inc/FUiCtrlMessageBox.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         FUiCtrlMessageBox.h
  20 * @brief        This is the header file for the %MessageBox class.
  21 *
  22 * This header file contains the declarations of the %MessageBox class.
  23 */
  24
  25 #ifndef _FUI_CTRL_MESSAGE_BOX_H_
  26 #define _FUI_CTRL_MESSAGE_BOX_H_
  27
  28 #include <FUiWindow.h>
  29
  30 namespace Tizen { namespace Ui { namespace Controls
  31 {
  32
  33 /**
  34  * @enum        MessageBoxStyle
  35  *
  36  * Defines the %MessageBox style.
  37  *
  38  * @since       2.0
  39  */
  40 enum MessageBoxStyle
  41 {
  42         MSGBOX_STYLE_NONE,                      /**< The message box does not contain push buttons: NONE */
  43         MSGBOX_STYLE_OK,                        /**< The message box contains one push button: OK */
  44         MSGBOX_STYLE_CANCEL,                    /**< The message box contains one push button: CANCEL */
  45         MSGBOX_STYLE_OKCANCEL,                  /**< The message box contains two push buttons: OK and CANCEL */
  46         MSGBOX_STYLE_YESNO,                     /**< The message box contains two push buttons: YES and NO */
  47         MSGBOX_STYLE_YESNOCANCEL,               /**< The message box contains three push buttons: YES, NO and CANCEL */
  48         MSGBOX_STYLE_ABORTRETRYIGNORE,          /**< The message box contains three push buttons: ABORT, RETRY, and IGNORE */
  49         MSGBOX_STYLE_CANCELTRYCONTINUE,         /**< The message box contains three push buttons: CANCEL, TRY, and CONTINUE */
  50         MSGBOX_STYLE_RETRYCANCEL                /**< The message box contains two push buttons: RETRY and CANCEL */
  51 };
  52
  53
  54 /**
  55  * @enum        MessageBoxModalResult
  56  *
  57  * Defines the %MessageBox notifications.
  58  *
  59  * @since       2.0
  60  */
  61 enum MessageBoxModalResult
  62 {
  63
  64         MSGBOX_RESULT_CLOSE,                /**< The message box is closed */
  65         MSGBOX_RESULT_OK,                   /**< The OK button is selected */
  66         MSGBOX_RESULT_CANCEL,               /**< The cancel button is selected */
  67         MSGBOX_RESULT_YES,                  /**< The Yes button is selected */
  68         MSGBOX_RESULT_NO,                   /**< The No button is selected */
  69         MSGBOX_RESULT_ABORT,                /**< The Abort button is selected */
  70         MSGBOX_RESULT_TRY,                  /**< The Try button is selected */
  71         MSGBOX_RESULT_RETRY,                /**< The Retry button is selected */
  72         MSGBOX_RESULT_IGNORE,               /**< The Ignore button is selected */
  73         MSGBOX_RESULT_CONTINUE,             /**< The Continue button is selected */
  74 };
  75
  76
  77 /**
  78 * @class        MessageBox
  79 * @brief        This class implements a message box.
  80 *
  81 * @since        2.0
  82 *
  83 * The %MessageBox class displays a confirmation message when the user is asked to confirm an action, or a warning message when the
  84 * user wants to continue a potentially dangerous action. It can also display information, question, alarm, and lock messages, or
  85 * the user selections.
  86 *
  87 * For more information on the class features,
  88 * see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_popup_messagebox.htm">Popup and MessageBox</a>.
  89 *
  90 * The following example demonstrates how to use the %MessageBox class.
  91 *
  92 * @code
  93 // Sample code for MessageBoxSample.h
  94 #include <FUi.h>
  95
  96 class MessageBoxSample
  97         : public Tizen::Ui::Controls::Form
  98         , public Tizen::Ui::IActionEventListener
  99 {
 100 public:
 101         bool Initialize(void);
 102         void OpenMessageBox(void);
 103         virtual result OnInitializing(void);
 104         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
 105
 106 protected:
 107         static const int ID_BTN_DO_SOMETHING = 101;
 108 };
 109  *      @endcode
 110  *
 111  *      @code
 112 // Sample code for MessageBoxSample.cpp
 113 #include <FGraphics.h>
 114
 115 #include "MessageBoxSample.h"
 116
 117 using namespace Tizen::Graphics;
 118 using namespace Tizen::Ui::Controls;
 119
 120 bool
 121 MessageBoxSample::Initialize(void)
 122 {
 123         Construct(FORM_STYLE_NORMAL);
 124         return true;
 125 }
 126
 127 result
 128 MessageBoxSample::OnInitializing(void)
 129 {
 130         result r = E_SUCCESS;
 131
 132         // Creates an instance of Button
 133         Button* pButton = new Button();
 134         pButton->Construct(Rectangle(10, 10, 350, 60), L"MessageBox Test");
 135         pButton->SetActionId(ID_BTN_DO_SOMETHING);
 136         pButton->AddActionEventListener(*this);
 137
 138         // Adds the button to the form
 139         AddControl(pButton);
 140
 141         return r;
 142 }
 143
 144 void
 145 MessageBoxSample::OpenMessageBox(void)
 146 {
 147         // Creates an instance of MessageBox
 148         MessageBox messageBox;
 149         messageBox.Construct(L"MessageBox Title", L"MessageBox Sample Code.", MSGBOX_STYLE_OK, 3000);
 150
 151         int modalResult = 0;
 152
 153         // Calls ShowAndWait() : Draws and Shows itself and processes events
 154         messageBox.ShowAndWait(modalResult);
 155
 156         switch (modalResult)
 157         {
 158         case MSGBOX_RESULT_OK:
 159                 {
 160                         // ....
 161                 }
 162                 break;
 163         default:
 164                 break;
 165         }
 166 }
 167
 168 void
 169 MessageBoxSample::OnActionPerformed(const Control& source, int actionId)
 170 {
 171         switch (actionId)
 172         {
 173         case ID_BTN_DO_SOMETHING:
 174                 {
 175                         OpenMessageBox();
 176                 }
 177                 break;
 178         default:
 179                 break;
 180         }
 181 }
 182 * @endcode
 183 */
 184
 185 class _OSP_EXPORT_ MessageBox
 186         : public Tizen::Ui::Window
 187 {
 188 public:
 189         /**
 190          * The object is not fully constructed after this constructor is called.  @n
 191          * For full construction, the MessageBox::Construct() method must be called right after calling this constructor.
 192          *
 193          * @since       2.0
 194          */
 195         MessageBox(void);
 196
 197         /**
 198          * This destructor overrides Tizen::Base::Object::~Object().
 199          *
 200          * @since       2.0
 201          */
 202         virtual ~MessageBox(void);
 203
 204         /**
 205          * Initializes this instance of %MessageBox with the specified parameters.
 206          *
 207          * @since               2.0
 208          *
 209          * @return              An error code
 210          * @param[in]   title                           The title string to set
 211          * @param[in]   text                            The text string to set
 212          * @param[in]   style                           The style of the %MessageBox control
 213          * @param[in]   timeout                         The duration of the timeout in milliseconds
 214          * @exception   E_SUCCESS                       The method is successful.
 215          * @exception   E_SYSTEM                        A system error has occurred.
 216          * @exception   E_INVALID_ARG           The specified @c text is too long.
 217          * @remarks
 218          *                              - To create a %MessageBox control, call ShowAndWait() after the Construct() method is called.
 219          *                              - The message box text cannot contain over @c 399 characters.
 220          *                              - To display the text in multi-lines or to denote the end of line use '\\n'.
 221          *                              - The default owner will be the current Form (or Frame). It is possible that this control may not be visible
 222          *                              due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
 223          * @see                 ShowAndWait()
 224          */
 225         result Construct(const Tizen::Base::String& title, const Tizen::Base::String& text, MessageBoxStyle style, unsigned long timeout = 0);
 226
 227 public:
 228         /**
 229          * Runs the modal window. @n
 230          * This method should be called only after calling the Construct() method.
 231          *
 232          * @since               2.0
 233          *
 234          * @return              An error code
 235          * @param[out]  modalResult             The %MessageBox notification
 236          * @exception   E_SUCCESS           The method is successful.
 237          * @exception   E_SYSTEM            A system error has occurred.
 238          */
 239         virtual result ShowAndWait(int& modalResult);
 240
 241         /**
 242          * Gets the text of the %MessageBox control.
 243          *
 244          * @since               2.0
 245          *
 246          * @return              The text of this %MessageBox instance, @n
 247          *                              else an empty string if the instance is invalid
 248          */
 249         Tizen::Base::String GetText(void) const;
 250
 251         /**
 252          * Gets the title of the %MessageBox control.
 253          *
 254          * @since               2.0
 255          *
 256          * @return              The title of this %MessageBox instance, @n
 257          *                              else an empty string if the instance is invalid
 258          */
 259         Tizen::Base::String GetTitleText(void) const;
 260
 261         /**
 262          * Gets the style of the current %MessageBox.
 263          *
 264          * @since               2.0
 265          *
 266          * @return              The style of the current %MessageBox, @n
 267          *                              else @c MSGBOX_STYLE_NONE if the instance is invalid
 268          */
 269         MessageBoxStyle GetMessageBoxStyle(void) const;
 270
 271         /**
 272          * Gets the timeout value of %MessageBox.
 273          *
 274          * @since               2.0
 275          *
 276          * @return              The timeout value in milliseconds, @n
 277          *                              else @c 0 if the instance is invalid
 278          */
 279         virtual unsigned long GetTimeout(void) const;
 280
 281         /**
 282          * Sets the color of the %MessageBox control.
 283          *
 284          * @since 2.0
 285          *
 286          * @param[in]   color           The color to set
 287          */
 288         void SetColor(const Tizen::Graphics::Color& color);
 289
 290         /**
 291          * Gets the color of the %MessageBox control.
 292          *
 293          * @since 2.0
 294          *
 295          * @return      The color to set
 296          */
 297         Tizen::Graphics::Color GetColor(void) const;
 298
 299         /**
 300          * Sets the title text color of the %MessageBox control.
 301          *
 302          * @since 2.0
 303          *
 304          * @param[in]   color           The title text color to set
 305          */
 306         void SetTitleTextColor(const Tizen::Graphics::Color& color);
 307
 308         /**
 309          * Gets the title text color of the %MessageBox control.
 310          *
 311          * @since 2.0
 312          *
 313          * @return              The title text color
 314          */
 315         Tizen::Graphics::Color GetTitleTextColor(void) const;
 316
 317         /**
 318          * Sets the text color of the %MessageBox control.
 319          *
 320          * @since 2.0
 321          *
 322          * @param[in]   color           The text color to set
 323          */
 324         void SetTextColor(const Tizen::Graphics::Color& color);
 325
 326         /**
 327          * Gets the text color of the %MessageBox control.
 328          *
 329          * @since 2.0
 330          *
 331          * @return              The text color
 332          */
 333         Tizen::Graphics::Color GetTextColor(void) const;
 334
 335 protected:
 336         friend class _MessageBoxImpl;
 337
 338 private:
 339         //
 340         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 341         //
 342         MessageBox(const MessageBox& rhs);
 343
 344         //
 345         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 346         //
 347         MessageBox& operator =(const MessageBox& rhs);
 348
 349 };  // MessageBox
 350
 351
 352 }}} // Tizen::Ui::Controls
 353
 354 #endif  // _FUI_CTRL_MESSAGE_BOX_H_