inc/FUiCtrlPopup.h

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