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 // Operation
 130 public:
 131         /**
 132          * Adds an IOrientationEventListener instance. @n
 133          * The added listener can listen to events on the given event dispatcher's context when they are fired.
 134          *
 135          * @since               2.0
 136          *
 137          * @param[in]   listener        The listener to be added
 138          * @remarks     When OnOrientationChanged() event is fired, re-position and draw the child controls, but do not explicitly call
 139          *                              the Show() method.
 140          * @see                 RemoveOrientationEventListener()
 141          */
 142         void AddOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
 143
 144         /**
 145          * Adds an IFrameEventListener instance. @n
 146          * The added listener can listen to events on the given event dispatcher's context when they are fired.
 147          *
 148          * @since               2.0
 149          *
 150          * @param[in]   listener        The listener to be added
 151          * @see                 RemoveFrameEventListener()
 152          */
 153         void AddFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
 154
 155         /**
 156          * Removes an IOrientationEventListener instance. @n
 157          * The removed listener cannot listen to events when they are fired.
 158          *
 159          * @since               2.0
 160          *
 161          * @param[in]   listener        The listener to be removed
 162          * @see                 AddOrientationEventListener()
 163          */
 164         void RemoveOrientationEventListener(Tizen::Ui::IOrientationEventListener& listener);
 165
 166         /**
 167          * Removes an IFrameEventListener instance. @n
 168          * The removed listener cannot listen to events when they are fired.
 169          *
 170          * @since               2.0
 171          *
 172          * @param[in]   listener                The listener to be removed
 173          * @see                 AddFrameEventListener()
 174          */
 175         void RemoveFrameEventListener(Tizen::Ui::Controls::IFrameEventListener& listener);
 176
 177 // Accessor
 178 public:
 179         /**
 180          * Gets the current %Form control of the %Frame control.
 181          *
 182          * @since               2.0
 183          *
 184          * @return              The current Form, @n
 185          *                              else @c null if there is no %Form
 186          * @see                 SetCurrentForm()
 187          */
 188         Form* GetCurrentForm(void) const;
 189
 190         /**
 191          * Sets the specified Form control as the current %Form of the %Frame control.
 192          *
 193          * @since               2.0
 194          *
 195          * @return              An error code
 196          * @param[in]   form                    The form to be set as the current form of the %Frame control
 197          * @exception   E_SUCCESS               The method is successful.
 198          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 199          *                                                              The specified @c form is not a child control of the %Frame control.
 200          * @exception   E_SYSTEM                A system error has occurred.
 201          * @remarks             If a form is set as the current form, it becomes the topmost form amongst its siblings. @n
 202          *                      SetCurrentForm() does not call Invalidate() internally, so if the current form needs to be drawn
 203          *                              immediately, Invalidate() should be called after SetCurrentForm().
 204          *                              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.
 205          */
 206         result SetCurrentForm(const Form& form);
 207
 208         /**
 209          * Gets the background color of the %Frame control.
 210          *
 211          * @since       2.0
 212          *
 213          * @return  The background color of the %Frame control
 214          */
 215         Tizen::Graphics::Color GetBackgroundColor(void) const;
 216
 217         /**
 218          * Sets the background color of the %Frame control.
 219          *
 220          * @since               2.0
 221          *
 222          * @param[in]   color   The background color
 223          */
 224         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 225
 226         /**
 227          * Sets the orientation mode of a frame.
 228          *
 229          * @since               2.0
 230          *
 231          * @param[in]   orientation             The orientation mode of the %Frame control
 232          * @remarks         To see the change in the orientation mode, the corresponding frame must be the topmost frame in the z-order hierarchy.
 233          *                              hierarchy.
 234          */
 235         void SetOrientation(Tizen::Ui::Orientation orientation);
 236
 237         /**
 238          * Gets the orientation mode of the frame.
 239          *
 240          * @since       2.0
 241          *
 242          * @return  The orientation mode of the frame
 243          */
 244         Tizen::Ui::Orientation GetOrientation(void) const;
 245
 246         /**
 247          * Gets the current orientation status of the frame.
 248          *
 249          * @since       2.0
 250          *
 251          * @return      The orientation status
 252          * @remarks     The method returns ORIENTATION_STATUS_NONE if the %Frame control is not drawn.
 253          *          Once it is drawn, the orientation of the %Frame control is set to portrait and the method
 254          *          returns ORIENTATION_STATUS_PORTRAIT if the application has not specified its orientation.
 255          */
 256         Tizen::Ui::OrientationStatus GetOrientationStatus(void) const;
 257
 258         /**
 259          * Gets the FrameAnimator of %Frame.
 260          *
 261          * @since               2.0
 262          *
 263          * @return              %FrameAnimator, @n
 264          *                              else @c null if this instance is not constructed as yet
 265          */
 266         Tizen::Ui::Animations::FrameAnimator* GetFrameAnimator(void) const;
 267
 268         /**
 269          * Sets the mode to show the %Frame control.
 270          *
 271          * @since 2.0
 272          *
 273          * @return      An error code
 274          * @param[in] mode      The mode to show the %Frame control
 275          * @exception   E_SUCCESS       The method is successful.
 276          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 277          * @remarks     The default mode is #FRAME_SHOW_MODE_FULL_SCREEN.
 278          */
 279         result SetShowMode(FrameShowMode mode);
 280
 281         /**
 282          * Gets the mode to show the %Frame control.
 283          *
 284          * @since 2.0
 285          *
 286          * @return      The mode to show the %Frame control
 287          * @remarks     The default mode is #FRAME_SHOW_MODE_FULL_SCREEN.
 288          */
 289         FrameShowMode GetShowMode(void) const;
 290
 291 protected:
 292         friend class _FrameImpl;
 293
 294         //
 295         //This method is for internal use only. Using this method can cause behavioral, security-related,
 296         //and consistency-related issues in the application.
 297         //
 298         // This method is reserved and may change its name at any time without
 299         // prior notice.
 300         //
 301         // @since 2.0
 302         //
 303         virtual void Frame_Reserved1(void) { }
 304
 305         //
 306         //This method is for internal use only. Using this method can cause behavioral, security-related,
 307         //and consistency-related issues in the application.
 308         //
 309         // This method is reserved and may change its name at any time without
 310         // prior notice.
 311         //
 312         // @since 2.0
 313         //
 314         virtual void Frame_Reserved2(void) { }
 315
 316         //
 317         //This method is for internal use only. Using this method can cause behavioral, security-related,
 318         //and consistency-related issues in the application.
 319         //
 320         // This method is reserved and may change its name at any time without
 321         // prior notice.
 322         //
 323         // @since 2.0
 324         //
 325         virtual void Frame_Reserved3(void) { }
 326
 327         //
 328         //This method is for internal use only. Using this method can cause behavioral, security-related,
 329         //and consistency-related issues in the application.
 330         //
 331         // This method is reserved and may change its name at any time without
 332         // prior notice.
 333         //
 334         // @since 2.0
 335         //
 336         virtual void Frame_Reserved4(void) { }
 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_Reserved5(void) { }
 348
 349 private:
 350         Frame(const Frame&);
 351         Frame& operator =(const Frame&);
 352 }; // Frame
 353
 354 }}} // Tizen::Ui::Controls
 355
 356 #endif // _FUI_CTRL_FRAME_H_