2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0/
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.
19 * @file FUiCtrlPopup.h
20 * @brief This is the header file for the %Popup class.
22 * This header file contains the declarations of the %Popup class.
25 #ifndef _FUI_CTRL_POPUP_H_
26 #define _FUI_CTRL_POPUP_H_
28 #include <FUiWindow.h>
30 namespace Tizen { namespace Ui
32 class DataBindingContext;
36 namespace Tizen { namespace Ui { namespace Controls
41 * @brief This class displays a popup on the top of the screen.
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.
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>.
51 * @see Tizen::Ui::Window
53 * The following example demonstrates how to use the %Popup class.
56 // Sample code for PopupSample.h
59 class PopupEventListener
60 : public Tizen::Ui::IPropagatedKeyEventListener
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; };
72 : public Tizen::Ui::Controls::Form
73 , public Tizen::Ui::IActionEventListener
79 bool Initialize(void);
82 virtual result OnInitializing(void);
83 virtual result OnTerminating(void);
84 virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
87 static const int ID_BUTTON_OPEN_POPUP = 501;
88 static const int ID_BUTTON_CLOSE_POPUP = 502;
90 Tizen::Ui::Controls::Popup* __pPopup;
91 PopupEventListener* __pPopupListener;
96 // Sample code for PopupSample.cpp
97 #include <FGraphics.h>
99 #include "PopupSample.h"
101 using namespace Tizen::Graphics;
102 using namespace Tizen::Ui::Controls;
105 PopupEventListener::OnKeyReleased(Control& source, const KeyEventInfo& keyEventInfo)
107 KeyCode key = keyEventInfo.GetKeyCode();
108 if (key == KEY_BACK || key == KEY_ESC)
110 Popup* pPopup = static_cast<Popup *>(&source);
111 pPopup->SetShowState(false);
112 pPopup->Invalidate(true);
119 PopupSample::Initialize(void)
121 Construct(FORM_STYLE_NORMAL);
126 PopupSample::OnInitializing(void)
128 result r = E_SUCCESS;
130 __pPopupListener = new PopupEventListener;
132 // Creates an instance of Popup
133 __pPopup = new Popup;
134 __pPopup->Construct(true, Dimension(600,800));
135 __pPopup->SetTitleText(L"Popup Sample");
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);
143 // Adds the button to the popup
144 __pPopup->AddControl(pCloseButton);
145 __pPopup->SetPropagatedKeyEventListener(__pPopupListener);
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);
153 // Adds the button to the form
154 AddControl(pOpenButton);
160 PopupSample::ShowPopup(void)
162 __pPopup->SetShowState(true);
167 PopupSample::HidePopup(void)
169 __pPopup->SetShowState(false);
174 PopupSample::OnTerminating(void)
176 result r = E_SUCCESS;
178 // Deallocates the __pPopup
180 delete __pPopupListener;
186 PopupSample::OnActionPerformed(const Control& source, int actionId)
190 case ID_BUTTON_OPEN_POPUP:
195 case ID_BUTTON_CLOSE_POPUP:
208 class _OSP_EXPORT_ Popup
209 : public Tizen::Ui::Window
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.
221 * This destructor overrides Tizen::Base::Object::~Object().
225 virtual ~Popup(void);
228 * Initializes this instance of %Popup with the specified dimensions.
232 * @return An error code
233 * @param[in] hasTitle Set to @c true if the %Popup control has a title, @n
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.
244 result Construct(bool hasTitle, const Tizen::Graphics::Dimension& dim);
247 * Initializes this instance of %Popup with the specified dimensions.
251 * @return An error code
252 * @param[in] hasTitle Set to @c true if the %Popup control has a title, @n
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.
263 result Construct(bool hasTitle, const Tizen::Graphics::FloatDimension& dim);
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.
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.
284 result Construct(const Tizen::Base::String& resourceId);
287 * Initializes this instance of %Popup with the specified layout and dimensions.
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
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.
305 result Construct(const Tizen::Ui::Layout& layout, bool hasTitle, const Tizen::Graphics::Dimension& dim);
308 * Initializes this instance of %Popup with the specified layout and dimensions.
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
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.
326 result Construct(const Tizen::Ui::Layout& layout, bool hasTitle, const Tizen::Graphics::FloatDimension& dim);
329 * Initializes this instance of %Popup with the specified layouts and dimensions.
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
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.
348 result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, bool hasTitle, const Tizen::Graphics::Dimension& dim);
351 * Initializes this instance of %Popup with the specified layouts and dimensions.
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
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.
370 result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, bool hasTitle, const Tizen::Graphics::FloatDimension& dim);
373 * Shows the modal window. @n
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.
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.
386 result DoModal(int& modalResult);
389 * Closes the modal window. @n
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.
399 result EndModal(int modalResult);
402 * Sets the title of the %Popup control.
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.
411 virtual result SetTitleText(const Tizen::Base::String& title);
414 * Gets the title of the %Popup control.
418 * @return The title of the %Popup control
420 Tizen::Base::String GetTitleText(void) const;
423 * Gets the bounds of the client area.
427 * @return The bounds of the client area in a Tizen::Graphics::Rectangle instance
429 Tizen::Graphics::Rectangle GetClientAreaBounds(void) const;
432 * Gets the bounds of the client area.
436 * @return The bounds of the client area in a Tizen::Graphics::FloatRectangle instance
438 Tizen::Graphics::FloatRectangle GetClientAreaBoundsF(void) const;
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.
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.
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.
457 Tizen::Graphics::Canvas* GetClientAreaCanvasN(void) const;
460 * Translates the specified position to the client coordinates.
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()
469 Tizen::Graphics::Point TranslateToClientAreaPosition(const Tizen::Graphics::Point& position) const;
472 * Translates the specified position to the client coordinates.
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()
481 Tizen::Graphics::FloatPoint TranslateToClientAreaPosition(const Tizen::Graphics::FloatPoint& position) const;
484 * Translates the specified client position to the control coordinate.
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()
493 Tizen::Graphics::Point TranslateFromClientAreaPosition(const Tizen::Graphics::Point& clientPosition) const;
496 * Translates the specified client position to the control coordinate.
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()
505 Tizen::Graphics::FloatPoint TranslateFromClientAreaPosition(const Tizen::Graphics::FloatPoint& clientPosition) const;
508 * Gets the color of the %Popup control.
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.
517 Tizen::Graphics::Color GetColor(void) const;
520 * Sets the color of the %Popup control.
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.
529 result SetColor(const Tizen::Graphics::Color& color);
532 * Gets the title text color of the %Popup control.
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.
541 Tizen::Graphics::Color GetTitleTextColor(void) const;
544 * Sets the title text color of the %Popup control.
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.
553 result SetTitleTextColor(const Tizen::Graphics::Color& color);
556 * Gets the data binding context.
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.
565 DataBindingContext* GetDataBindingContextN(void) const;
568 friend class _PopupImpl;
571 * The following methods are reserved and may change its name at any time without
574 virtual void Popup_Reserved1(void) { }
575 virtual void Popup_Reserved2(void) { }
576 virtual void Popup_Reserved3(void) { }
580 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
582 Popup(const Popup& rhs);
585 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
587 Popup& operator =(const Popup& rhs);
592 }}} // Tizen::Ui::Controls
594 #endif //_FUI_CTRL_POPUP_H_