inc/FUiCtrlSplitPanel.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         FUiCtrlSplitPanel.h
  20 * @brief        This is the header file for the %SplitPanel class.
  21 *
  22 * This header file contains the declarations of the %SplitPanel class.
  23 */
  24 #ifndef _FUI_CTRL_SPLIT_PANEL_H_
  25 #define _FUI_CTRL_SPLIT_PANEL_H_
  26
  27 #include <FBaseTypes.h>
  28 #include <FGrpRectangle.h>
  29 #include <FUiControl.h>
  30 #include <FUiCtrlSplitPanelTypes.h>
  31
  32
  33 namespace Tizen { namespace Ui { namespace Controls
  34 {
  35
  36 class ISplitPanelEventListener;
  37 class ISplitPanelEventListenerF;
  38
  39 /**
  40  * @class       SplitPanel
  41  * @brief       This class is an implementation of a %SplitPanel control.
  42  *
  43  * @since 2.0
  44  * @final       This class is not intended for extension.
  45  *
  46  * The %SplitPanel class provides the functionality of a %SplitPanel which is a control that contains two panes.
  47  *
  48  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_splitpanel.htm">SplitPanel</a>.
  49  *
  50  * The following example demonstrates how to use the %SplitPanel class.
  51  *
  52  * @code
  53 // Sample code for SplitPanel.h
  54 #include <FUi.h>
  55
  56 class SplitPanelSample
  57         : public Tizen::Ui::Controls::Form
  58         , public Tizen::Ui::Controls::ISplitPanelEventListener
  59 {
  60 public:
  61         SplitPanelSample(void)
  62         : __pSplitPanel(null)
  63         , __pFirstPanel(null)
  64         , __pSecondPanel(null){}
  65
  66         virtual result OnInitializing(void);
  67         virtual result OnTerminating(void);
  68
  69 private:
  70         Tizen::Ui::Controls::SplitPanel* __pSplitPanel;
  71         Tizen::Ui::Controls::Panel* __pFirstPanel;
  72         Tizen::Ui::Controls::Panel* __pSecondPanel;
  73 };
  74  * @endcode
  75  *
  76  * @code
  77 // Sample code for SplitPanelSample.cpp
  78 #include <FGraphics.h>
  79
  80 #include "SplitPanelSample.h"
  81
  82 using namespace Tizen::Graphics;
  83 using namespace Tizen::Ui;
  84 using namespace Tizen::Ui::Controls;
  85
  86 bool
  87 SplitPanelSample::Initialize(void)
  88 {
  89         Construct(FORM_STYLE_NORMAL);
  90         return true;
  91 }
  92
  93 result
  94 SplitPanelSample::OnInitializing(void)
  95 {
  96         // Creates an instance of SplitPanel
  97         __pSplitPanel = new (std::nothrow) SplitPanel();
  98         __pSplitPanel->Construct(Rectangle(0, 0, 800, 400),
  99                         SPLIT_PANEL_DIVIDER_STYLE_MOVABLE, SPLIT_PANEL_DIVIDER_DIRECTION_VERTICAL);
 100
 101         // Creates instances of Panel
 102         __pFirstPanel = new (std::nothrow) Panel();
 103         __pFirstPanel->Construct(Rectangle(0, 0, 400, 480));
 104
 105         __pSecondPanel = new (std::nothrow) Panel();
 106         __pSecondPanel->Construct(Rectangle(0, 0, 400, 480));
 107
 108         //Sets the divider position to the slit panel
 109         __pSplitPanel->SetDividerPosition(400);
 110
 111         //Sets panes to the split panel
 112         __pSplitPanel->SetPane(__pFirstPanel, SPLIT_PANEL_PANE_ORDER_FIRST);
 113         __pSplitPanel->SetPane(__pSecondPanel, SPLIT_PANEL_PANE_ORDER_SECOND);
 114
 115         // Adds the split panel to the form
 116         AddControl(*__pSplitPanel);
 117
 118         return E_SUCCESS;
 119 }
 120
 121  result
 122  SplitPanelSample::OnTerminating(void)
 123  {
 124         // Sets null panes to the split panel
 125          __pSplitPanel->SetPane(null, SPLIT_PANEL_PANE_ORDER_FIRST);
 126          __pSplitPanel->SetPane(null, SPLIT_PANEL_PANE_ORDER_SECOND);
 127
 128         //Deallocates the control
 129          __pFirstPanel->Destroy();
 130          __pSecondPanel->Destroy();
 131
 132          return E_SUCCESS;
 133  }
 134
 135  * @endcode
 136  *
 137  */
 138
 139 class _OSP_EXPORT_ SplitPanel
 140         : public Tizen::Ui::Control
 141 {
 142 public:
 143         /**
 144          * 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.
 145          *
 146          * @since 2.0
 147          */
 148         SplitPanel(void);
 149
 150         /**
 151          * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called when the destructor of this interface is called.
 152          *
 153          * @since 2.0
 154          */
 155         virtual ~SplitPanel(void);
 156
 157         /**
 158          * Initializes this instance of %SplitPanel with the specified parameters.
 159          *
 160          * @since 2.0
 161          *
 162          * @return              An error code
 163          * @param[in]   rect                                            The location and size of the %SplitPanel control as a Rectangle instance.
 164          * @param[in]   splitPanelDividerStyle          The divider style of the %SplitPanel control
 165          * @param[in]   splitPanelDividerDirection      The divider direction of the %SplitPanel control @n
 166          *                                                                                      The specified divider direction determines the divider is vertical or horizontal.
 167          * @exception   E_SUCCESS                                       The method is successful.
 168          * @exception   E_INVALID_ARG                           A specified input parameter is invalid.
 169          */
 170         result Construct(const Tizen::Graphics::Rectangle& rect, SplitPanelDividerStyle splitPanelDividerStyle, SplitPanelDividerDirection splitPanelDividerDirection);
 171
 172         /**
 173          * Initializes this instance of %SplitPanel with the specified parameters.
 174          *
 175          * @since 2.1
 176          *
 177          * @return              An error code
 178          * @param[in]   rect                                            The location and size of the %SplitPanel control as a FloatRectangle instance.
 179          * @param[in]   splitPanelDividerStyle          The divider style of the %SplitPanel control
 180          * @param[in]   splitPanelDividerDirection      The divider direction of the %SplitPanel control @n
 181          *                                                                                      The specified divider direction determines the divider is vertical or horizontal.
 182          * @exception   E_SUCCESS                                       The method is successful.
 183          * @exception   E_INVALID_ARG                           A specified input parameter is invalid.
 184          */
 185         result Construct(const Tizen::Graphics::FloatRectangle& rect, SplitPanelDividerStyle splitPanelDividerStyle, SplitPanelDividerDirection splitPanelDividerDirection);
 186
 187
 188         /**
 189          * Adds a ISplitPanelEventListener instance. @n
 190          * The added listener listens to events on the context of the specified event dispatcher when they are fired.
 191          *
 192          * @since 2.0
 193          *
 194          * @param[in]   listener                        The event listener to be added
 195          * @exception   E_SUCCESS                               The method is successful.
 196          * @exception   E_OBJ_ALREADY_EXIST             The event listener already exists.
 197          */
 198         result AddSplitPanelEventListener(ISplitPanelEventListener& listener);
 199
 200         /**
 201          * Adds a ISplitPanelEventListenerF instance. @n
 202          * The added listener listens to events on the context of the specified event dispatcher when they are fired.
 203          *
 204          * @since 2.1
 205          *
 206          * @param[in]   listener                        The event listener to be added
 207          * @exception   E_SUCCESS                               The method is successful.
 208          * @exception   E_OBJ_ALREADY_EXIST             The event listener already exists.
 209          */
 210         result AddSplitPanelEventListener(ISplitPanelEventListenerF& listener);
 211
 212         /**
 213          * Removes a ISplitPanelEventListener instance. @n
 214          * The removed listener cannot listen to events when they are fired.
 215          *
 216          * @since 2.0
 217          *
 218          * @param[in]   listener                The event listener to be removed
 219          * @exception   E_SUCCESS                       The method is successful.
 220          * @exception   E_OBJ_NOT_FOUND         The event listener is not found.
 221          */
 222         result RemoveSplitPanelEventListener(ISplitPanelEventListener& listener);
 223
 224         /**
 225          * Removes a ISplitPanelEventListenerF instance. @n
 226          * The removed listener cannot listen to events when they are fired.
 227          *
 228          * @since 2.1
 229          *
 230          * @param[in]   listener                The event listener to be removed
 231          * @exception   E_SUCCESS                       The method is successful.
 232          * @exception   E_OBJ_NOT_FOUND         The event listener is not found.
 233          */
 234         result RemoveSplitPanelEventListener(ISplitPanelEventListenerF& listener);
 235
 236         /**
 237          * Sets the pane to the %SplitPanel control.
 238          *
 239          * @since 2.0
 240          *
 241          * @return              An error code
 242          * @param[in]   pControl                The control to be set.
 243          * @param[in]   paneOrder               The order of pane. SPLIT_PANEL_PANE_FIRST is displayed on the left side @n
 244          *                                                                      and SPLIT_PANEL_PANE_SECOND is displayed on the right side of the %SplitPanel when its direction is SPLIT_PANEL_DIVIDER_DIRECTION_VERTICAL.
 245          * @exception   E_SUCCESS                       The method is successful.
 246          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 247          * @remarks             The %SplitPanel control must contain exactly two panes and the user can change their relative sizes.
 248          */
 249         result SetPane(Control* pControl, SplitPanelPaneOrder paneOrder);
 250
 251         /**
 252          * Gets the control at the specified pane order of the %SplitPanel.
 253          *
 254          * @since 2.0
 255          *
 256          * @return              The control at the specified pane order of the %SplitPanel @n
 257          *              @c null, if there is no panel.
 258          * @param[in]   paneOrder                       The order of pane. SPLIT_PANEL_PANE_FIRST is displayed on the left side @n
 259          *                                                                      and SPLIT_PANEL_PANE_SECOND is displayed on the right side of the %SplitPanel when its direction is SPLIT_PANEL_DIVIDER_DIRECTION_VERTICAL.
 260          * @exception   E_SUCCESS                       The method is successful.
 261          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 262          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 263          */
 264         Control* GetPane(SplitPanelPaneOrder paneOrder) const;
 265
 266         /**
 267          * Sets the divider position of the control.
 268          *
 269          * @since 2.0
 270          *
 271          * @return                      An error code
 272          * @param[in]           position                                The position of divider
 273          * @exception           E_SUCCESS                               The method is successful.
 274          * @exception           E_OUT_OF_RANGE                  A specified input parameter is invalid.
 275          * @see                         GetDividerPosition()
 276          * @see                         SetMaximumDividerPosition()
 277          * @see                         GetMaximumDividerPosition()
 278          * @see                         SetMinimumDividerPosition()
 279          * @see                         GetMinimumDividerPosition()
 280          * @remarks                     This Api sets the value to current orientation. The divider position must be reset when the orientation of the form is changed.
 281          */
 282         result SetDividerPosition(int position);
 283
 284         /**
 285          * Sets the divider position of the control.
 286          *
 287          * @since 2.1
 288          *
 289          * @return                      An error code
 290          * @param[in]           position                                The position of divider
 291          * @exception           E_SUCCESS                               The method is successful.
 292          * @exception           E_OUT_OF_RANGE                  A specified input parameter is invalid.
 293          * @see                         GetDividerPosition()
 294          * @see                         SetMaximumDividerPosition()
 295          * @see                         GetMaximumDividerPosition()
 296          * @see                         SetMinimumDividerPosition()
 297          * @see                         GetMinimumDividerPosition()
 298          * @remarks                     This Api sets the value to current orientation. The divider position must be reset when the orientation of the form is changed.
 299          */
 300         result SetDividerPosition(float position);
 301
 302         /**
 303          * Gets the current divider position of the control.
 304          *
 305          * @since 2.0
 306          *
 307          * @return                      The current divider position
 308          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 309          * @see                         SetDividerPosition()
 310          * @see                         SetMaximumDividerPosition()
 311          * @see                         GetMaximumDividerPosition()
 312          * @see                         SetMinimumDividerPosition()
 313          * @see                         GetMinimumDividerPosition()
 314          */
 315         int GetDividerPosition(void) const;
 316
 317         /**
 318          * Gets the current divider position of the control.
 319          *
 320          * @since 2.1
 321          *
 322          * @return                      The current divider position
 323          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 324          * @see                         SetDividerPosition()
 325          * @see                         SetMaximumDividerPosition()
 326          * @see                         GetMaximumDividerPosition()
 327          * @see                         SetMinimumDividerPosition()
 328          * @see                         GetMinimumDividerPosition()
 329          */
 330         float GetDividerPositionF(void) const;
 331
 332         /**
 333          * Sets the divider maximum position of the control.
 334          *
 335          * @since 2.0
 336          *
 337          * @return                      An error code
 338          * @param[in]           position                                The position of divider.
 339          * @exception           E_SUCCESS                               The method is successful.
 340          * @exception           E_OUT_OF_RANGE                  A specified input parameter is invalid.
 341          * @see                         GetMaximumDividerPosition()
 342          * @see                         SetMinimumDividerPosition()
 343          * @see                         GetMinimumDividerPosition()
 344          * @remarks                     This Api sets the value to current orientation. The maximum divider position must be reset when the orientation of the form is changed.
 345          */
 346         result SetMaximumDividerPosition(int position);
 347
 348         /**
 349          * Sets the divider maximum position of the control.
 350          *
 351          * @since 2.1
 352          *
 353          * @return                      An error code
 354          * @param[in]           position                                The position of divider.
 355          * @exception           E_SUCCESS                               The method is successful.
 356          * @exception           E_OUT_OF_RANGE                  A specified input parameter is invalid.
 357          * @see                         GetMaximumDividerPosition()
 358          * @see                         SetMinimumDividerPosition()
 359          * @see                         GetMinimumDividerPosition()
 360          * @remarks                     This Api sets the value to current orientation. The maximum divider position must be reset when the orientation of the form is changed.
 361          */
 362         result SetMaximumDividerPosition(float position);
 363
 364         /**
 365          * Gets the maximum divider position.
 366          *
 367          * @since 2.0
 368          *
 369          * @return                      The maximum divider position of the control.
 370          * @see                         SetMaximumDividerPosition()
 371          * @see                         SetMinimumDividerPosition()
 372          * @see                         GetMinimumDividerPosition()
 373          */
 374         int GetMaximumDividerPosition(void) const;
 375
 376         /**
 377          * Gets the maximum divider position.
 378          *
 379          * @since 2.1
 380          *
 381          * @return                      The maximum divider position of the control.
 382          * @see                         SetMaximumDividerPosition()
 383          * @see                         SetMinimumDividerPosition()
 384          * @see                         GetMinimumDividerPosition()
 385          */
 386         float GetMaximumDividerPositionF(void) const;
 387
 388         /**
 389          * Sets the divider minimum position of the control.
 390          *
 391          * @since 2.0
 392          *
 393          * @return                      An error code
 394          * @param[in]           position                                The position of divider.
 395          * @exception           E_SUCCESS                               The method is successful.
 396          * @exception           E_OUT_OF_RANGE                  A specified input parameter is invalid.
 397          * @see                         GetMinimumDividerPosition()
 398          * @see                         SetMaximumDividerPosition()
 399          * @see                         GetMaximumDividerPosition()
 400          * @remarks                     This Api sets the value to current orientation. The minimum divider position must be reset when the orientation of the form is changed.
 401          */
 402         result SetMinimumDividerPosition(int position);
 403
 404         /**
 405          * Sets the divider minimum position of the control.
 406          *
 407          * @since 2.1
 408          *
 409          * @return                      An error code
 410          * @param[in]           position                                The position of divider.
 411          * @exception           E_SUCCESS                               The method is successful.
 412          * @exception           E_OUT_OF_RANGE                  A specified input parameter is invalid.
 413          * @see                         GetMinimumDividerPosition()
 414          * @see                         SetMaximumDividerPosition()
 415          * @see                         GetMaximumDividerPosition()
 416          * @remarks                     This Api sets the value to current orientation. The minimum divider position must be reset when the orientation of the form is changed.
 417          */
 418         result SetMinimumDividerPosition(float position);
 419
 420         /**
 421          * Gets the minimum divider position.
 422          *
 423          * @since 2.0
 424          *
 425          * @return                      The minimum divider position of the control.
 426          * @see                         SetMinimumDividerPosition()
 427          * @see                         SetMaximumDividerPosition()
 428          * @see                         GetMaximumDividerPosition()
 429          */
 430         int GetMinimumDividerPosition(void) const;
 431
 432         /**
 433          * Gets the minimum divider position.
 434          *
 435          * @since 2.1
 436          *
 437          * @return                      The minimum divider position of the control.
 438          * @see                         SetMinimumDividerPosition()
 439          * @see                         SetMaximumDividerPosition()
 440          * @see                         GetMaximumDividerPosition()
 441          */
 442         float GetMinimumDividerPositionF(void) const;
 443
 444         /**
 445          * Maximizes the specified pane.
 446          *
 447          * @since 2.0
 448          *
 449          * @return                      An error code
 450          * @param[in]           paneOrder                               The order of pane.
 451          * @see                         IsPaneMaximized()
 452          */
 453         result MaximizePane(SplitPanelPaneOrder paneOrder);
 454
 455         /**
 456          * Checks whether the specified pane is maximized.
 457          *
 458          * @since 2.0
 459          * @return              @c true if the pane is maximized, @n
 460          *                      else @c false
 461          */
 462         bool IsPaneMaximized(SplitPanelPaneOrder paneOrder) const;
 463
 464         /**
 465          * Restores the previous pane size if the specified pane is maximized.
 466          *
 467          * @since 2.0
 468          *
 469          * @return                      An error code
 470          * @see                         MaximizePane()
 471          */
 472         result RestorePane(void);
 473
 474 private:
 475         //
 476         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 477         //
 478         SplitPanel(const SplitPanel& rhs);
 479
 480         //
 481         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 482         //
 483         SplitPanel& operator =(const SplitPanel& rhs);
 484
 485         friend class _SplitPanelImpl;
 486
 487 }; // SplitPanel
 488
 489 }}} //Tizen::Ui::Controls
 490
 491 #endif // _FUI_CTRL_SPLIT_PANEL_H_