2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.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
9 // http://www.apache.org/licenses/LICENSE-2.0/
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.
19 * @file FUiCtrlScrollPanel.h
20 * @brief This is the header file for the %ScrollPanel class.
22 * This header file contains the declarations of the %ScrollPanel class.
25 #ifndef _FUI_CTRL_SCROLL_PANEL_H_
26 #define _FUI_CTRL_SCROLL_PANEL_H_
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 <FUiCtrlIScrollEventListenerF.h>
35 #include <FUiCtrlScrollPanelTypes.h>
37 namespace Tizen { namespace Ui { namespace Controls
41 * @brief This class implements a scrollable container class.
45 * The %ScrollPanel class is a Panel with automatic scroll bars.
47 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_panels.htm">Panels</a>.
49 * The following example demonstrates how to use the %ScrollPanel class.
52 // Sample code for ScrollPanelSample.h
55 class ScrollPanelSample
56 : public Tizen::Ui::Controls::Form
59 ScrollPanelSample(void)
60 : __pScrollPanel(null){}
62 bool Initialize(void);
63 virtual result OnInitializing(void);
66 Tizen::Ui::Controls::ScrollPanel* __pScrollPanel;
71 // Sample code for ScrollPanelSample.cpp
72 #include <FGraphics.h>
74 #include "ScrollPanelSample.h"
76 using namespace Tizen::Graphics;
77 using namespace Tizen::Ui::Controls;
80 ScrollPanelSample::Initialize(void)
82 Construct(FORM_STYLE_NORMAL);
87 ScrollPanelSample::OnInitializing(void)
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));
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");
100 EditField* pEdit = new EditField();
101 pEdit->Construct(Rectangle(0, 250, 200, 150));
102 pEdit->SetText(L"Edit");
104 // Adds the button and the edit field to the ScrollPanel
105 __pScrollPanel->AddControl(pButton);
106 __pScrollPanel->AddControl(pEdit);
108 // Adds the ScrollPanel to the form
109 AddControl(__pScrollPanel);
116 class _OSP_EXPORT_ ScrollPanel
123 * The object is not fully constructed after this constructor is called. @n
124 * For full construction, the %Construct() method must be called right after calling this constructor.
133 * This destructor overrides Tizen::Base::Object::~Object().
138 virtual ~ScrollPanel(void);
142 * Initializes this instance of %ScrollPanel with the specified rectangular region.
146 * @return An error code
147 * @param[in] rect The location and size of the %ScrollPanel control
148 * @exception E_SUCCESS The method is successful.
149 * @exception E_INVALID_ARG The given width or height is less than 0.
150 * @exception E_SYSTEM A system error has occurred.
151 * @remarks By default, the scroll direction is vertical and the scroll area is resized automatically.
152 * @see Tizen::Ui::Container
154 result Construct(const Tizen::Graphics::Rectangle& rect);
158 * Initializes this instance of %ScrollPanel with the specified rectangular region.
162 * @return An error code
163 * @param[in] rect The location and size of the %ScrollPanel control
164 * @exception E_SUCCESS The method is successful.
165 * @exception E_INVALID_ARG The given width or height is less than 0.
166 * @exception E_SYSTEM A system error has occurred.
167 * @remarks By default, the scroll direction is vertical and the scroll area is resized automatically.
168 * @see Tizen::Ui::Container
170 result Construct(const Tizen::Graphics::FloatRectangle& rect);
174 * Initializes this instance of %ScrollPanel and child controls with the specified resource ID @n
175 * This method first attempts to find the resource file in the folder that corresponds to the current screen resolution. @n
176 * 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
177 * the density folder that corresponds to the current screen size category "res/screen-size-normal/" folder.
181 * @return An error code
182 * @param[in] resourceId The resource ID describing the %ScrollPanel control
183 * @exception E_SUCCESS The method is successful.
184 * @exception E_FILE_NOT_FOUND The specified file cannot be found.
185 * @exception E_INVALID_FORMAT The specified XML format is invalid.
186 * @exception E_OPERATION_FAILED The operation has failed.
187 * @remarks If SetBounds(), SetSize(), SetPosition() methods are called before the control is added to the parent via AddControl(), then the new value is applied
188 * to both orientations because the current orientation is not known. After AddControl() is called, then the values are applied only to the current orientation.
190 result Construct(const Tizen::Base::String& resourceId);
194 * Initializes this instance of %ScrollPanel with the specified rectangular region.
198 * @return An error code
199 * @param[in] rect The location and size of the %ScrollPanel control
200 * @param[in] scrollDirection The scroll direction of %ScrollPanel
201 * @param[in] autoResizingEnable Whether to resize the client area automatically
202 * @exception E_SUCCESS The method is successful.
203 * @exception E_INVALID_ARG The given width or height is less than 0.
204 * @see Tizen::Ui::Container
206 result Construct(const Tizen::Graphics::Rectangle& rect, ScrollPanelScrollDirection scrollDirection, bool autoResizingEnable);
210 * Initializes this instance of %ScrollPanel with the specified rectangular region.
214 * @return An error code
215 * @param[in] rect The location and size of the %ScrollPanel control
216 * @param[in] scrollDirection The scroll direction of %ScrollPanel
217 * @param[in] autoResizingEnable Whether to resize the client area automatically
218 * @exception E_SUCCESS The method is successful.
219 * @exception E_INVALID_ARG The given width or height is less than 0.
220 * @see Tizen::Ui::Container
222 result Construct(const Tizen::Graphics::FloatRectangle& rect, ScrollPanelScrollDirection scrollDirection, bool autoResizingEnable);
226 * Initializes this instance of %ScrollPanel with the specified layout and rectangular region.
230 * @return An error code
231 * @param[in] layout The layout for both the portrait and 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 layout is already bound to another container, or the given width or the 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
239 result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::Rectangle& rect);
243 * Initializes this instance of %ScrollPanel with the specified layout and rectangular region.
247 * @return An error code
248 * @param[in] layout The layout for both the portrait and landscape mode
249 * @param[in] rect The location and size of the %ScrollPanel control
250 * @exception E_SUCCESS The method is successful.
251 * @exception E_INVALID_ARG @c layout is already bound to another container, or the given width or the height is less than 0.
252 * @exception E_SYSTEM A system error has occurred.
253 * @remarks By default, the scroll direction is vertical and the scroll area is resized automatically.
254 * @see Tizen::Ui::Container
256 result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::FloatRectangle& rect);
260 * Initializes this instance of %ScrollPanel with the specified layout and rectangular region.
264 * @return An error code
265 * @param[in] layout The layout for both the portrait and landscape mode
266 * @param[in] rect The location and size of the %ScrollPanel control
267 * @param[in] scrollDirection The scroll direction of %ScrollPanel
268 * @param[in] autoResizingEnable Whether to resize the client area automatically
269 * @exception E_SUCCESS The method is successful.
270 * @exception E_INVALID_ARG @c layout is already bound to another container, or the given width or height is less than 0.
271 * @see Tizen::Ui::Container
273 result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::Rectangle& rect, ScrollPanelScrollDirection scrollDirection, bool autoResizingEnable);
277 * Initializes this instance of %ScrollPanel with the specified layout and rectangular region.
281 * @return An error code
282 * @param[in] layout The layout for both the portrait and landscape mode
283 * @param[in] rect The location and size of the %ScrollPanel control
284 * @param[in] scrollDirection The scroll direction of %ScrollPanel
285 * @param[in] autoResizingEnable Whether to resize the client area automatically
286 * @exception E_SUCCESS The method is successful.
287 * @exception E_INVALID_ARG @c layout is already bound to another container, or the given width or height is less than 0.
288 * @see Tizen::Ui::Container
290 result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::FloatRectangle& rect, ScrollPanelScrollDirection scrollDirection, bool autoResizingEnable);
294 * Initializes this instance of %ScrollPanel with the specified layouts and rectangular region.
298 * @return An error code
299 * @param[in] portraitLayout The layout for the portrait mode
300 * @param[in] landscapeLayout The layout for the landscape mode
301 * @param[in] rect The location and size of the %ScrollPanel control
302 * @exception E_SUCCESS The method is successful.
303 * @exception E_INVALID_ARG @c portraitLayout or @c landscapeLayout is already bound to another container, or the given width or
304 * height is less than @c 0.
305 * @exception E_SYSTEM A system error has occurred.
306 * @remarks By default, the scroll direction is vertical and the scroll area is resized automatically.
307 * @see Tizen::Ui::Container
309 result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::Rectangle& rect);
313 * Initializes this instance of %ScrollPanel with the specified layouts and rectangular region.
317 * @return An error code
318 * @param[in] portraitLayout The layout for the portrait mode
319 * @param[in] landscapeLayout The layout for the landscape mode
320 * @param[in] rect The location and size of the %ScrollPanel control
321 * @exception E_SUCCESS The method is successful.
322 * @exception E_INVALID_ARG @c portraitLayout or @c landscapeLayout is already bound to another container, or the given width or
323 * height is less than @c 0.
324 * @exception E_SYSTEM A system error has occurred.
325 * @remarks By default, the scroll direction is vertical and the scroll area is resized automatically.
326 * @see Tizen::Ui::Container
328 result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::FloatRectangle& rect);
332 * Initializes this instance of %ScrollPanel with the specified layouts and rectangular region.
336 * @return An error code
337 * @param[in] portraitLayout The layout for the portrait mode
338 * @param[in] landscapeLayout The layout for the landscape mode
339 * @param[in] rect The location and size of the %ScrollPanel control
340 * @param[in] scrollDirection The scroll direction of %ScrollPanel
341 * @param[in] autoResizingEnable Whether to resize the client area automatically
342 * @exception E_SUCCESS The method is successful.
343 * @exception E_INVALID_ARG @c portraitLayout or @c landscapeLayout is already bound to another container, or the given width or
344 * height is less than @c 0.
345 * @see Tizen::Ui::Container
347 result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::Rectangle& rect, ScrollPanelScrollDirection scrollDirection, bool autoResizingEnable);
351 * Initializes this instance of %ScrollPanel with the specified layouts and rectangular region.
355 * @return An error code
356 * @param[in] portraitLayout The layout for the portrait mode
357 * @param[in] landscapeLayout The layout for the landscape mode
358 * @param[in] rect The location and size of the %ScrollPanel control
359 * @param[in] scrollDirection The scroll direction of %ScrollPanel
360 * @param[in] autoResizingEnable Whether to resize the client area automatically
361 * @exception E_SUCCESS The method is successful.
362 * @exception E_INVALID_ARG @c portraitLayout or @c landscapeLayout is already bound to another container, or
363 * the given width or height is less than 0.
364 * @see Tizen::Ui::Container
366 result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::FloatRectangle& rect, ScrollPanelScrollDirection scrollDirection, bool autoResizingEnable);
370 * Adds a listener instance that listens to the state changes of a scroll event. @n
371 * The added listener can listen to the events on the given event dispatcher's context when they are fired.
375 * @param[in] listener The listener to add
376 * @exception E_SUCCESS The method is successful.
377 * @exception E_OUT_OF_MEMORY The memory is insufficient.
378 * @see Tizen::Ui::Controls::IScrollEventListener
379 * @see RemoveScrollEventListener()
381 void AddScrollEventListener(IScrollEventListener& listener);
385 * Adds a listener instance that listens to the state changes of a scroll event. @n
386 * The added listener can listen to the events on the given event dispatcher's context when they are fired.
390 * @param[in] listener The listener to add
391 * @exception E_SUCCESS The method is successful.
392 * @exception E_OUT_OF_MEMORY The memory is insufficient.
393 * @see Tizen::Ui::Controls::IScrollEventListenerF
394 * @see RemoveScrollEventListener()
396 void AddScrollEventListener(IScrollEventListenerF& listener);
400 * Removes a listener instance that listens to the state changes of a scroll event. @n
401 * The removed listener cannot listen to the events when they are fired.
405 * @param[in] listener The listener to remove
406 * @see Tizen::Ui::Controls::IScrollEventListener
407 * @see AddScrollEventListener()
409 void RemoveScrollEventListener(IScrollEventListener& listener);
413 * Removes a listener instance that listens to the state changes of a scroll event. @n
414 * The removed listener cannot listen to the events when they are fired.
418 * @param[in] listener The listener to remove
419 * @see Tizen::Ui::Controls::IScrollEventListenerF
420 * @see AddScrollEventListener()
422 void RemoveScrollEventListener(IScrollEventListenerF& listener);
426 * Gets the scroll position.
430 * @return The scroll position
432 int GetScrollPosition(void) const;
436 * Gets the scroll position.
440 * @return The scroll position
442 float GetScrollPositionF(void) const;
447 * Sets the scroll position.
449 * @brief <i> [Deprecated] </i>
450 * @deprecated This method is deprecated. Instead of using this method, use the SetScrollPosition(int, bool), which supports animated scroll.
453 * @param[in] position The scroll position
456 void SetScrollPosition(int position);
460 * Sets the scroll position.
464 * @param[in] position The scroll position in pixel
465 * @param[in] withAnimation @c true to scroll the %ScrollPanel smoothly. @n
469 void SetScrollPosition(int position, bool withAnimation);
473 * Sets the scroll position.
477 * @param[in] position The scroll position in pixel
478 * @param[in] withAnimation @c true to scroll the %ScrollPanel smoothly. @n
482 void SetScrollPosition(float position, bool withAnimation);
486 * Scrolls to the bottom of %ScrollPanel.
490 void ScrollToBottom(void) const;
494 * Scrolls to the top of %ScrollPanel.
498 void ScrollToTop(void) const;
502 * Closes the overlay Window for supporting the overlay keypad.
506 * @exception E_SUCCESS The method is successful.
507 * @exception E_SYSTEM A system error has occurred.
509 result CloseOverlayWindow(void);
513 * Gets the bounds of the client area.
517 * @return The bounds of the client area
520 Tizen::Graphics::Rectangle GetClientAreaBounds(void) const;
524 * Gets the bounds of the client area.
528 * @return The bounds of the client area
531 Tizen::Graphics::FloatRectangle GetClientAreaBoundsF(void) const;
535 * Sets the width of the client area.
539 * @return An error code
540 * @param[in] width The width of the client area to set
541 * @exception E_SUCCESS The method is successful.
542 * @exception E_INVALID_ARG @c width is less than the width of %ScrollPanel
543 * @exception E_INVALID_OPERATION The width of the client area cannot be set when auto resizing of the client area is on,
544 * or the scroll direction is vertical.
547 result SetClientAreaWidth(int width);
551 * Sets the width of the client area.
555 * @return An error code
556 * @param[in] width The width of the client area to set
557 * @exception E_SUCCESS The method is successful.
558 * @exception E_INVALID_ARG @c width is less than the width of %ScrollPanel
559 * @exception E_INVALID_OPERATION The width of the client area cannot be set when auto resizing of the client area is on,
560 * or the scroll direction is vertical.
563 result SetClientAreaWidth(float width);
567 * Sets the height of the client area.
571 * @return An error code
572 * @param[in] height The height of the client area to set
573 * @exception E_SUCCESS The method is successful.
574 * @exception E_INVALID_ARG @c height is less than the height of %ScrollPanel
575 * @exception E_INVALID_OPERATION The height of the client area cannot be set when auto resizing of the client area is on,
576 * or the scroll direction is horizontal.
579 result SetClientAreaHeight(int height);
583 * Sets the height of the client area.
587 * @return An error code
588 * @param[in] height The height of the client area to set
589 * @exception E_SUCCESS The method is successful.
590 * @exception E_INVALID_ARG @c height is less than the height of %ScrollPanel
591 * @exception E_INVALID_OPERATION The height of the client area cannot be set when auto resizing of the client area is on,
592 * or the scroll direction is horizontal.
595 result SetClientAreaHeight(float height);
599 * Gets the scroll direction of the %ScrollPanel.
603 * @return Direction of %ScrollPanel
606 ScrollPanelScrollDirection GetScrollDirection(void) const;
610 * Gets how the scroll area the %ScrollPanel is resized.
614 * @return Whether to resize the client area automatically
617 bool IsScrollAreaAutoResizingEnabled(void) const;
621 * Enables or disables scrolling by page, where page size is determined by the size of the %ScrollPanel.
625 * @param[in] enable Set to @c true to enable page scroll.
628 void SetPageScrollEnabled(bool enable);
632 * Checks whether scrolling by page feature is enabled.
636 * @return @c true if the page scroll is enabled. @n
640 bool IsPageScrollEnabled(void) const;
644 * Sets the visibility of scroll bar.
648 * @param[in] visible Set to @c true to show scroll bar. @n
652 void SetScrollBarVisible(bool visible);
656 * Gets the visibility of scroll bar.
661 bool IsScrollBarVisible(void) const;
665 * Sets the scroll input handling mode.
669 * @param[in] mode The scroll input handling mode
670 * @see GetScrollInputMode()
672 void SetScrollInputMode(ScrollInputMode mode);
676 * Gets the scroll input handling mode.
680 * @return The scroll input handling mode
681 * @see SetScrollInputMode()
683 ScrollInputMode GetScrollInputMode(void) const;
688 friend class _ScrollPanelImpl;
690 // Reserved virtual methods for later extension
692 // The following methods are reserved and may change its name at any time without prior notice.
693 virtual void ScrollPanel_Reserved1(void) {}
695 virtual void ScrollPanel_Reserved2(void) {}
697 virtual void ScrollPanel_Reserved3(void) {}
700 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
701 ScrollPanel(const ScrollPanel& rhs);
703 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
704 ScrollPanel& operator =(const ScrollPanel& rhs);
708 }}} // Tizen::Ui::Controls
710 #endif // _FUI_CTRL_SCROLL_PANEL_H_