inc/FUiCtrlFrame.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                FUiCtrlFrame.h
  20  * @brief       This is the header file for the %Frame class.
  21  *
  22  * This header file contains the declarations of the %Frame class.
  23  */
  24 #ifndef _FUI_CTRL_FRAME_H_
  25 #define _FUI_CTRL_FRAME_H_
  26
  27 #include <FBaseTypes.h>
  28 #include <FUiWindow.h>
  29 #include <FUiIOrientationEventListener.h>
  30 #include <FUiCtrlFrameTypes.h>
  31
  32 namespace Tizen { namespace Ui { namespace Animations {
  33 class FrameAnimator;
  34 } } } // Tizen::Ui::Animations
  35
  36 namespace Tizen { namespace App {
  37 class _AppFrame;
  38 } } // Tizen::App
  39
  40 namespace Tizen { namespace Ui { namespace Controls
  41 {
  42
  43 class Form;
  44 class IFrameEventListener;
  45
  46 /**
  47  * @class       Frame
  48  * @brief       This class provides the main frame window for an application.
  49  *
  50  * @since       2.0
  51  *
  52  * The %Frame class provides the main frame window for an application.
  53  * A frame is the main top-level window of an application. It is the ultimate parent
  54  * of all application controls.
  55  *
  56  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_frame.htm">Frame</a>.
  57  *
  58  * The following example demonstrates how to use the %Frame class
  59  *
  60  * @code
  61         // Gets a pointer of the frame
  62         Frame *pFrame = UiApp::GetInstance()->GetAppFrame()->GetFrame();
  63
  64         // Creates an instance of canvas
  65         Canvas* pCanvas = new Canvas();
  66         pCanvas->Construct();
  67         pCanvas->DrawText(Point(30, 30), L"FrameSample");
  68
  69         // Calls Invalidate();
  70         pFrame->Invalidate(true);
  71  * @endcode
  72  *
  73  */
  74 class _OSP_EXPORT_ Frame
  75         : public Tizen::Ui::Window
  76 {
  77 public:
  78 // Lifecycle
  79         /**
  80          *      This is the default constructor for this class.
  81          *
  82          * @since               2.0
  83          */
  84         Frame(void);
  85
  86         /**
  87          *      This is the destructor for this class.
  88          *
  89          * @since               2.0
  90          */
  91         virtual ~Frame(void);
  92
  93         /**
  94          * Initializes this instance of %Frame with the specified parameter.
  95          *
  96          * @since               2.0
  97          *
  98          * @return      An error code
  99          * @exception   E_SUCCESS           The method is successful.
 100          * @exception   E_INVALID_ARG       The specified input parameter is invalid.
 101          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation (that
 102          *                                                                      is, the method is called on an instance that is constructed).
 103          * @exception   E_MAX_EXCEEDED      The number of Frames and Forms exceeds the system limitation.
 104          * @exception   E_SYSTEM            A system error has occurred.
 105          * @remarks     The maximum number of Forms that an application can construct is limited by available memory.
 106          */
 107         result Construct(void);
 108
 109         /**
 110          * Initializes this instance of %Frame with the specified position and size.
 111          *
 112          * @since 2.0
 113          *
 114          * @return      An error code
 115          * @param[in]   rect    An instance of the Rectangle class @n
 116          *                              This instance represents the x and y coordinates of the top-left corner @n
 117          *                             of the created window along with its width and height. @n
 118          * @exception   E_SUCCESS       The method is successful.
 119          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 120          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation (that
 121          *                                                                      is, the method is called on an instance that is constructed).
 122          * @exception   E_MAX_EXCEEDED  The number of Frames and Forms exceeds the system limitation.
 123          * @exception   E_SYSTEM        A system error has occurred.
 124          * @remarks     The maximum number of Forms that an application can construct is limited by available memory.
 125          * @remarks     The specified position and size are only applied when the show mode is not #FRAME_SHOW_MODE_FULL_SCREEN.
 126          */
 127         result Construct(const Tizen::Graphics::Rectangle& rect);
 128
 129         /**
 130          * Initializes this instance of %Frame with the specified position and size.
 131          *
 132          * @since 2.1
 133          *
 134          * @return      An error code
 135          * @param[in]   rect    An instance of the FloatRectangle class @n
 136          *                              This instance represents the x and y coordinates of the top-left corner @n
 137          *                             of the created window along with its width and height. @n
 138          * @exception   E_SUCCESS       The method is successful.
 139          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 140          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation (that
 141          *                                                                      is, the method is called on an instance that is constructed).
 142          * @exception   E_MAX_EXCEEDED  The number of Frames and Forms exceeds the system limitation.
 143          * @exception   E_SYSTEM        A system error has occurred.
 144          * @remarks     The maximum number of Forms that an application can construct is limited by available memory.
 145          * @remarks     The specified position and size are only applied when the show mode is not #FRAME_SHOW_MODE_FULL_SCREEN.
 146          */
 147         result Construct(const Tizen::Graphics::FloatRectangle& rect);
 148
 149 // Operation
 150 public:
 151         /**
 152          * Adds an IOrientationEventListener instance. @n
 153          * The added listener can listen to events on the given event dispatcher's context when they are fired.
 154          *
 155          * @since               2.0
 156          *
 157          * @param[in]   listener        The listener to add
 158          * @remarks     When OnOrientationChanged() event is fired, re-position and draw the child controls, but do not explicitly call
 159          *                              the Show() method.
 160          * @see                 RemoveOrientationEventListener()
 161          */
 162         void AddOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
 163
 164         /**
 165          * Adds an IFrameEventListener instance. @n
 166          * The added listener can listen to events on the given event dispatcher's context when they are fired.
 167          *
 168          * @since               2.0
 169          *
 170          * @param[in]   listener        The listener to add
 171          * @see                 RemoveFrameEventListener()
 172          */
 173         void AddFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
 174
 175         /**
 176          * Removes an IOrientationEventListener instance. @n
 177          * The removed listener cannot listen to events when they are fired.
 178          *
 179          * @since               2.0
 180          *
 181          * @param[in]   listener        The listener to remove
 182          * @see                 AddOrientationEventListener()
 183          */
 184         void RemoveOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
 185
 186         /**
 187          * Removes an IFrameEventListener instance. @n
 188          * The removed listener cannot listen to events when they are fired.
 189          *
 190          * @since               2.0
 191          *
 192          * @param[in]   listener                The listener to remove
 193          * @see                 AddFrameEventListener()
 194          */
 195         void RemoveFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
 196
 197 // Accessor
 198 public:
 199         /**
 200          * Gets the current %Form control of the %Frame control.
 201          *
 202          * @since               2.0
 203          *
 204          * @return              The current Form, @n
 205          *                              else @c null if there is no %Form
 206          * @see                 SetCurrentForm()
 207          */
 208         Form* GetCurrentForm(void) const;
 209
 210         /**
 211          * Sets the specified Form control as the current %Form of the %Frame control.
 212          *
 213          * @brief       <i> [Deprecated] </i>
 214          * @deprecated  This API is deprecated.
 215          * @since               2.0
 216          *
 217          * @return              An error code
 218          * @param[in]   form                    The form to set as the current form of the %Frame control
 219          * @exception   E_SUCCESS               The method is successful.
 220          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 221          *                                                              The specified @c form is not a child control of the %Frame control.
 222          * @exception   E_SYSTEM                A system error has occurred.
 223          * @remarks             If a form is set as the current form, it becomes the topmost form amongst its siblings. @n
 224          *                      SetCurrentForm() does not call Invalidate() internally, so if the current form needs to be drawn
 225          *                              immediately, Invalidate() should be called after SetCurrentForm().
 226          *                              Only Frame whose show mode is @c FRAME_SHOW_MODE_FULL_SCREEN can set a Form which has the style of @c FORM_STYLE_INDICATOR as the current form.
 227          */
 228         result SetCurrentForm(const Form& form);
 229
 230         /**
 231          * Sets the specified Form control as the current %Form of the %Frame control.
 232          *
 233          * @since               2.1
 234          *
 235          * @return              An error code
 236          * @param[in]   pForm                   The form to be set as the current form of the %Frame control
 237          * @exception   E_SUCCESS               The method is successful.
 238          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 239          *                                                              The specified @c form is not a child control of the %Frame control.
 240          * @exception   E_SYSTEM                A system error has occurred.
 241          * @remarks             If a form is set as the current form, it becomes the topmost form amongst its siblings. @n
 242          *                      SetCurrentForm() does not call Invalidate() internally, so if the current form needs to be drawn
 243          *                              immediately, Invalidate() should be called after SetCurrentForm().
 244          *                              Only Frame whose show mode is @c FRAME_SHOW_MODE_FULL_SCREEN can set a Form which has the style of @c FORM_STYLE_INDICATOR as the current form.
 245          */
 246         result SetCurrentForm(Form* pForm);
 247
 248         /**
 249          * Gets the background color of the %Frame control.
 250          *
 251          * @since       2.0
 252          *
 253          * @return  The background color of the %Frame control
 254          */
 255         Tizen::Graphics::Color GetBackgroundColor(void) const;
 256
 257         /**
 258          * Sets the background color of the %Frame control.
 259          *
 260          * @since               2.0
 261          *
 262          * @param[in]   color   The background color
 263          */
 264         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 265
 266         /**
 267          * Sets the orientation mode of a frame.
 268          *
 269          * @since       2.0
 270          *
 271          * @feature %http://tizen.org/setting/screen.auto_rotation for the ORIENTATION_AUTOMATIC_FOUR_DIRECTION or ORIENTATION_AUTOMATIC value of @c orientation
 272          * @param[in] orientation                                  The orientation mode of the %Frame control
 273          * @exception  E_UNSUPPORTED_OPERATION               The Emulator or target device does not support the required feature. @b Since: @b 2.1
 274          * For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 275          * @remarks
 276          *              - The specific error code can be accessed using the GetLastResult() method.
 277          *              - To see the change in the orientation mode, the corresponding frame must be the topmost frame in the z-order hierarchy.
 278          */
 279         void SetOrientation(Tizen::Ui::Orientation orientation);
 280
 281         /**
 282          * Gets the orientation mode of the frame.
 283          *
 284          * @since       2.0
 285          *
 286          * @return  The orientation mode of the frame
 287          */
 288         Tizen::Ui::Orientation GetOrientation(void) const;
 289
 290         /**
 291          * Gets the current orientation status of the frame.
 292          *
 293          * @since       2.0
 294          *
 295          * @return      The orientation status
 296          * @remarks     The method returns ORIENTATION_STATUS_NONE if the %Frame control is not drawn.
 297          *          Once it is drawn, the orientation of the %Frame control is set to portrait and the method
 298          *          returns ORIENTATION_STATUS_PORTRAIT if the application has not specified its orientation.
 299          */
 300         Tizen::Ui::OrientationStatus GetOrientationStatus(void) const;
 301
 302         /**
 303          * Gets the FrameAnimator of %Frame.
 304          *
 305          * @since               2.0
 306          *
 307          * @return              %FrameAnimator, @n
 308          *                              else @c null if this instance is not constructed as yet
 309          */
 310         Tizen::Ui::Animations::FrameAnimator* GetFrameAnimator(void) const;
 311
 312         /**
 313          * Sets the mode to show the %Frame control.
 314          *
 315          * @since 2.0
 316          *
 317          * @return      An error code
 318          * @param[in] mode      The mode to show the %Frame control
 319          * @exception   E_SUCCESS       The method is successful.
 320          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 321          * @remarks     The default mode is #FRAME_SHOW_MODE_FULL_SCREEN.
 322          */
 323         result SetShowMode(FrameShowMode mode);
 324
 325         /**
 326          * Gets the mode to show the %Frame control.
 327          *
 328          * @since 2.0
 329          *
 330          * @return      The mode to show the %Frame control
 331          * @remarks     The default mode is #FRAME_SHOW_MODE_FULL_SCREEN.
 332          */
 333         FrameShowMode GetShowMode(void) const;
 334
 335 protected:
 336         friend class _FrameImpl;
 337
 338         //
 339         //This method is for internal use only. Using this method can cause behavioral, security-related,
 340         //and consistency-related issues in the application.
 341         //
 342         // This method is reserved and may change its name at any time without
 343         // prior notice.
 344         //
 345         // @since 2.0
 346         //
 347         virtual void Frame_Reserved1(void) { }
 348
 349         //
 350         //This method is for internal use only. Using this method can cause behavioral, security-related,
 351         //and consistency-related issues in the application.
 352         //
 353         // This method is reserved and may change its name at any time without
 354         // prior notice.
 355         //
 356         // @since 2.0
 357         //
 358         virtual void Frame_Reserved2(void) { }
 359
 360         //
 361         //This method is for internal use only. Using this method can cause behavioral, security-related,
 362         //and consistency-related issues in the application.
 363         //
 364         // This method is reserved and may change its name at any time without
 365         // prior notice.
 366         //
 367         // @since 2.0
 368         //
 369         virtual void Frame_Reserved3(void) { }
 370
 371         //
 372         //This method is for internal use only. Using this method can cause behavioral, security-related,
 373         //and consistency-related issues in the application.
 374         //
 375         // This method is reserved and may change its name at any time without
 376         // prior notice.
 377         //
 378         // @since 2.0
 379         //
 380         virtual void Frame_Reserved4(void) { }
 381
 382         //
 383         //This method is for internal use only. Using this method can cause behavioral, security-related,
 384         //and consistency-related issues in the application.
 385         //
 386         // This method is reserved and may change its name at any time without
 387         // prior notice.
 388         //
 389         // @since 2.0
 390         //
 391         virtual void Frame_Reserved5(void) { }
 392
 393 private:
 394         Frame(const Frame&);
 395         Frame& operator =(const Frame&);
 396 }; // Frame
 397
 398 }}} // Tizen::Ui::Controls
 399
 400 #endif // _FUI_CTRL_FRAME_H_
 401