inc/FUiCtrlScrollPanel.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FUiCtrlScrollPanel.h
  20  * @brief       This is the header file for the %ScrollPanel class.
  21  *
  22  * This header file contains the declarations of the %ScrollPanel class.
  23  */
  24
  25 #ifndef _FUI_CTRL_SCROLL_PANEL_H_
  26 #define _FUI_CTRL_SCROLL_PANEL_H_
  27
  28 #include <FBaseString.h>
  29 #include <FBaseTypes.h>
  30 #include <FUiCtrlForm.h>
  31 #include <FUiCtrlInputTypes.h>
  32 #include <FUiCtrlPanel.h>
  33 #include <FUiCtrlIScrollEventListener.h>
  34 #include <FUiCtrlScrollPanelTypes.h>
  35 #include <FUiCtrlTableViewTypes.h>
  36
  37 namespace Tizen { namespace Ui { namespace Controls
  38 {
  39 /**
  40  * @class       ScrollPanel
  41  * @brief       This class implements a scrollable container class.
  42  *
  43  * @since       2.0
  44  *
  45  * The %ScrollPanel class is a Panel with automatic scroll bars.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_panels.htm">Panels</a>.
  48  *
  49  * The following example demonstrates how to use the %ScrollPanel class.
  50  *
  51  * @code
  52 // Sample code for ScrollPanelSample.h
  53 #include <FUi.h>
  54
  55 class ScrollPanelSample
  56         : public Tizen::Ui::Controls::Form
  57 {
  58 public:
  59         ScrollPanelSample(void)
  60         : __pScrollPanel(null){}
  61
  62         bool Initialize(void);
  63         virtual result OnInitializing(void);
  64
  65 private:
  66         Tizen::Ui::Controls::ScrollPanel* __pScrollPanel;
  67 };
  68  *      @endcode
  69  *
  70  *      @code
  71 // Sample code for ScrollPanelSample.cpp
  72 #include <FGraphics.h>
  73
  74 #include "ScrollPanelSample.h"
  75
  76 using namespace Tizen::Graphics;
  77 using namespace Tizen::Ui::Controls;
  78
  79 bool
  80 ScrollPanelSample::Initialize(void)
  81 {
  82         Construct(FORM_STYLE_NORMAL);
  83         return true;
  84 }
  85
  86 result
  87 ScrollPanelSample::OnInitializing(void)
  88 {
  89         result r = E_SUCCESS;
  90
  91         // Creates an instance of ScrollPanel
  92         __pScrollPanel = new ScrollPanel();
  93         __pScrollPanel->Construct(Rectangle(100, 250, 400, 300));
  94         __pScrollPanel->SetBackgroundColor(Color::GetColor(COLOR_ID_YELLOW));
  95
  96         // Creates an instance of Button and an instance of EditField
  97         Button* pButton = new Button();
  98         pButton->Construct(Rectangle(0, 80, 200, 150), L"Button");
  99
 100         EditField* pEdit = new EditField();
 101         pEdit->Construct(Rectangle(0, 250, 200, 150));
 102         pEdit->SetText(L"Edit");
 103
 104         // Adds the button and the edit field to the ScrollPanel
 105         __pScrollPanel->AddControl(*pButton);
 106         __pScrollPanel->AddControl(*pEdit);
 107
 108         // Adds the ScrollPanel to the form
 109         AddControl(*__pScrollPanel);
 110
 111         return r;
 112 }
 113  * @endcode
 114  */
 115
 116 class _OSP_EXPORT_ ScrollPanel
 117         : public Panel
 118 {
 119
 120 // Lifecycle
 121 public:
 122         /**
 123          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 124          *
 125          * @since               2.0
 126          *
 127          */
 128         ScrollPanel(void);
 129
 130
 131         /**
 132          * This destructor overrides Tizen::Base::Object::~Object().
 133          *
 134          * @since               2.0
 135          *
 136          */
 137         virtual ~ScrollPanel(void);
 138
 139
 140         /**
 141          * Initializes this instance of %ScrollPanel with the specified rectangular region.
 142          *
 143          * @since               2.0
 144          *
 145          * @return              An error code
 146          * @param[in]   rect                    The location and size of the %ScrollPanel control
 147          * @exception   E_SUCCESS               The method is successful.
 148          * @exception   E_INVALID_ARG           The given width or height is less than 0.
 149          * @exception   E_SYSTEM                A system error has occurred.
 150          * @remarks             By default, the scroll direction is vertical and the scroll area is resized automatically.
 151          * @see                 Tizen::Ui::Container
 152          */
 153         result Construct(const Tizen::Graphics::Rectangle& rect);
 154
 155
 156         /**
 157          * Initializes this instance of %ScrollPanel and child controls with the specified resource ID @n
 158          *
 159          * This method first attempts to find the resource file in the folder that corresponds to the current screen resolution. @n
 160          * If it fails to find the resource file, it searches in other folders in the following order when CoordinateSystem is Logical in the application manifest file @n
 161          * the density folder that corresponds to the current screen size category  "res/screen-size-normal/" folder.
 162          *
 163          * @since 2.0
 164          *
 165          * @return           An error code
 166          * @param[in]  resourceId              The resource ID describing the %ScrollPanel control
 167          * @exception  E_SUCCESS               The method is successful.
 168          * @exception  E_FILE_NOT_FOUND        The specified file cannot be found.
 169          * @exception  E_INVALID_FORMAT        The specified XML format is invalid.
 170          * @exception  E_OPERATION_FAILED      The operation has failed.
 171          */
 172         result Construct(const Tizen::Base::String& resourceId);
 173
 174         /**
 175          * Initializes this instance of %ScrollPanel with the specified rectangular region.
 176          *
 177          * @since 2.0
 178          *
 179          * @return              An error code
 180          * @param[in]   rect                            The location and size of the %ScrollPanel control
 181          * @param[in]   scrollDirection                         The scroll direction of %ScrollPanel
 182          * @param[in]   autoResizingEnable                              Whether to resize the client area automatically
 183          * @exception   E_SUCCESS               The method is successful.
 184          * @exception   E_INVALID_ARG           The given width or height is less than 0.
 185          * @see                 Tizen::Ui::Container
 186          */
 187         result Construct(const Tizen::Graphics::Rectangle& rect, ScrollPanelScrollDirection scrollDirection, bool autoResizingEnable);
 188
 189
 190         /**
 191          * Initializes this instance of %ScrollPanel with the specified layout and rectangular region.
 192          *
 193          * @since               2.0
 194          *
 195          * @return              An error code
 196          * @param[in]   layout                          The layout for both the portrait and landscape mode
 197          * @param[in]   rect                            The location and size of the %ScrollPanel control
 198          * @exception   E_SUCCESS               The method is successful.
 199          * @exception   E_INVALID_ARG           @c layout is already bound to another container, or the given width or the height is less than 0.
 200          * @exception   E_SYSTEM                A system error has occurred.
 201          * @remarks             By default, the scroll direction is vertical and the scroll area is resized automatically.
 202          * @see                 Tizen::Ui::Container
 203          */
 204         result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::Rectangle& rect);
 205
 206
 207         /**
 208          * Initializes this instance of %ScrollPanel with the specified layout and rectangular region.
 209          *
 210          * @since 2.0
 211          *
 212          * @return              An error code
 213          * @param[in]   layout                          The layout for both the portrait and landscape mode
 214          * @param[in]   rect                            The location and size of the %ScrollPanel control
 215          * @param[in]   scrollDirection                         The scroll direction of %ScrollPanel
 216          * @param[in]   autoResizingEnable                              Whether to resize the client area automatically
 217          * @exception   E_SUCCESS               The method is successful.
 218          * @exception   E_INVALID_ARG           @c layout is already bound to another container, or the given width or height is less than 0.
 219          * @see                 Tizen::Ui::Container
 220          */
 221         result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::Rectangle& rect, ScrollPanelScrollDirection scrollDirection, bool autoResizingEnable);
 222
 223
 224         /**
 225          * Initializes this instance of %ScrollPanel with the specified layouts and rectangular region.
 226          *
 227          * @since               2.0
 228          *
 229          * @return              An error code
 230          * @param[in]   portraitLayout          The layout for the portrait mode
 231          * @param[in]   landscapeLayout         The layout for the landscape mode
 232          * @param[in]   rect                            The location and size of the %ScrollPanel control
 233          * @exception   E_SUCCESS               The method is successful.
 234          * @exception   E_INVALID_ARG           @c portraitLayout or @c landscapeLayout is already bound to another container, or the given width or height is less than 0.
 235          * @exception   E_SYSTEM                A system error has occurred.
 236          * @remarks             By default, the scroll direction is vertical and the scroll area is resized automatically.
 237          * @see                 Tizen::Ui::Container
 238          */
 239         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::Rectangle& rect);
 240
 241
 242         /**
 243          * Initializes this instance of %ScrollPanel with the specified layouts and rectangular region.
 244          *
 245          * @since 2.0
 246          *
 247          * @return              An error code
 248          * @param[in]   portraitLayout          The layout for the portrait mode
 249          * @param[in]   landscapeLayout         The layout for the landscape mode
 250          * @param[in]   rect                            The location and size of the %ScrollPanel control
 251          * @param[in]   scrollDirection                         The scroll direction of %ScrollPanel
 252          * @param[in]   autoResizingEnable                              Whether to resize the client area automatically
 253          * @exception   E_SUCCESS               The method is successful.
 254          * @exception   E_INVALID_ARG           @c portraitLayout or @c landscapeLayout is already bound to another container, or the given width or height is less than 0.
 255          * @see                 Tizen::Ui::Container
 256          */
 257         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::Rectangle& rect, ScrollPanelScrollDirection scrollDirection, bool autoResizingEnable);
 258
 259
 260         /**
 261          * Adds a listener instance that listens to the state changes of a scroll event. @n
 262          * The added listener can listen to the events on the given event dispatcher's context when they are fired.
 263          *
 264          * @since                       2.0
 265          *
 266          * @param[in]   listener The listener to add
 267          * @exception   E_SUCCESS       The method is successful.
 268          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 269          * @see                         IScrollEventListener::OnScrollEndReached()
 270          * @see                         RemoveScrollEventListener()
 271          */
 272         void AddScrollEventListener(IScrollEventListener& listener);
 273
 274
 275         /**
 276          * Removes a listener instance that listens to the state changes of a scroll event. @n
 277          * The removed listener cannot listen to the events when they are fired.
 278          *
 279          * @since               2.0
 280          *
 281          * @param[in]   listener   The listener to remove
 282          * @see                 IScrollEventListener::OnScrollEndReached()
 283          * @see                 AddScrollEventListener()
 284          */
 285         void RemoveScrollEventListener(IScrollEventListener& listener);
 286
 287
 288         /**
 289          * Gets the scroll position.
 290          *
 291          * @since               2.0
 292          *
 293          * @return              The scroll position
 294          */
 295         int GetScrollPosition(void) const;
 296
 297
 298         /**
 299          * @if OSPDEPREC
 300          * Sets the scroll position.
 301          *
 302          * @brief <i> [Deprecated]  </i>
 303          * @deprecated  This method is deprecated. Instead of using this method, use the SetScrollPosition(int, bool), which supports animated scroll.
 304          * @since               2.0
 305          *
 306          * @param[in]   position                The scroll position
 307          * @endif
 308          */
 309         void SetScrollPosition(int position);
 310
 311         /**
 312          * Sets the scroll position.
 313          *
 314          * @since 2.0
 315          *
 316          * @param[in]   position                The scroll position in pixel
 317          * @param[in]   withAnimation           @c true to scroll the %ScrollPanel smoothly. @n
 318          *                                                                                                      else @c false.
 319          *
 320          */
 321         void SetScrollPosition(int position, bool withAnimation);
 322
 323         /**
 324          * Scrolls to the bottom of %ScrollPanel.
 325          *
 326          * @since               2.0
 327          */
 328         void ScrollToBottom(void) const;
 329
 330
 331         /**
 332          * Scrolls to the top of %ScrollPanel.
 333          *
 334          * @since               2.0
 335          */
 336         void ScrollToTop(void) const;
 337
 338
 339         /**
 340          * Closes the overlay Window for supporting the overlay keypad.
 341          *
 342          * @since               2.0
 343          *
 344          * @exception   E_SUCCESS               The method is successful.
 345          * @exception   E_SYSTEM                A system error has occurred.
 346          */
 347         result CloseOverlayWindow(void);
 348
 349
 350         /**
 351          * Gets the bounds of the client area.
 352          *
 353          * @since               2.0
 354          *
 355          * @return              The bounds of the client area
 356          *
 357          */
 358         Tizen::Graphics::Rectangle GetClientAreaBounds(void) const;
 359
 360
 361         /**
 362          * Sets the width of the client area.
 363          *
 364          * @since 2.0
 365          *
 366          * @return                   An error code
 367          * @param[in]     width                        The width of the client area to set
 368          * @exception     E_SUCCESS                   The method is successful.
 369          * @exception     E_INVALID_ARG             @c width is less than the width of %ScrollPanel
 370          * @exception     E_INVALID_OPERATION    The width of the client area cannot be set when auto resizing of the client area is off, or the scroll direction is vertical.
 371          *
 372          */
 373         result SetClientAreaWidth(int width);
 374
 375
 376         /**
 377          * Sets the height of the client area.
 378          *
 379          * @since 2.0
 380          *
 381          * @return                   An error code
 382          * @param[in]     height                        The height of the client area to set
 383          * @exception     E_SUCCESS                   The method is successful.
 384          * @exception     E_INVALID_ARG             @c height is less than the height of %ScrollPanel
 385          * @exception     E_INVALID_OPERATION    The height of the client area cannot be set when auto resizing of the client area is off, or the scroll direction is horizontal.
 386          *
 387          */
 388         result SetClientAreaHeight(int height);
 389
 390
 391         /**
 392          * Gets the scroll direction of the %ScrollPanel.
 393          *
 394          * @since 2.0
 395          *
 396          * @return        Direction of %ScrollPanel
 397          *
 398          */
 399         ScrollPanelScrollDirection GetScrollDirection(void) const;
 400
 401
 402         /**
 403          * Gets how the scroll area the %ScrollPanel is resized.
 404          *
 405          * @since 2.0
 406          *
 407          * @return        Whether to resize the client area automatically
 408          *
 409          */
 410         bool IsScrollAreaAutoResizingEnabled(void) const;
 411
 412
 413         /**
 414          * Enables or disables scrolling by page, where page size is determined by the size of the %ScrollPanel.
 415          *
 416          * @since 2.0
 417          *
 418          * @param[in]     enable                Set to @c true to enable page scroll.
 419          *
 420          */
 421         void SetPageScrollEnabled(bool enable);
 422
 423
 424         /**
 425          * Checks whether scrolling by page feature is enabled.
 426          *
 427          * @since 2.0
 428          *
 429          * @return              @c true if the page scroll is enabled. @n
 430          *                                              else @c false.
 431          *
 432          */
 433         bool IsPageScrollEnabled(void) const;
 434
 435
 436         /**
 437          * Sets the visibility of scroll bar.
 438          *
 439          * @since 2.0
 440          *
 441          * @param[in]   visible         Set to @c true to show scroll bar. @n
 442          *                                                                              else @c false.
 443          *
 444          */
 445         void SetScrollBarVisible(bool visible);
 446
 447
 448         /**
 449          * Gets the visibility of scroll bar.
 450          *
 451          * @since 2.0
 452          *
 453          */
 454         bool IsScrollBarVisible(void) const;
 455
 456
 457         /**
 458          * Sets the scroll input handling mode.
 459          *
 460          * @since 2.0
 461          *
 462          * @param[in] mode  The scroll input handling mode
 463          *  @see         GetScrollInputMode()
 464          */
 465         void SetScrollInputMode(ScrollInputMode mode);
 466
 467
 468         /**
 469          * Gets the scroll input handling mode.
 470          *
 471          * @since 2.0
 472          *
 473          * @return     The scroll input handling mode
 474          * @see         SetScrollInputMode()
 475          */
 476         ScrollInputMode GetScrollInputMode(void) const;
 477
 478
 479 protected:
 480
 481         friend class _ScrollPanelImpl;
 482
 483         // Reserved virtual methods for later extension
 484
 485         // The following methods are reserved and may change its name at any time without prior notice.
 486         virtual void ScrollPanel_Reserved1(void) {}
 487
 488         virtual void ScrollPanel_Reserved2(void) {}
 489
 490         virtual void ScrollPanel_Reserved3(void) {}
 491
 492 private:
 493         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 494         ScrollPanel(const ScrollPanel& rhs);
 495
 496         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 497         ScrollPanel& operator =(const ScrollPanel& rhs);
 498
 499 }; // ScrollPanel
 500
 501 }}} // Tizen::Ui::Controls
 502
 503 #endif // _FUI_CTRL_SCROLL_PANEL_H_