[dali_1.0.16] Merge branch 'tizen'
[platform/core/uifw/dali-toolkit.git] / base / dali-toolkit / public-api / controls / popup / popup.h
1 #ifndef __DALI_TOOLKIT_POPUP_H__
2 #define __DALI_TOOLKIT_POPUP_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/text-view/text-view.h>
24
25 namespace Dali
26 {
27
28 namespace Toolkit
29 {
30
31 namespace Internal DALI_INTERNAL
32 {
33 class Popup;
34 }
35
36 class Button;
37
38 /**
39  * @brief Popup contains content that can come into focus when activated, and out of focus when deactivated.
40  *
41  * Content:
42  *
43  * The content within a popup consists of:
44  *
45  * 1. Title
46  * 2. Buttons
47  * 3. Background/Frame (i.e. Scale-9 image)
48  * 4. Custom Content (Actors)
49  *
50  * All of which are optional.
51  *
52  * States:
53  *
54  * A popup can be in a number of states:
55  *
56  * 1. HIDE (invisible)
57  * 2. SHOW (visible at normal size)
58  * 3. SHOW_MAXIMIZED (visible occupying full parent size)
59  * 4. Or custom defined.
60  *
61  * Transition Effects:
62  *
63  * A popup can use various custom transition effects, e.g.
64  * Alpha fade, Scaling transition, position/rotation, shader effects.
65  */
66 class DALI_IMPORT_API Popup : public Control
67 {
68
69 public:
70
71   //Signal Names
72   static const char* const SIGNAL_TOUCHED_OUTSIDE; ///< name "touched-outside"
73   static const char* const SIGNAL_HIDDEN;          ///< name "hidden"
74
75   /**
76    * @brief Current popup state.
77    */
78   enum PopupState
79   {
80     POPUP_NONE,               ///< Init status
81     POPUP_HIDE,               ///< Hidden (not visible)
82     POPUP_SHOW,               ///< Shown (visible in default size)
83   };
84
85   typedef SignalV2< void () > TouchedOutsideSignalV2; ///< Touched outside signal type.
86   typedef SignalV2< void () > HiddenSignalV2;         ///< Hidden signal type.
87
88   /**
89    * @brief Signal emitted when user has touched outside of the Dialog.
90    */
91   TouchedOutsideSignalV2& OutsideTouchedSignal();
92
93   /**
94    * @brief Signal emitted when popup has been hidden.
95    */
96   HiddenSignalV2& HiddenSignal();
97
98 public:
99
100   /**
101    * @brief Creates an empty Popup handle.
102    */
103   Popup();
104
105   /**
106    * @brief Copy constructor.
107    *
108    * Creates another handle that points to the same real object
109    * @param[in] handle Handle to the copied object
110    */
111   Popup( const Popup& handle );
112
113   /**
114    * @brief Assignment operator.
115    *
116    * Changes this handle to point to another real object
117    * @param[in] handle Handle to the object
118    * @return A reference to this
119    */
120   Popup& operator=( const Popup& handle );
121
122   /**
123    * @brief Destructor
124    *
125    * This is non-virtual since derived Handle types must not contain data or virtual methods.
126    */
127   ~Popup();
128
129   /**
130    * @brief Create the Poup control.
131    *
132    * @return A handle to the Popup control.
133    */
134   static Popup New();
135
136   /**
137    * @brief Downcast an Object handle to Popup.
138    *
139    * If handle points to a Popup the
140    * downcast produces valid handle. If not the returned handle is left uninitialized.
141    * @param[in] handle Handle to an object
142    * @return handle to a Popup or an uninitialized handle
143    */
144   static Popup DownCast( BaseHandle handle );
145
146 public:
147
148   /**
149    * @brief Sets the background image for this Popup.
150    *
151    * The background is resized (stretched according to scale settings),
152    * to the size of the Popup.
153    *
154    * @param[in] image The Background ImageActor to cover background
155    */
156   void SetBackgroundImage( Actor image );
157
158   /**
159    * @brief Sets a title for this Popup.
160    *
161    * By default a TextView is created with following settings: black color, split-by-word multi-line policy and split exceed policy.
162    *
163    * @param[in] text The text to appear as the heading for this Popup
164    */
165   void SetTitle( const std::string& text );
166
167   /**
168    * @brief Sets a title for this Popup.
169    *
170    * @param[in] titleActor The TextView to appear as the heading for this Popup
171    */
172   void SetTitle( TextView titleActor );
173
174   /**
175    * @brief Gets the text (TextView) for this Popup.
176    *
177    * @return The TextView representing this popup is returned.
178    */
179   TextView GetTitle() const;
180
181   /**
182    * @brief Adds a button to this Popup.
183    *
184    * Buttons are added to the bottom of the Popup and Centered.
185    *
186    * By default the first button added will have the focus, and the focus will
187    * shift to other buttons based on the sequence in which they are added to the popup.
188    *
189    * @param[in] button The button to be added to this Popup
190    */
191   void AddButton( Button button );
192
193   /**
194    * @brief Sets state of Popup, such as HIDE, and SHOW.
195    *
196    * The Popup will instantaneously jump to this state.
197    *
198    * @param[in] state The state of the popup
199    */
200   void SetState( PopupState state );
201
202   /**
203    * @brief Sets state of Popup, such as HIDE, and SHOW.
204    *
205    * The Popup will smoothly animate to this state.
206    *
207    * @param[in] state The state of the popup
208    * @param[in] duration The time to animate to this new state.
209    */
210   void SetState( PopupState state, float duration );
211
212   /**
213    * @brief Gets the state of the popup.
214    *
215    * @return The state of the popup.
216    */
217   PopupState GetState() const;
218
219   /**
220    * @brief Shows the popup.
221    *
222    * The Popup will animate to the SHOW state
223    */
224   void Show();
225
226   /**
227    * @brief Hides the popup.
228    *
229    * The Popup will animate to the HIDE state
230    */
231   void Hide();
232
233   /**
234    * @brief Shows the tail.
235    *
236    * The tail position is specified relative to it's Parent.
237    * To display at top center for instace, pass:
238    *
239    * ParentOrigin::TOP_CENTER
240    *
241    * @note The tail images are defined inside PopupStyle as
242    * tailUpImage, tailDownImage, tailLeftImage, and tailRightImage
243    *
244    * @param[in] position A position around the perimeter of the Parent.
245    */
246   void ShowTail(const Vector3& position);
247
248   /**
249    * @brief Hides the tail.
250    */
251   void HideTail();
252
253 public: // Not intended for application developers
254
255   /**
256    * @brief Creates a handle using the Toolkit::Internal implementation.
257    *
258    * @param[in]  implementation  The Control implementation.
259    */
260   DALI_INTERNAL Popup(Internal::Popup& implementation);
261
262   /**
263    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
264    *
265    * @param[in]  internal  A pointer to the internal CustomActor.
266    */
267   explicit DALI_INTERNAL Popup( Dali::Internal::CustomActor* internal );
268 };
269
270 } // namespace Toolkit
271
272 } // namespace Dali
273
274 #endif // __DALI_TOOLKIT_POPUP_H__