inc/FUiCtrlSplitPanel.h

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