optional/dali-toolkit/public-api/controls/navigation-frame/navigation-control.h

   1 #ifndef __DALI_TOOLKIT_NAVIGATION_CONTROL_H__
   2 #define __DALI_TOOLKIT_NAVIGATION_CONTROL_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.0 (the License);
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //     http://floralicense.org/license/
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an AS IS BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19
  20 // INTERNAL INCLUDES
  21 #include <dali-toolkit/public-api/controls/control.h>
  22 #include <dali-toolkit/public-api/controls/navigation-frame/page.h>
  23 #include <dali-toolkit/public-api/controls/navigation-frame/navigation-bar-style.h>
  24
  25 namespace Dali DALI_IMPORT_API
  26 {
  27
  28 namespace Toolkit
  29 {
  30
  31 namespace Internal DALI_INTERNAL
  32 {
  33 // Forward declarations
  34 class NavigationControl;
  35 }
  36
  37 /**
  38  * NavigationControl implements a controller than manages the navigation of hierarchical contents.
  39  * NavigationControl holds views as its item which are organized in a stack.
  40  * New items get pushed on the top of the old. Only the topmost item is displayed in the view area at one time.
  41  * Its layout contains a title bar on the top, a tool bar in the bottom, and the content of top item in the middle.
  42  * The top item carries title/subtitle/buttons/icon information,
  43  * so with new item on the top, the NavigationControl will update the bars accordingly.
  44  * if no component is needed to place on the bar for the current item, the bar is hidden
  45  *                 +----------------------------------------+
  46  *                 |                                        |
  47  *                 | +-+ Title                   +-+  +-+   |  title bar
  48  *                 | +-+ Subtitle                +-+  +-+   |
  49  *                 +----------------------------------------+
  50  *                 |                                        |
  51  *                 |                                        |
  52  *                 |                                        |
  53  *                 |                                        |
  54  *                 |                                        |
  55  *                 |                                        |
  56  *                 |                                        |
  57  *                 |                                        |
  58  *                 |                                        |
  59  *                 |              View Area                 |
  60  *                 |                                        |
  61  *                 |                                        |
  62  *                 |                                        |
  63  *                 |                                        |
  64  *                 |                                        |
  65  *                 |                                        |
  66  *                 |                                        |
  67  *                 |                                        |
  68  *                 |                                        |
  69  *                 |                                        |
  70  *                 |                                        |
  71  *                 +----------------------------------------+
  72  *                 | +-+        +-----+  +-----+        +-+ |
  73  *                 | +-+        +-----+  +-----+        +-+ |  tool bar
  74  *                 +----------------------------------------+
  75  */
  76
  77 class NavigationControl : public Control
  78 {
  79
  80 public:
  81   //Action Names
  82   static const char* const ACTION_PUSH;
  83   static const char* const ACTION_POP;
  84
  85 public:
  86
  87   /**
  88    * Create a NavigationControl handle; this can be initialize with NavigationControl::New().
  89    * Calling member function with an uninitialized handle is not allowed.
  90    */
  91   NavigationControl();
  92
  93   /**
  94    * Copy Constructor.
  95    */
  96   NavigationControl( const NavigationControl& handle );
  97
  98  /**
  99   * Assignment operator.
 100   */
 101   NavigationControl& operator=( const NavigationControl& handle );
 102
 103   /**
 104    * virtual Destructor.
 105    */
 106   virtual ~NavigationControl();
 107
 108   /**
 109    * Create an initialized NavigationControl.
 110    * @return A handle to a newly allocated Dali resource.
 111    */
 112   static NavigationControl New();
 113
 114   /**
 115    * Downcast an object handle to NavigationControl.
 116    * If handle points to a NavigationControl, the downcast produces valid handle.
 117    * If not, the returned handle is left uninitialized.
 118    * @param[in] handle Handle to an object.
 119    * @return handle to a NavigationControl of an uninitialized handle.
 120    */
 121   static NavigationControl DownCast( BaseHandle handle );
 122
 123   /**
 124    * Push a new item to the top of the NavigationControl stack and show it.
 125    * @param[in] item A Page object.
 126    */
 127   void PushItem( Page item );
 128
 129   /**
 130    * Pop an item that is on the top of the NavigationControl stack and make it disappear.
 131    * It doesnot pop out the last item in the stack.
 132    * It returns an uninitialized item handle if there is no item or only one item in the stack.
 133    * @return The Page popped out.
 134    */
 135   Page PopItem();
 136
 137   /**
 138    * Query the number of items in the stack.
 139    * @return the number of items in the stack.
 140    */
 141   std::size_t GetItemCount() const;
 142
 143   /**
 144    * Retrieve the index-th item in the stack
 145    * Here, the index is from zero to stack size minus one, the bottom-most item is with index zero
 146    * @pre There are more items in the stack than the parameter index plus one
 147    * @param[in] index The location index of the item in the stack
 148    * @return The index-th item in the navigation stack
 149    */
 150   Page GetItem(std::size_t index) const;
 151
 152   /**
 153    * Retrieve the current top item.
 154    * @return the Page object which is on the top of the stack.
 155    */
 156   Page GetCurrentItem() const;
 157
 158   /**
 159    * Sets a background image.
 160    * @param[in] background Actor with the navigation control background.
 161    */
 162   void SetBackground( Actor background);
 163
 164   /**
 165    *Create a tool bar at the bottom of the navigation control.
 166    *@param[in] toolBarStylePortrait the given navigation tool bar style of Portrait orientation.
 167    *@param[in] toolBarStyleLandscape the given navigation tool bar style of Landscape orientation.
 168    */
 169   void CreateNavigationToolBar( NaviToolBarStyle toolBarStylePortrait, NaviToolBarStyle toolBarStyleLandscape );
 170
 171   /**
 172    * Create a title bar at the top of the navigation control.
 173    * @param[in] titleBarStylePortrait the given navigation title bar style of Portrait orientation.
 174    * @param[in] titleBarStyleLandscape the given navigation title bar style of Landscape orientation.
 175    */
 176   void CreateNavigationTitleBar( NaviTitleBarStyle titleBarStylePortrait, NaviTitleBarStyle titleBarStyleLandscape);
 177
 178   /**
 179    * Rotate all the contents to the new given orientation. This rotation is animated.
 180    * Also change the bar style from portrait to landscape style, or vice versa.
 181    * The application should invoke this function in call back of the orientation change signal if different orientations are required.
 182    * @param[in] angle The angle degree of the new orientation, this is one of four discrete values, in degrees clockwise: 0, 90, 180, & 270
 183    */
 184   void OrientationChanged( int angle );
 185
 186   /**
 187    * Set the duration and the alpha function for the rotating animation in OrientationChanged function above.
 188    * Without calling this function, the default values are 1.0 and EaseOut respectively.
 189    * @param[in] duration The duration of the rotating animation when orientation changed.
 190    * @param[in] alphaFunc The alpha function of the rotating animation when orientation changed.
 191    */
 192   void SetOrientationRotateAnimation( float duration, AlphaFunction alphaFunc);
 193
 194 public: //Signal
 195
 196   typedef SignalV2< void( NavigationControl, Page ) > ItemPushedSignalV2;
 197   typedef SignalV2< void( NavigationControl, Page ) > ItemPoppedSignalV2;
 198
 199   /**
 200    * Signal emitted right after a new item is pushed into the navigation stack.
 201    * A callback of the following type may be connected:
 202    * @code
 203    *   void YourCallBackName(NavigationControl controller, Page pushedItem);
 204    * @endcode
 205    * @return The signal to connect to.
 206    */
 207   ItemPushedSignalV2& ItemPushedSignal();
 208
 209   /**
 210    * Signal emitted right after an item is popped out from the navigation stack.
 211    * A callback of the following type may be connected:
 212    * @code
 213    *   void YourCallBackName(NavigationControl controller, Page poppedItem);
 214    * @endcode
 215    * If attempt to pop the bottom-most item, the poppedItem in the callback will receive an uninitialized handle
 216    * The app can use this signal and check the poppedItem to be uninitialized to know the app window should be lower
 217    * @return The signal to connect to.
 218    */
 219   ItemPoppedSignalV2& ItemPoppedSignal();
 220
 221
 222
 223 public: // Not intended for application developers
 224
 225   /**
 226    * Creates a handle using the Toolkit::Internal implementation.
 227    * @param[in]  implementation  The Control implementation.
 228    */
 229   NavigationControl( Internal::NavigationControl& implementation );
 230
 231   /**
 232    * Allows the creation of this Control from an Internal::CustomActor pointer.
 233    * @param[in]  internal  A pointer to the internal CustomActor.
 234    */
 235   NavigationControl( Dali::Internal::CustomActor* internal );
 236
 237 }; // class NavigationControl
 238
 239 } // namespace Toolkit
 240
 241 } // namespace Dali
 242
 243 #endif /* __DALI_TOOLKIT_NAVIGATION_CONTROL_H__ */