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
  38 /**
  39  * @class       SplitPanel
  40  * @brief       This class is an implementation of a %SplitPanel control.
  41  *
  42  * @since 2.0
  43  * @final       This class is not intended for extension.
  44  *
  45  * The %SplitPanel class provides the functionality of a %SplitPanel which is a control that contains two panes.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_splitpanel.htm">SplitPanel</a>.
  48  *
  49  * The following example demonstrates how to use the %SplitPanel class.
  50  *
  51  * @code
  52 // Sample code for SplitPanel.h
  53 #include <FUi.h>
  54
  55 class SplitPanelSample
  56         : public Tizen::Ui::Controls::Form
  57 {
  58 public:
  59         virtual result OnInitializing(void);
  60 };
  61  * @endcode
  62  *
  63  * @code
  64 // Sample code for SplitPanelSample.cpp
  65 #include "SplitPanelSample.h"
  66
  67 using namespace Tizen::Ui;
  68 using namespace Tizen::Ui::Controls;
  69 using namespace Tizen::Graphics;
  70
  71 result
  72 SplitPanelSample::OnInitializing(void)
  73 {
  74         // Creates an instance of SplitPanel
  75         SplitPanel* pSplitPanel = new (std::nothrow) SplitPanel();
  76         pSplitPanel->Construct(Rectangle(0, 0, 800, 400),
  77                         SPLIT_PANEL_DIVIDER_STYLE_MOVABLE, SPLIT_PANEL_DIVIDER_DIRECTION_VERTICAL);
  78
  79         // Creates instances of Panel
  80         Panel* pFirstPanel = new (std::nothrow) Panel();
  81         pFirstPanel->Construct(Rectangle(0, 0, 400, 480));
  82
  83         Panel* pSecondPanel = new (std::nothrow) Panel();
  84         pSecondPanel->Construct(Rectangle(0, 0, 400, 480));
  85
  86         //Sets the divider position to the slit panel
  87         pSplitPanel->SetDividerPosition(400);
  88
  89         //Sets panes to the split panel
  90         pSplitPanel->SetPane(pFirstPanel, SPLIT_PANEL_PANE_ORDER_FIRST);
  91         pSplitPanel->SetPane(pSecondPanel, SPLIT_PANEL_PANE_ORDER_SECOND);
  92
  93         // Adds the split panel to the form
  94         AddControl(*pSplitPanel);
  95
  96         return E_SUCCESS;
  97 }
  98  * @endcode
  99  *
 100  */
 101
 102 class _OSP_EXPORT_ SplitPanel
 103         : public Tizen::Ui::Control
 104 {
 105 public:
 106         /**
 107          * 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.
 108          *
 109          * @since 2.0
 110          */
 111         SplitPanel(void);
 112
 113         /**
 114          * 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.
 115          *
 116          * @since 2.0
 117          */
 118         virtual ~SplitPanel(void);
 119
 120         /**
 121          * Initializes this instance of %SplitPanel with the specified parameters.
 122          *
 123          * @since 2.0
 124          *
 125          * @return              An error code
 126          * @param[in]   rect                                            The location and size of the %SplitPanel control as a Rectangle instance.
 127          * @param[in]   splitPanelDividerStyle          The divider style of the %SplitPanel control
 128          * @param[in]   splitPanelDividerDirection      The divider direction of the %SplitPanel control @n
 129          *                                                                                      The specified divider direction determines the divider is vertical or horizontal.
 130          * @exception   E_SUCCESS                                       The method is successful.
 131          * @exception   E_INVALID_ARG                           A specified input parameter is invalid.
 132          */
 133         result Construct(const Tizen::Graphics::Rectangle& rect, SplitPanelDividerStyle splitPanelDividerStyle, SplitPanelDividerDirection splitPanelDividerDirection);
 134
 135         /**
 136          * Adds a ISplitPanelEventListener instance. @n
 137          * The added listener listens to events on the context of the specified event dispatcher when they are fired.
 138          *
 139          * @since 2.0
 140          *
 141          * @param[in]   listener                        The event listener to be added
 142          * @exception   E_SUCCESS                               The method is successful.
 143          * @exception   E_OBJ_ALREADY_EXIST             The event listener already exists.
 144          */
 145         result AddSplitPanelEventListener(ISplitPanelEventListener& listener);
 146
 147         /**
 148          * Removes a ISplitPanelEventListener instance. @n
 149          * The removed listener cannot listen to events when they are fired.
 150          *
 151          * @since 2.0
 152          *
 153          * @param[in]   listener                The event listener to be removed
 154          * @exception   E_SUCCESS                       The method is successful.
 155          * @exception   E_OBJ_NOT_FOUND         The event listener is not found.
 156          */
 157         result RemoveSplitPanelEventListener(ISplitPanelEventListener& listener);
 158
 159         /**
 160          * Sets the pane to the %SplitPanel control.
 161          *
 162          * @since 2.0
 163          *
 164          * @return              An error code
 165          * @param[in]   pControl                The control to be set.
 166          * @param[in]   paneOrder               The order of pane. SPLIT_PANEL_PANE_FIRST is displayed on the left side @n
 167          *                                                                      and SPLIT_PANEL_PANE_SECOND is displayed on the right side of the %SplitPanel when its direction is SPLIT_PANEL_DIVIDER_DIRECTION_VERTICAL.
 168          * @exception   E_SUCCESS                       The method is successful.
 169          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 170          * @remarks             The %SplitPanel control must contain exactly two panes and the user can change their relative sizes.
 171          */
 172         result SetPane(Control* pControl, SplitPanelPaneOrder paneOrder);
 173
 174         /**
 175          * Gets the control at the specified pane order of the %SplitPanel.
 176          *
 177          * @since 2.0
 178          *
 179          * @return              The control at the specified pane order of the %SplitPanel @n
 180          *              @c null, if there is no panel.
 181          * @param[in]   paneOrder                       The order of pane. SPLIT_PANEL_PANE_FIRST is displayed on the left side @n
 182          *                                                                      and SPLIT_PANEL_PANE_SECOND is displayed on the right side of the %SplitPanel when its direction is SPLIT_PANEL_DIVIDER_DIRECTION_VERTICAL.
 183          * @exception   E_SUCCESS                       The method is successful.
 184          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 185          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 186          */
 187         Control* GetPane(SplitPanelPaneOrder paneOrder) const;
 188
 189         /**
 190          * Sets the divider position of the control.
 191          *
 192          * @since 2.0
 193          *
 194          * @return                      An error code
 195          * @param[in]           position                                The position of divider
 196          * @exception           E_SUCCESS                               The method is successful.
 197          * @exception           E_OUT_OF_RANGE                  A specified input parameter is invalid.
 198          * @see                         GetDividerPosition()
 199          * @see                         SetMaximumDividerPosition(), GetMaximumDividerPosition()
 200          * @see                         SetMinimumDividerPosition(), GetMinimumDividerPosition()
 201          */
 202         result SetDividerPosition(int position);
 203
 204         /**
 205          * Gets the current divider position of the control.
 206          *
 207          * @since 2.0
 208          *
 209          * @return                      The current divider position
 210          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 211          * @see                         SetDividerPosition()
 212          * @see                         SetMaximumDividerPosition(), GetMaximumDividerPosition()
 213          * @see                         SetMinimumDividerPosition(), GetMinimumDividerPosition()
 214          */
 215         int GetDividerPosition(void) const;
 216
 217         /**
 218          * Sets the divider maximum position of the control.
 219          *
 220          * @since 2.0
 221          *
 222          * @return                      An error code
 223          * @param[in]           position                                The position of divider.
 224          * @exception           E_SUCCESS                               The method is successful.
 225          * @exception           E_OUT_OF_RANGE                  A specified input parameter is invalid.
 226          * @see                         GetMaximumDividerPosition()
 227          * @see                         SetMinimumDividerPosition(), GetMinimumDividerPosition()
 228          */
 229         result SetMaximumDividerPosition(int position);
 230
 231         /**
 232          * Gets the maximum divider position.
 233          *
 234          * @since 2.0
 235          *
 236          * @return                      The maximum divider position of the control.
 237          * @see                         SetMaximumDividerPosition()
 238          * @see                         SetMinimumDividerPosition(), GetMinimumDividerPosition()
 239          */
 240         int GetMaximumDividerPosition(void) const;
 241
 242         /**
 243          * Sets the divider minimum position of the control.
 244          *
 245          * @since 2.0
 246          *
 247          * @return                      An error code
 248          * @param[in]           position                                The position of divider.
 249          * @exception           E_SUCCESS                               The method is successful.
 250          * @exception           E_OUT_OF_RANGE                  A specified input parameter is invalid.
 251          * @see                         GetMinimumDividerPosition()
 252          * @see                         SetMaximumDividerPosition(), GetMaximumDividerPosition()
 253          */
 254         result SetMinimumDividerPosition(int position);
 255
 256         /**
 257          * Gets the minimum divider position.
 258          *
 259          * @since 2.0
 260          *
 261          * @return                      The minimum divider position of the control.
 262          * @see                         SetMinimumDividerPosition()
 263          * @see                         SetMaximumDividerPosition(), GetMaximumDividerPosition()
 264          */
 265         int GetMinimumDividerPosition(void) const;
 266
 267         /**
 268          * Maximizes the specified pane.
 269          *
 270          * @since 2.0
 271          *
 272          * @return                      An error code
 273          * @param[in]           paneOrder                               The order of pane.
 274          * @see                         IsPaneMaximized()
 275          */
 276         result MaximizePane(SplitPanelPaneOrder paneOrder);
 277
 278         /**
 279          * Checks whether the specified pane is maximized.
 280          *
 281          * @since 2.0
 282          * @return              @c true if the pane is maximized, @n
 283          *                      else @c false
 284          */
 285         bool IsPaneMaximized(SplitPanelPaneOrder paneOrder) const;
 286
 287         /**
 288          * Restores the previous pane size if the specified pane is maximized.
 289          *
 290          * @since 2.0
 291          *
 292          * @return                      An error code
 293          * @see                         MaximizePane()
 294          */
 295         result RestorePane(void);
 296
 297 private:
 298         //
 299         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 300         //
 301         SplitPanel(const SplitPanel& rhs);
 302
 303         //
 304         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 305         //
 306         SplitPanel& operator =(const SplitPanel& rhs);
 307
 308         friend class _SplitPanelImpl;
 309
 310 }; // SplitPanel
 311
 312 }}} //Tizen::Ui::Controls
 313
 314 #endif // _FUI_CTRL_SPLIT_PANEL_H_