inc/FUiCtrlFrame.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                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 Tizen::Graphics::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
 125          *                              - The maximum number of Forms that an application can construct is limited by available memory.
 126          *                              - The specified position and size are only applied when the show mode is not ::FRAME_SHOW_MODE_FULL_SCREEN.
 127          */
 128         result Construct(const Tizen::Graphics::Rectangle& rect);
 129
 130         /**
 131          * Initializes this instance of %Frame with the specified position and size.
 132          *
 133          * @since 2.1
 134          *
 135          * @return      An error code
 136          * @param[in]   rect    An instance of the Tizen::Graphics::FloatRectangle class @n
 137          *                              This instance represents the x and y coordinates of the top-left corner @n
 138          *                             of the created window along with its width and height. @n
 139          * @exception   E_SUCCESS       The method is successful.
 140          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 141          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation (that
 142          *                                                                      is, the method is called on an instance that is constructed).
 143          * @exception   E_MAX_EXCEEDED  The number of Frames and Forms exceeds the system limitation.
 144          * @exception   E_SYSTEM        A system error has occurred.
 145          * @remarks
 146          *                              - The maximum number of Forms that an application can construct is limited by available memory.
 147          *                              - The specified position and size are only applied when the show mode is not ::FRAME_SHOW_MODE_FULL_SCREEN.
 148          */
 149         result Construct(const Tizen::Graphics::FloatRectangle& rect);
 150
 151 // Operation
 152 public:
 153         /**
 154          * Adds an IOrientationEventListener instance. @n
 155          * The added listener can listen to events on the given event dispatcher's context when they are fired.
 156          *
 157          * @since               2.0
 158          *
 159          * @param[in]   listener        The listener to add
 160          * @remarks     When OnOrientationChanged() event is fired, re-position and draw the child controls, but do not explicitly call
 161          *                              the Show() method.
 162          * @see                 RemoveOrientationEventListener()
 163          */
 164         void AddOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
 165
 166         /**
 167          * Adds an IFrameEventListener instance. @n
 168          * The added listener can listen to events on the given event dispatcher's context when they are fired.
 169          *
 170          * @since               2.0
 171          *
 172          * @param[in]   listener        The listener to add
 173          * @see                 RemoveFrameEventListener()
 174          */
 175         void AddFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
 176
 177         /**
 178          * Removes an IOrientationEventListener instance. @n
 179          * The removed listener cannot listen to events when they are fired.
 180          *
 181          * @since               2.0
 182          *
 183          * @param[in]   listener        The listener to remove
 184          * @see                 AddOrientationEventListener()
 185          */
 186         void RemoveOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
 187
 188         /**
 189          * Removes an IFrameEventListener instance. @n
 190          * The removed listener cannot listen to events when they are fired.
 191          *
 192          * @since               2.0
 193          *
 194          * @param[in]   listener                The listener to remove
 195          * @see                 AddFrameEventListener()
 196          */
 197         void RemoveFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
 198
 199 // Accessor
 200 public:
 201         /**
 202          * Gets the current %Form control of the %Frame control.
 203          *
 204          * @since               2.0
 205          *
 206          * @return              The current Form, @n
 207          *                              else @c null if there is no %Form
 208          * @see                 SetCurrentForm()
 209          */
 210         Form* GetCurrentForm(void) const;
 211
 212         /**
 213          * Sets the specified Form control as the current %Form of the %Frame control.
 214          *
 215          * @brief       <i> [Deprecated] </i>
 216          * @deprecated  This method is deprecated.
 217          * @since               2.0
 218          *
 219          * @return              An error code
 220          * @param[in]   form                    The form to set as the current form of the %Frame control
 221          * @exception   E_SUCCESS               The method is successful.
 222          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 223          *                                                              The specified @c form is not a child control of the %Frame control.
 224          * @exception   E_SYSTEM                A system error has occurred.
 225          * @remarks
 226          *                              - If a form is set as the current form, it becomes the topmost form amongst its siblings.
 227          *                              - This method does not call Invalidate() internally, so if the current form needs to be drawn
 228          *                              immediately, Invalidate() should be called after SetCurrentForm().
 229          *                              - Only Frame whose show mode is ::FRAME_SHOW_MODE_FULL_SCREEN
 230          *                              can set a Form which has the style of ::FORM_STYLE_PORTRAIT_INDICATOR as the current form.
 231          */
 232         result SetCurrentForm(const Form& form);
 233
 234         /**
 235          * Sets a specified Form control as the current %Form of the %Frame control.
 236          *
 237          * @since               2.1
 238          *
 239          * @return              An error code
 240          * @param[in]   pForm                   The form to set as the current form of the %Frame control
 241          * @exception   E_SUCCESS               The method is successful.
 242          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 243          *                                                              The specified @c form is not a child control of the %Frame control.
 244          * @exception   E_SYSTEM                A system error has occurred.
 245          * @remarks
 246          *                              - If a form is set as the current form, it becomes the topmost form amongst its siblings.
 247          *                              - This method does not call Invalidate() internally, so if the current form needs to be drawn
 248          *                              immediately, Invalidate() should be called after SetCurrentForm().
 249          *                              - Only Frame whose show mode is ::FRAME_SHOW_MODE_FULL_SCREEN can set a Form which has
 250          *                              the style of ::FORM_STYLE_PORTRAIT_INDICATOR as the current form.
 251          */
 252         result SetCurrentForm(Form* pForm);
 253
 254         /**
 255          * Gets the background color of the %Frame control.
 256          *
 257          * @since       2.0
 258          *
 259          * @return  The background color of the %Frame control
 260          */
 261         Tizen::Graphics::Color GetBackgroundColor(void) const;
 262
 263         /**
 264          * Sets the background color of the %Frame control.
 265          *
 266          * @since               2.0
 267          *
 268          * @param[in]   color   The background color
 269          */
 270         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 271
 272         /**
 273          * Sets the orientation mode of a frame.
 274          *
 275          * @since               2.0
 276          *
 277          * @feature %http://tizen.org/feature/screen.auto_rotation for the @c ORIENTATION_AUTOMATIC_FOUR_DIRECTION or
 278          *                      @c ORIENTATION_AUTOMATIC value of @c orientation
 279          * @param[in] orientation                                  The orientation mode of the %Frame control
 280          * @exception  E_UNSUPPORTED_OPERATION               The Emulator or target device does not support the required feature. @b Since: @b 2.1 @n
 281          * For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 282          * @remarks
 283          *              - The specific error code can be accessed using the GetLastResult() method.
 284          *              - To see the change in the orientation mode, the corresponding frame must be the topmost frame in the z-order hierarchy.
 285          */
 286         void SetOrientation(Tizen::Ui::Orientation orientation);
 287
 288         /**
 289          * Gets the orientation mode of the frame.
 290          *
 291          * @since       2.0
 292          *
 293          * @return  The orientation mode of the frame
 294          */
 295         Tizen::Ui::Orientation GetOrientation(void) const;
 296
 297         /**
 298          * Gets the current orientation status of the frame.
 299          *
 300          * @since       2.0
 301          *
 302          * @return      The orientation status
 303          * @remarks     The method returns @c ORIENTATION_STATUS_NONE if the %Frame control is not drawn.
 304          *          Once it is drawn, the orientation of the %Frame control is set to portrait and the method
 305          *          returns @c ORIENTATION_STATUS_PORTRAIT if the application has not specified its orientation.
 306          */
 307         Tizen::Ui::OrientationStatus GetOrientationStatus(void) const;
 308
 309         /**
 310          * Gets the FrameAnimator of %Frame.
 311          *
 312          * @since               2.0
 313          *
 314          * @return              %FrameAnimator, @n
 315          *                              else @c null if this instance is not constructed as yet
 316          */
 317         Tizen::Ui::Animations::FrameAnimator* GetFrameAnimator(void) const;
 318
 319         /**
 320          * Sets the mode to show the %Frame control.
 321          *
 322          * @since 2.0
 323          *
 324          * @return      An error code
 325          * @param[in] mode      The mode to show the %Frame control
 326          * @exception   E_SUCCESS       The method is successful.
 327          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 328          * @remarks     The default mode is ::FRAME_SHOW_MODE_FULL_SCREEN.
 329          */
 330         result SetShowMode(FrameShowMode mode);
 331
 332         /**
 333          * Gets the mode to show the %Frame control.
 334          *
 335          * @since 2.0
 336          *
 337          * @return      The mode to show the %Frame control
 338          * @remarks     The default mode is ::FRAME_SHOW_MODE_FULL_SCREEN.
 339          */
 340         FrameShowMode GetShowMode(void) const;
 341
 342 protected:
 343         friend class _FrameImpl;
 344
 345         //
 346         //This method is for internal use only. Using this method can cause behavioral, security-related,
 347         //and consistency-related issues in the application.
 348         //
 349         // This method is reserved and may change its name at any time without
 350         // prior notice.
 351         //
 352         // @since 2.0
 353         //
 354         virtual void Frame_Reserved1(void) { }
 355
 356         //
 357         //This method is for internal use only. Using this method can cause behavioral, security-related,
 358         //and consistency-related issues in the application.
 359         //
 360         // This method is reserved and may change its name at any time without
 361         // prior notice.
 362         //
 363         // @since 2.0
 364         //
 365         virtual void Frame_Reserved2(void) { }
 366
 367         //
 368         //This method is for internal use only. Using this method can cause behavioral, security-related,
 369         //and consistency-related issues in the application.
 370         //
 371         // This method is reserved and may change its name at any time without
 372         // prior notice.
 373         //
 374         // @since 2.0
 375         //
 376         virtual void Frame_Reserved3(void) { }
 377
 378         //
 379         //This method is for internal use only. Using this method can cause behavioral, security-related,
 380         //and consistency-related issues in the application.
 381         //
 382         // This method is reserved and may change its name at any time without
 383         // prior notice.
 384         //
 385         // @since 2.0
 386         //
 387         virtual void Frame_Reserved4(void) { }
 388
 389         //
 390         //This method is for internal use only. Using this method can cause behavioral, security-related,
 391         //and consistency-related issues in the application.
 392         //
 393         // This method is reserved and may change its name at any time without
 394         // prior notice.
 395         //
 396         // @since 2.0
 397         //
 398         virtual void Frame_Reserved5(void) { }
 399
 400 private:
 401         Frame(const Frame&);
 402         Frame& operator =(const Frame&);
 403 }; // Frame
 404
 405 }}} // Tizen::Ui::Controls
 406
 407 #endif // _FUI_CTRL_FRAME_H_