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