1 #ifndef __DALI_TOOLKIT_NAVIGATION_CONTROL_H__
2 #define __DALI_TOOLKIT_NAVIGATION_CONTROL_H__
5 * Copyright (c) 2015 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/public-api/animation/alpha-function.h>
23 #include <dali-toolkit/public-api/controls/control.h>
24 #include <dali-toolkit/public-api/controls/navigation-frame/page.h>
25 #include <dali-toolkit/public-api/controls/navigation-frame/navigation-bar-style.h>
33 namespace Internal DALI_INTERNAL
35 // Forward declarations
36 class NavigationControl;
40 * NavigationControl implements a controller than manages the navigation of hierarchical contents.
41 * NavigationControl holds views as its item which are organized in a stack.
42 * New items get pushed on the top of the old. Only the topmost item is displayed in the view area at one time.
43 * Its layout contains a title bar on the top, a tool bar in the bottom, and the content of top item in the middle.
44 * The top item carries title/subtitle/buttons/icon information,
45 * so with new item on the top, the NavigationControl will update the bars accordingly.
46 * if no component is needed to place on the bar for the current item, the bar is hidden
47 * +----------------------------------------+
49 * | +-+ Title +-+ +-+ | title bar
50 * | +-+ Subtitle +-+ +-+ |
51 * +----------------------------------------+
73 * +----------------------------------------+
74 * | +-+ +-----+ +-----+ +-+ |
75 * | +-+ +-----+ +-----+ +-+ | tool bar
76 * +----------------------------------------+
79 * | %Action Name | %NavigationControl method called |
80 * |-------------------|----------------------------------|
81 * | push | %PushItem() |
82 * | pop | %PopItem() |
84 class DALI_IMPORT_API NavigationControl : public Control
90 * Create a NavigationControl handle; this can be initialize with NavigationControl::New().
91 * Calling member function with an uninitialized handle is not allowed.
98 NavigationControl( const NavigationControl& handle );
101 * Assignment operator.
103 NavigationControl& operator=( const NavigationControl& handle );
108 * This is non-virtual since derived Handle types must not contain data or virtual methods.
110 ~NavigationControl();
113 * Create an initialized NavigationControl.
114 * @return A handle to a newly allocated Dali resource.
116 static NavigationControl New();
119 * Downcast an object handle to NavigationControl.
120 * If handle points to a NavigationControl, the downcast produces valid handle.
121 * If not, the returned handle is left uninitialized.
122 * @param[in] handle Handle to an object.
123 * @return handle to a NavigationControl of an uninitialized handle.
125 static NavigationControl DownCast( BaseHandle handle );
128 * Push a new item to the top of the NavigationControl stack and show it.
129 * @param[in] item A Page object.
131 void PushItem( Page item );
134 * Pop an item that is on the top of the NavigationControl stack and make it disappear.
135 * It doesnot pop out the last item in the stack.
136 * It returns an uninitialized item handle if there is no item or only one item in the stack.
137 * @return The Page popped out.
142 * Query the number of items in the stack.
143 * @return the number of items in the stack.
145 std::size_t GetItemCount() const;
148 * Retrieve the index-th item in the stack
149 * Here, the index is from zero to stack size minus one, the bottom-most item is with index zero
150 * @pre There are more items in the stack than the parameter index plus one
151 * @param[in] index The location index of the item in the stack
152 * @return The index-th item in the navigation stack
154 Page GetItem(std::size_t index) const;
157 * Retrieve the current top item.
158 * @return the Page object which is on the top of the stack.
160 Page GetCurrentItem() const;
163 * Sets a background image.
164 * @param[in] background Actor with the navigation control background.
166 void SetBackground( Actor background);
169 *Create a tool bar at the bottom of the navigation control.
170 *@param[in] toolBarStylePortrait the given navigation tool bar style of Portrait orientation.
171 *@param[in] toolBarStyleLandscape the given navigation tool bar style of Landscape orientation.
173 void CreateNavigationToolBar( NaviToolBarStyle toolBarStylePortrait, NaviToolBarStyle toolBarStyleLandscape );
176 * Create a title bar at the top of the navigation control.
177 * @param[in] titleBarStylePortrait the given navigation title bar style of Portrait orientation.
178 * @param[in] titleBarStyleLandscape the given navigation title bar style of Landscape orientation.
180 void CreateNavigationTitleBar( NaviTitleBarStyle titleBarStylePortrait, NaviTitleBarStyle titleBarStyleLandscape);
183 * Rotate all the contents to the new given orientation. This rotation is animated.
184 * Also change the bar style from portrait to landscape style, or vice versa.
185 * The application should invoke this function in call back of the orientation change signal if different orientations are required.
186 * @param[in] angle The angle degree of the new orientation, this is one of four discrete values, in degrees clockwise: 0, 90, 180, & 270
188 void OrientationChanged( int angle );
191 * Set the duration and the alpha function for the rotating animation in OrientationChanged function above.
192 * Without calling this function, the default values are 1.0 and EaseOut respectively.
193 * @param[in] duration The duration of the rotating animation when orientation changed.
194 * @param[in] alphaFunc The alpha function of the rotating animation when orientation changed.
196 void SetOrientationRotateAnimation( float duration, AlphaFunction alphaFunc);
200 typedef Signal< void( NavigationControl, Page ) > ItemPushedSignalType;
201 typedef Signal< void( NavigationControl, Page ) > ItemPoppedSignalType;
204 * Signal emitted right after a new item is pushed into the navigation stack.
205 * A callback of the following type may be connected:
207 * void YourCallBackName(NavigationControl controller, Page pushedItem);
209 * @return The signal to connect to.
211 ItemPushedSignalType& ItemPushedSignal();
214 * Signal emitted right after an item is popped out from the navigation stack.
215 * A callback of the following type may be connected:
217 * void YourCallBackName(NavigationControl controller, Page poppedItem);
219 * If attempt to pop the bottom-most item, the poppedItem in the callback will receive an uninitialized handle
220 * The app can use this signal and check the poppedItem to be uninitialized to know the app window should be lower
221 * @return The signal to connect to.
223 ItemPoppedSignalType& ItemPoppedSignal();
227 public: // Not intended for application developers
230 * Creates a handle using the Toolkit::Internal implementation.
231 * @param[in] implementation The Control implementation.
233 DALI_INTERNAL NavigationControl( Internal::NavigationControl& implementation );
236 * Allows the creation of this Control from an Internal::CustomActor pointer.
237 * @param[in] internal A pointer to the internal CustomActor.
239 explicit DALI_INTERNAL NavigationControl( Dali::Internal::CustomActor* internal );
241 }; // class NavigationControl
243 } // namespace Toolkit
247 #endif /* __DALI_TOOLKIT_NAVIGATION_CONTROL_H__ */