Fixed to add the AllWindowList
[platform/framework/native/uifw.git] / inc / FUiCtrlPopup.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
4 //
5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0/
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        FUiCtrlPopup.h
20  * @brief       This is the header file for the %Popup class.
21  *
22  * This header file contains the declarations of the %Popup class.
23  */
24
25 #ifndef _FUI_CTRL_POPUP_H_
26 #define _FUI_CTRL_POPUP_H_
27
28 #include <FUiWindow.h>
29
30 namespace Tizen { namespace Ui
31 {
32 class DataBindingContext;
33 }}      // Tizen::Ui
34
35
36 namespace Tizen { namespace Ui { namespace Controls
37 {
38
39 /**
40  * @class       Popup
41  * @brief       This class displays a popup on the top of the screen.
42  *
43  * @since       2.0
44  *
45  * The %Popup class displays messages to alert the user of important changes, to request confirmation for a significant task, or to
46  * serve as a warning. It is an implementation of the Window class.
47  *
48  * For more information on the class features,
49  * see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_popup_messagebox.htm">Popup and MessageBox</a>.
50  *
51  * @see Tizen::Ui::Window
52  *
53  * The following example demonstrates how to use the %Popup class.
54  *
55  * @code
56 // Sample code for PopupSample.h
57 #include <FUi.h>
58
59 class PopupEventListener
60     : public Tizen::Ui::IPropagatedKeyEventListener
61 {
62     // key events for back-key
63     virtual bool OnKeyPressed(Tizen::Ui::Control& source, const Tizen::Ui::KeyEventInfo& keyEventInfo) { return false; };
64     virtual bool OnKeyReleased(Tizen::Ui::Control& source, const Tizen::Ui::KeyEventInfo& keyEventInfo);
65     virtual bool OnPreviewKeyPressed(Tizen::Ui::Control& source, const Tizen::Ui::KeyEventInfo& keyEventInfo) { return false; };
66     virtual bool OnPreviewKeyReleased(Tizen::Ui::Control& source, const Tizen::Ui::KeyEventInfo& keyEventInfo) { return false; };
67     virtual bool TranslateKeyEventInfo(Tizen::Ui::Control& source, Tizen::Ui::KeyEventInfo& keyEventInfo) { return false; };
68
69 };
70
71 class PopupSample
72     : public Tizen::Ui::Controls::Form
73     , public Tizen::Ui::IActionEventListener
74 {
75 public:
76     PopupSample(void)
77     : __pPopup(null){}
78
79     bool Initialize(void);
80     void ShowPopup(void);
81     void HidePopup(void);
82     virtual result OnInitializing(void);
83     virtual result OnTerminating(void);
84     virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
85
86 private:
87     static const int ID_BUTTON_OPEN_POPUP = 501;
88     static const int ID_BUTTON_CLOSE_POPUP = 502;
89
90     Tizen::Ui::Controls::Popup* __pPopup;
91     PopupEventListener* __pPopupListener;
92 };
93  *      @endcode
94  *
95  *      @code
96 // Sample code for PopupSample.cpp
97 #include <FGraphics.h>
98
99 #include "PopupSample.h"
100
101 using namespace Tizen::Graphics;
102 using namespace Tizen::Ui::Controls;
103
104 bool
105 PopupEventListener::OnKeyReleased(Control& source, const KeyEventInfo& keyEventInfo)
106 {
107         KeyCode key = keyEventInfo.GetKeyCode();
108         if (key == KEY_BACK || key == KEY_ESC)
109         {
110                 Popup* pPopup = static_cast<Popup *>(&source);
111                 pPopup->SetShowState(false);
112                 pPopup->Invalidate(true);
113         }
114
115         return false;
116 }
117
118 bool
119 PopupSample::Initialize(void)
120 {
121     Construct(FORM_STYLE_NORMAL);
122     return true;
123 }
124
125 result
126 PopupSample::OnInitializing(void)
127 {
128     result r = E_SUCCESS;
129
130     __pPopupListener = new PopupEventListener;
131
132     // Creates an instance of Popup
133     __pPopup = new Popup;
134     __pPopup->Construct(true, Dimension(600,800));
135     __pPopup->SetTitleText(L"Popup Sample");
136
137     // Creates an instance of Button to close the popup.
138     Button* pCloseButton = new Button();
139     pCloseButton->Construct(Rectangle(10, 10, 250, 80), L"Close Popup");
140     pCloseButton->SetActionId(ID_BUTTON_CLOSE_POPUP);
141     pCloseButton->AddActionEventListener(*this);
142
143     // Adds the button to the popup
144     __pPopup->AddControl(pCloseButton);
145     __pPopup->SetPropagatedKeyEventListener(__pPopupListener);
146
147     // Creates an instance of Button to open the popup.
148     Button* pOpenButton = new Button();
149     pOpenButton->Construct(Rectangle(10, 10, 250, 60), L"Open Popup");
150     pOpenButton->SetActionId(ID_BUTTON_OPEN_POPUP);
151     pOpenButton->AddActionEventListener(*this);
152
153     // Adds the button to the form
154     AddControl(pOpenButton);
155
156     return r;
157 }
158
159 void
160 PopupSample::ShowPopup(void)
161 {
162     __pPopup->SetShowState(true);
163     __pPopup->Show();
164 }
165
166 void
167 PopupSample::HidePopup(void)
168 {
169     __pPopup->SetShowState(false);
170     Invalidate(true);
171 }
172
173 result
174 PopupSample::OnTerminating(void)
175 {
176     result r = E_SUCCESS;
177
178     // Deallocates the __pPopup
179     __pPopup->Destroy();
180     delete __pPopupListener;
181
182     return r;
183 }
184
185 void
186 PopupSample::OnActionPerformed(const Control& source, int actionId)
187 {
188     switch (actionId)
189     {
190     case ID_BUTTON_OPEN_POPUP:
191         {
192             ShowPopup();
193         }
194         break;
195     case ID_BUTTON_CLOSE_POPUP:
196         {
197             HidePopup();
198         }
199         break;
200     default:
201         break;
202     }
203 }
204
205 * @endcode
206 */
207
208 class _OSP_EXPORT_ Popup
209         : public Tizen::Ui::Window
210 {
211 public:
212         /**
213          * The object is not fully constructed after this constructor is called.  @n
214          * For full construction, the %Construct() method must be called right after calling this constructor.
215          *
216          * @since       2.0
217          */
218         Popup(void);
219
220         /**
221          * This destructor overrides Tizen::Base::Object::~Object().
222          *
223          * @since       2.0
224          */
225         virtual ~Popup(void);
226
227         /**
228          * Initializes this instance of %Popup with the specified dimensions.
229          *
230          * @since               2.0
231          *
232          * @return              An error code
233          * @param[in]   hasTitle                        Set to @c true if the %Popup control has a title, @n
234          *                                                                      else @c false
235          * @param[in]   dim                             The size of the %Popup control @n
236          *                                                                      The optimal size of the control is defined in
237          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
238          * @exception   E_SUCCESS               The method is successful.
239          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
240          * @exception   E_SYSTEM                A system error has occurred.
241          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
242          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
243          */
244         result Construct(bool hasTitle, const Tizen::Graphics::Dimension& dim);
245
246         /**
247          * Initializes this instance of %Popup with the specified dimensions.
248          *
249          * @since               2.1
250          *
251          * @return              An error code
252          * @param[in]   hasTitle                        Set to @c true if the %Popup control has a title, @n
253          *                                                                      else @c false
254          * @param[in]   dim                             The size of the %Popup control @n
255          *                                                                      The optimal size of the control is defined in
256          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
257          * @exception   E_SUCCESS               The method is successful.
258          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
259          * @exception   E_SYSTEM                A system error has occurred.
260          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
261          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
262          */
263         result Construct(bool hasTitle, const Tizen::Graphics::FloatDimension& dim);
264
265         /**
266          * Initializes this instance of %Popup and child controls with the specified resource ID @n
267          * This method first attempts to find the resource file in the folder that corresponds to the current screen resolution. @n
268          * If it fails to find the resource file, it searches in other folders in the following order when CoordinateSystem is Logical in the application manifest file
269          * the density folder that corresponds to the current screen size category  "res/screen-size-normal/" folder.
270          *
271          * @since         2.0
272          *
273          * @return     An error code
274          * @param[in]  resourceId              The resource ID describing the %Popup control
275          * @exception  E_SUCCESS               The method is successful.
276          * @exception  E_FILE_NOT_FOUND        The specified file cannot be found.
277          * @exception  E_INVALID_FORMAT        The specified XML format is invalid.
278          * @exception  E_OPERATION_FAILED      The operation has failed.
279          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
280          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
281          * @remarks     If SetBounds(), SetSize(), SetPosition() methods are called before Show(), then the new value is applied to both orientations
282          *                      because the current orientation is not known. After Show() is called, then the values are applied only to the current orientation.
283          */
284         result Construct(const Tizen::Base::String& resourceId);
285
286         /**
287          * Initializes this instance of %Popup with the specified layout and dimensions.
288          *
289          * @since               2.0
290          *
291          * @return              An error code
292          * @param[in]   layout                          The layout for both the portrait and landscape mode
293          * @param[in]   hasTitle                Set to @c true if the %Popup control should have a title, @n
294          *                                                              else @c false
295          * @param[in]   dim                             The size of the %Popup control @n
296          *                                                                      The optimal size of the control is defined in
297          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
298          * @exception   E_SUCCESS               The method is successful.
299          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
300          *                                                                      the specified layout is already bound to another container.
301          * @exception   E_SYSTEM                A system error has occurred.
302          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
303          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
304          */
305         result Construct(const Tizen::Ui::Layout& layout, bool hasTitle, const Tizen::Graphics::Dimension& dim);
306
307         /**
308          * Initializes this instance of %Popup with the specified layout and dimensions.
309          *
310          * @since               2.1
311          *
312          * @return              An error code
313          * @param[in]   layout                          The layout for both the portrait and landscape mode
314          * @param[in]   hasTitle                Set to @c true if the %Popup control should have a title, @n
315          *                                                              else @c false
316          * @param[in]   dim                             The size of the %Popup control @n
317          *                                                                      The optimal size of the control is defined in
318          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
319          * @exception   E_SUCCESS               The method is successful.
320          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
321          *                                                                      the specified layout is already bound to another container.
322          * @exception   E_SYSTEM                A system error has occurred.
323          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
324          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
325          */
326         result Construct(const Tizen::Ui::Layout& layout, bool hasTitle, const Tizen::Graphics::FloatDimension& dim);
327
328         /**
329          * Initializes this instance of %Popup with the specified layouts and dimensions.
330          *
331          * @since               2.0
332          *
333          * @return              An error code
334          * @param[in]   portraitLayout          The layout for the portrait mode
335          * @param[in]   landscapeLayout         The layout for the landscape mode
336          * @param[in]   hasTitle                        Set to @c true if this %Popup control should have a title, @n
337          *                                                                      else @c false
338          * @param[in]   dim                             The size of the %Popup control @n
339          *                                                                      The optimal size of the control is defined in
340          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
341          * @exception   E_SUCCESS               The method is successful.
342          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
343          *                                                                      the specified layout is already bound to another container.
344          * @exception   E_SYSTEM                A system error has occurred.
345          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
346          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
347          */
348         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, bool hasTitle, const Tizen::Graphics::Dimension& dim);
349
350         /**
351          * Initializes this instance of %Popup with the specified layouts and dimensions.
352          *
353          * @since               2.1
354          *
355          * @return              An error code
356          * @param[in]   portraitLayout          The layout for the portrait mode
357          * @param[in]   landscapeLayout         The layout for the landscape mode
358          * @param[in]   hasTitle                        Set to @c true if this %Popup control should have a title, @n
359          *                                                                      else @c false
360          * @param[in]   dim                             The size of the %Popup control @n
361          *                                                                      The optimal size of the control is defined in
362          *                                                                      <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
363          * @exception   E_SUCCESS               The method is successful.
364          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
365          *                                                                      the specified layout is already bound to another container.
366          * @exception   E_SYSTEM                A system error has occurred.
367          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
368          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
369          */
370         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, bool hasTitle, const Tizen::Graphics::FloatDimension& dim);
371
372         /**
373          * Shows the modal window. @n
374          *
375          * @since 2.0
376          * @return                   An error code
377          * @param[out]   modalResult           The %Popup's notification. @n
378          *                                              This value is the 'modalResult' parameter of the EndModal() method
379          * @exception     E_SUCCESS            The method is successful.
380          * @exception     E_INVALID_STATE    The %Popup is not visible. The visible state of the %Popup should be set @c true.
381          * @remarks
382          *                              - Do not call this method from Tizen::App::App::OnAppInitializing().
383          *                              - To show a %Popup properly from Tizen::Ui::Controls::Form::OnInitializing(), theForm must
384          *                              have been successfully drawn before the DoModal() method.
385          */
386         result DoModal(int& modalResult);
387
388         /**
389          * Closes the modal window. @n
390          *
391          * @since 2.0
392          * @return                  An error code
393          * @param[in]     modalResult                           The result value of the modal window. @n
394          *                                                                              The value which needs to be returned as the output parameter of DoModal() method
395          *                                                                              should be passed as the input argument
396          * @exception     E_SUCCESS                            The method is successful.
397          * @exception     E_INVALID_STATE                    The method is not supported because this popup isn't running as a modal window.
398          */
399         result EndModal(int modalResult);
400
401         /**
402          * Sets the title of the %Popup control.
403          *
404          * @since               2.0
405          *
406          * @return              An error code
407          * @param[in]   title           The title to set
408          * @exception   E_SUCCESS       The method is successful.
409          * @exception   E_SYSTEM        A system error has occurred.
410          */
411         virtual result SetTitleText(const Tizen::Base::String& title);
412
413         /**
414          * Gets the title of the %Popup control.
415          *
416          * @since               2.0
417          *
418          * @return              The title of the %Popup control
419          */
420         Tizen::Base::String GetTitleText(void) const;
421
422         /**
423          * Gets the bounds of the client area.
424          *
425          * @since               2.0
426          *
427          * @return              The bounds of the client area in a Tizen::Graphics::Rectangle instance
428          */
429         Tizen::Graphics::Rectangle GetClientAreaBounds(void) const;
430
431         /**
432          * Gets the bounds of the client area.
433          *
434          * @since               2.1
435          *
436          * @return              The bounds of the client area in a Tizen::Graphics::FloatRectangle instance
437          */
438         Tizen::Graphics::FloatRectangle GetClientAreaBoundsF(void) const;
439
440         /**
441          * Creates and returns a graphics canvas whose bounds (position and size) are equal to the bounds of the client area of the %Popup control.
442          *
443          * @since               2.0
444          *
445          * @return              The graphic canvas of the %Popup control, @n
446          *                              else @c null if an error occurs
447          * @exception   E_SUCCESS                                       The method is successful.
448          * @exception   E_RESOURCE_UNAVAILABLE          The required resource is currently unavailable.
449          * @remarks
450          *                              - The method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the client area of the %Popup control.
451          *                              - It is the responsibility of the developers to deallocate the canvas after use.
452          *                              - The canvas is valid only if the properties of the parent control of the canvas remain unchanged. @n
453          *                              Therefore, delete the previously allocated canvas and create a new canvas using this method if the size or position of the
454          *                              control is changed.
455          *                              - The specific error code can be accessed using the GetLastResult() method.
456          */
457         Tizen::Graphics::Canvas* GetClientAreaCanvasN(void) const;
458
459         /**
460          * Translates the specified position to the client coordinates.
461          *
462          * @since       2.0
463          *
464          * @return      The position in relative to the top-left corner of the client-area, @n
465          *                              else @c (-1,-1) if the instance is invalid
466          * @param[in]   position        The position relative to the top-left corner of the %Popup control
467          * @see         TranslateFromClientAreaPosition()
468          */
469         Tizen::Graphics::Point TranslateToClientAreaPosition(const Tizen::Graphics::Point& position) const;
470
471         /**
472          * Translates the specified position to the client coordinates.
473          *
474          * @since       2.1
475          *
476          * @return      The position in relative to the top-left corner of the client-area, @n
477          *                              else @c (-1.0f,-1.0f) if the instance is invalid
478          * @param[in]   position        The position relative to the top-left corner of the %Popup control
479          * @see         TranslateFromClientAreaPositionF()
480          */
481         Tizen::Graphics::FloatPoint TranslateToClientAreaPosition(const Tizen::Graphics::FloatPoint& position) const;
482
483         /**
484          * Translates the specified client position to the control coordinate.
485          *
486          * @since       2.0
487          *
488          * @return      The position in relative to the top-left corner of the %Popup control, @n
489          *                              else @c (-1,-1) if the instance is invalid
490          * @param[in]   clientPosition          The position relative to the top-left corner of the client area
491          * @see         TranslateToClientAreaPosition()
492          */
493         Tizen::Graphics::Point TranslateFromClientAreaPosition(const Tizen::Graphics::Point& clientPosition) const;
494
495         /**
496          * Translates the specified client position to the control coordinate.
497          *
498          * @since       2.1
499          *
500          * @return      The position in relative to the top-left corner of the %Popup control, @n
501          *                              else @c (-1.0f,-1.0f) if the instance is invalid
502          * @param[in]   clientPosition          The position relative to the top-left corner of the client area
503          * @see         TranslateToClientAreaPositionF()
504          */
505         Tizen::Graphics::FloatPoint TranslateFromClientAreaPosition(const Tizen::Graphics::FloatPoint& clientPosition) const;
506
507         /**
508          * Gets the color of the %Popup control.
509          *
510          * @since       2.0
511          *
512          * @return      The color, @n
513          *                              else RGBA(0, 0, 0, 0) if an error occurs
514          * @exception   E_SUCCESS            The method is successful.
515          * @remarks     The specific error code can be accessed using the GetLastResult() method.
516          */
517         Tizen::Graphics::Color GetColor(void) const;
518
519         /**
520          * Sets the color of the %Popup control.
521          *
522          * @since       2.0
523          *
524          * @return      An error code
525          * @param[in]   color               The color to set
526          * @exception   E_SUCCESS           The method is successful.
527          * @exception   E_SYSTEM            A system error has occurred.
528          */
529         result SetColor(const Tizen::Graphics::Color& color);
530
531         /**
532          * Gets the title text color of the %Popup control.
533          *
534          * @since               2.0
535          *
536          * @return              The color, @n
537          *                              else RGBA(0, 0, 0, 0) if an error occurs
538          * @exception   E_SUCCESS                       The method is successful.
539          * @remarks             The specific error code can be accessed using the GetLastResult() method.
540          */
541         Tizen::Graphics::Color GetTitleTextColor(void) const;
542
543         /**
544          * Sets the title text color of the %Popup control.
545          *
546          * @since       2.0
547          *
548          * @return      An error code
549          * @param[in]   color                The title text color
550          * @exception   E_SUCCESS            The method is successful.
551          * @exception   E_SYSTEM             A system error has occurred.
552          */
553         result SetTitleTextColor(const Tizen::Graphics::Color& color);
554
555         /**
556          * Gets the data binding context.
557          *
558          * @since 2.0
559          *
560          * @return       The data binding context
561          * @exception    E_SUCCESS        The method is successful.
562          * @exception    E_SYSTEM         A system error has occurred.
563          * @remarks      The specific error code can be accessed using the GetLastResult() method.
564          */
565         DataBindingContext* GetDataBindingContextN(void) const;
566
567 protected:
568         friend class _PopupImpl;
569
570         /**
571          * The following methods are reserved and may change its name at any time without
572          * prior notice.
573          */
574         virtual void Popup_Reserved1(void) { }
575         virtual void Popup_Reserved2(void) { }
576         virtual void Popup_Reserved3(void) { }
577
578 private:
579         //
580         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
581         //
582         Popup(const Popup& rhs);
583
584         //
585         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
586         //
587         Popup& operator =(const Popup& rhs);
588
589 }; // Popup
590
591
592 }}} // Tizen::Ui::Controls
593
594 #endif  //_FUI_CTRL_POPUP_H_