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         delete __pPopup;
 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 and child controls with the specified resource ID @n
 210          *
 211          * This method first attempts to find the resource file in the folder that corresponds to the current screen resolution. @n
 212          * 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
 213          * the density folder that corresponds to the current screen size category  "res/screen-size-normal/" folder.
 214          *
 215          * @since         2.0
 216          *
 217          * @return     An error code
 218          * @param[in]  resourceId              The resource ID describing the %Popup control
 219          * @exception  E_SUCCESS               The method is successful.
 220          * @exception  E_FILE_NOT_FOUND        The specified file cannot be found.
 221          * @exception  E_INVALID_FORMAT        The specified XML format is invalid.
 222          * @exception  E_OPERATION_FAILED      The operation has failed.
 223          */
 224         result Construct(const Tizen::Base::String& resourceId);
 225
 226         /**
 227          * Initializes this instance of %Popup with the specified layout and dimensions.
 228          *
 229          * @since               2.0
 230          *
 231          * @return              An error code
 232          * @param[in]   layout                          The layout for both the portrait and landscape mode
 233          * @param[in]   hasTitle                Set to @c true if the %Popup control should have a title, @n
 234          *                                                              else @c false
 235          * @param[in]   dim                             The size of the %Popup control
 236          * @exception   E_SUCCESS               The method is successful.
 237          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
 238          *                                                                      the specified layout is already bound to another container.
 239          * @exception   E_SYSTEM                A system error has occurred.
 240          */
 241         result Construct(const Tizen::Ui::Layout& layout, bool hasTitle, const Tizen::Graphics::Dimension& dim);
 242
 243         /**
 244          * Initializes this instance of %Popup with the specified layouts and dimensions.
 245          *
 246          * @since               2.0
 247          *
 248          * @return              An error code
 249          * @param[in]   portraitLayout          The layout for the portrait mode
 250          * @param[in]   landscapeLayout         The layout for the landscape mode
 251          * @param[in]   hasTitle                        Set to @c true if this %Popup control should have a title, @n
 252          *                                                                      else @c false
 253          * @param[in]   dim                             The size of the %Popup control
 254          * @exception   E_SUCCESS               The method is successful.
 255          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or
 256          *                                                                      the specified layout is already bound to another container.
 257          * @exception   E_SYSTEM                A system error has occurred.
 258          */
 259         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, bool hasTitle, const Tizen::Graphics::Dimension& dim);
 260
 261         /**
 262          * Shows the modal window. @n
 263          *
 264          * @since 2.0
 265          * @return                   An error code
 266          * @param[out]   modalResult           The %Popup's notification. @n
 267          *                                     This value is the 'modalResult' parameter of the EndModal() method
 268          * @exception     E_SUCCESS            The method is successful.
 269          * @exception     E_INVALID_STATE    The %Popup is not visible. The visible state of the %Popup should be set @c true.
 270          * @remarks      Do not call this method from Tizen::App::App::OnAppInitializing(). @n
 271          *                   To show a %Popup properly from Tizen::Ui::Controls::Form::OnInitializing(), theForm must
 272          *                   have been successfully drawn before the DoModal() method.
 273          */
 274         result DoModal(int& modalResult);
 275
 276         /**
 277          * Closes the modal window. @n
 278          *
 279          * @since 2.0
 280          * @return                  An error code
 281          * @param[in]     modalResult                           The result value of the modal window. @n
 282          *                                                                 The value which needs to be returned as the output parameter of DoModal() method should be passed as the input argument
 283          * @exception     E_SUCCESS                            The method is successful.
 284          * @exception     E_INVALID_STATE                    The method is not supported because this popup isn't running as a modal window.
 285          */
 286         result EndModal(int modalResult);
 287
 288         /**
 289          * Sets the title of the %Popup control.
 290          *
 291          * @since               2.0
 292          *
 293          * @return              An error code
 294          * @param[in]   title           The title to be set
 295          * @exception   E_SUCCESS       The method is successful.
 296          * @exception   E_SYSTEM        A system error has occurred.
 297          */
 298         virtual result SetTitleText(const Tizen::Base::String& title);
 299
 300         /**
 301          * Gets the title of the %Popup control.
 302          *
 303          * @since               2.0
 304          *
 305          * @return              The title of the %Popup control
 306          */
 307         Tizen::Base::String GetTitleText(void) const;
 308
 309         /**
 310          * Gets the bounds of the client area.
 311          *
 312          * @since               2.0
 313          *
 314          * @return              The bounds of the client area in a Rectangle instance
 315          */
 316         Tizen::Graphics::Rectangle GetClientAreaBounds(void) const;
 317
 318         /**
 319          * Creates and returns a graphics canvas whose bounds (position and size) are equal to the bounds of the client area of the %Popup control.
 320          *
 321          * @since               2.0
 322          *
 323          * @return              The graphic canvas of the %Popup control, @n
 324          *                              else @c null if an error occurs
 325          * @exception   E_SUCCESS                                       The method is successful.
 326          * @exception   E_RESOURCE_UNAVAILABLE          The required resource is currently unavailable.
 327          * @remarks             The method allocates a Tizen::Graphics::Canvas whose bounds are equal to that of the client area of the %Popup control. @n
 328          *                              It is the responsibility of the developers to deallocate the canvas after use.
 329          * @remarks             The canvas is valid only if the properties of the parent control of the canvas remain unchanged. @n
 330          *                              Therefore, delete the previously allocated canvas and create a new canvas using the GetCanvasN() method if the size or position of the
 331          *                              control is changed.
 332          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 333          */
 334         Tizen::Graphics::Canvas* GetClientAreaCanvasN(void) const;
 335
 336         /**
 337          * Translates the specified position to the client coordinates.
 338          *
 339          * @since       2.0
 340          *
 341          * @return      The position in relative to the top-left corner of the client-area, @n
 342          *                              else @c (-1,-1) if the instance is invalid
 343          * @param[in]   position        The position relative to the top-left corner of the %Popup control
 344          * @see         TranslateFromClientAreaPosition()
 345          */
 346         Tizen::Graphics::Point TranslateToClientAreaPosition(const Tizen::Graphics::Point& position) const;
 347
 348         /**
 349          * Translates the specified client position to the control coordinate.
 350          *
 351          * @since       2.0
 352          *
 353          * @return      The position in relative to the top-left corner of the %Popup control, @n
 354          *                              else @c (-1,-1) if the instance is invalid
 355          * @param[in]   clientPosition          The position relative to the top-left corner of the client area
 356          * @see         TranslateToClientAreaPosition()
 357          */
 358         Tizen::Graphics::Point TranslateFromClientAreaPosition(const Tizen::Graphics::Point& clientPosition) const;
 359
 360         /**
 361          * Gets the color of the %Popup control.
 362          *
 363          * @since       2.0
 364          *
 365          * @return      The color, @n
 366          *                              else RGBA(0, 0, 0, 0) if an error occurs
 367          * @exception   E_SUCCESS            The method is successful.
 368          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 369          */
 370         Tizen::Graphics::Color GetColor(void) const;
 371
 372         /**
 373          * Sets the color of the %Popup control.
 374          *
 375          * @since       2.0
 376          *
 377          * @return      An error code
 378          * @param[in]   color               The color to be set
 379          * @exception   E_SUCCESS           The method is successful.
 380          * @exception   E_SYSTEM            A system error has occurred.
 381          */
 382         result SetColor(const Tizen::Graphics::Color& color);
 383
 384         /**
 385          * Gets the title text color of the %Popup control.
 386          *
 387          * @since               2.0
 388          *
 389          * @return              The color, @n
 390          *                              else RGBA(0, 0, 0, 0) if an error occurs
 391          * @exception   E_SUCCESS                       The method is successful.
 392          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 393          */
 394         Tizen::Graphics::Color GetTitleTextColor(void) const;
 395
 396         /**
 397          * Sets the title text color of the %Popup control.
 398          *
 399          * @since       2.0
 400          *
 401          * @return      An error code
 402          * @param[in]   color                The title text color
 403          * @exception   E_SUCCESS            The method is successful.
 404          * @exception   E_SYSTEM             A system error has occurred.
 405          */
 406         result SetTitleTextColor(const Tizen::Graphics::Color& color);
 407
 408         /**
 409          * Gets the data binding context.
 410          *
 411          * @since 2.0
 412          *
 413          * @return       The data binding context
 414          * @exception    E_SUCCESS        The method is successful.
 415          * @exception    E_SYSTEM         A system error has occurred.
 416          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 417          */
 418         DataBindingContext* GetDataBindingContextN(void) const;
 419
 420 protected:
 421         friend class _PopupImpl;
 422
 423         //
 424         // The following methods are reserved and may change its name at any time without
 425         // prior notice.
 426         //
 427         virtual void Popup_Reserved1(void) { }
 428         virtual void Popup_Reserved2(void) { }
 429         virtual void Popup_Reserved3(void) { }
 430
 431 private:
 432         //
 433         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 434         //
 435         Popup(const Popup& rhs);
 436
 437         //
 438         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 439         //
 440         Popup& operator =(const Popup& rhs);
 441
 442 }; // Popup
 443
 444
 445 }}} // Tizen::Ui::Controls
 446
 447 #endif  //_FUI_CTRL_POPUP_H_