inc/FUiWindow.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        FUiWindow.h
  20  * @brief       This is the header file for the %Window class.
  21  *
  22  * This header file contains the declarations of the %Window class.
  23  */
  24
  25 #ifndef _FUI_WINDOW_H_
  26 #define _FUI_WINDOW_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FUiContainer.h>
  30 #include <FUiIWindowEventListener.h>
  31
  32 namespace Tizen { namespace Ui { namespace Animations {
  33 class DisplayContext;
  34 }}}
  35
  36 namespace Tizen { namespace Ui
  37 {
  38
  39 class _WindowImpl;
  40
  41 /**
  42  * @enum WindowState
  43  *
  44  * Defines the state of %Window.
  45  *
  46  * @since       2.0
  47  */
  48 enum WindowState
  49 {
  50         WINDOW_STATE_INITIALIZED = 0x0000,      /**< The initial state of the window */
  51         WINDOW_STATE_ACTIVATED = 0x0001,        /**< The state indicates that the window is the topmost window */
  52         WINDOW_STATE_DEACTIVATED = 0x0002,      /**< The state indicates that the window is not the topmost window */
  53 };
  54
  55 /**
  56  * @enum WindowZOrderGroup
  57  *
  58  * Defines the Z order group of %Window.
  59  *
  60  * @since 2.0
  61  */
  62 enum WindowZOrderGroup
  63 {
  64         WINDOW_Z_ORDER_GROUP_HIGHEST,        /**< The highest group for windows such as the call screen */
  65         WINDOW_Z_ORDER_GROUP_HIGH,           /**< The high group for windows such as the lock screen */
  66         WINDOW_Z_ORDER_GROUP_NORMAL,         /**< The default group of apps */
  67 };
  68
  69 /**
  70  * @class       Window
  71  * @brief       This class provides abstract top-level 'window' objects.
  72  *
  73  * @since       2.0
  74  *
  75  * The %Window class is an abstract base class.
  76  * The %Window is a top-level window such as Controls::Frame, Controls::MessageBox, and Controls::Popup.
  77  * The descendants of a %Window can exist outside of their applications's bounds.
  78  *
  79  */
  80 class _OSP_EXPORT_ Window
  81         : public Container
  82 {
  83
  84 public:
  85         /**
  86          * This destructor overrides Tizen::Base::Object::~Object().
  87          *
  88          * @since       2.0
  89          */
  90         virtual ~Window(void) = 0;
  91
  92 public:
  93         /**
  94          * Adds the listener instance. @n
  95          * The added listener can listen to events on when they are fired.
  96          *
  97          * @since                       2.0
  98          *
  99          * @param[in]   listener    The event listener to add
 100          * @see                         RemoveWindowEventListener()
 101          */
 102         void AddWindowEventListener(Tizen::Ui::IWindowEventListener& listener);
 103
 104         /**
 105          * Removes a listener instance. @n
 106          * The removed listener cannot listen to events when they are fired.
 107          *
 108          * @since                       2.0
 109          *
 110          * @param[in]   listener    The listener to remove
 111          * @see                         AddWindowEventListener()
 112          */
 113         void RemoveWindowEventListener(Tizen::Ui::IWindowEventListener& listener);
 114
 115         /**
 116          * Shows the %Window.
 117          *
 118          * @since                       2.0
 119          *
 120          * @final     Although this method is virtual, it should not be overridden.
 121      * If overridden, it may not work as expected.
 122          *
 123          * @return              An error code
 124          * @exception   E_SUCCESS                       The method is successful.
 125          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, or
 126          *                                                              this control is not 'displayable'.
 127          * @exception   E_SYSTEM                        A system error has occurred.
 128          */
 129         virtual result Show(void);
 130
 131         /**
 132          * Sets the owner of the window.
 133          * The visibility of a window has dependency on the visibility of the owner window.
 134          *
 135          * @since 2.0
 136          *
 137          * @param[in]    pControl      The control
 138          * @remarks       The ownership of @c pControl is not transferred to this instance. It is the developer's responsibility to deallocate @c pControl even after calling this method.
 139          */
 140         void SetOwner(Tizen::Ui::Control* pControl);
 141
 142         /**
 143          * Gets the owner of the window.
 144          *
 145          * @since 2.1
 146          *
 147          * @return    The owner of the window
 148          * @see    SetOwner()
 149          */
 150         Tizen::Ui::Control* GetOwner(void) const;
 151
 152         /**
 153          * Sets the Z order group of %Window.
 154          *
 155          * @since 2.0
 156          *
 157          * @privlevel      platform
 158          * @privilege      %http://tizen.org/privilege/uimanager
 159          *
 160          * @return         An error code
 161          * @param[in]      windowZOrderGroup    The Z order group of %Window
 162          * @exception      E_SUCCESS            The method is successful.
 163          * @exception      E_PRIVILEGE_DENIED   The application does not have the privilege to call this method.
 164          * @remarks        If this method is not explicitly called, the Z order group of %Window is set to #WINDOW_Z_ORDER_GROUP_NORMAL.
 165          */
 166         result SetZOrderGroup(WindowZOrderGroup windowZOrderGroup);
 167
 168         /**
 169          * Gets the current state of the window.
 170          *
 171          * @since                       2.0
 172          *
 173          * @return              The current state of the window
 174          */
 175         WindowState GetWindowState(void) const;
 176
 177         /**
 178          * Gets the display context of the window.
 179          *
 180          * @since 2.0
 181          *
 182          * @return              A pointer to the DisplayContext instance
 183          */
 184         Tizen::Ui::Animations::DisplayContext* GetDisplayContext(void) const;
 185
 186 protected:
 187         /**
 188          * Initializes this instance of %Window with the specified parameters.
 189          *
 190          * @since 2.0
 191          *
 192          * @return      An error code
 193          * @param[in]   rect                                      The rectangle bounds to set
 194          * @param[in]   resizable                                Set to @c true to make the window resizable, @n
 195          *                                  else @c false
 196          * @param[in]   movable                                          Set to @c true to make the window movable, @n
 197          *                                  else @c false
 198          * @exception   E_SUCCESS           The method is successful.
 199          * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 200          * @remarks     This method must be called from the derived classes's construct methods.
 201          * @remarks     If the @c resizable is @c false, IsResizable() returns @c false.
 202          * @see IsResizable()
 203          */
 204         result Construct(const Tizen::Graphics::Rectangle& rect, bool resizable = true, bool movable = true);
 205
 206         /**
 207          * Initializes this instance of %Window with the specified parameters.
 208          *
 209          * @since 2.1
 210          *
 211          * @return      An error code
 212          * @param[in]   rect                                      The rectangle bounds to set
 213          * @param[in]   resizable                                Set to @c true to make the window resizable, @n
 214          *                                  else @c false
 215          * @param[in]   movable                                          Set to @c true to make the window movable, @n
 216          *                                  else @c false
 217          * @exception   E_SUCCESS           The method is successful.
 218          * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 219          * @remarks     This method must be called from the derived classes's construct methods.
 220          * @remarks     If the @c resizable is @c false, IsResizable() returns @c false.
 221          * @see IsResizable()
 222          */
 223         result Construct(const Tizen::Graphics::FloatRectangle& rect, bool resizable = true, bool movable = true);
 224
 225         /**
 226          * Initializes this instance of %Window with the specified layout and rectangular region.
 227          *
 228          * @since 2.0
 229          *
 230          * @return                  An error code
 231          * @param[in]   layout                                   The layout for both the portrait and landscape mode
 232          * @param[in]   rect                                      The location and size of the %window
 233          * @param[in]   resizable                                Set to @c true to make the window resizable, @n
 234          *                                  else @c false
 235          * @param[in]   movable                                          Set to @c true to make the window movable, @n
 236          *                                  else @c false
 237          * @exception   E_SUCCESS                The method is successful.
 238          * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 239          * @remarks     This method must be called from the derived classes's construct methods.
 240          * @remarks     If the @c resizable is @c false, IsResizable() returns @c false.
 241          * @see IsResizable()
 242          * @see Tizen::Ui::Layout
 243          * @see Tizen::Ui::Container::GetLayoutN()
 244          */
 245          result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::Rectangle& rect, bool resizable = true, bool movable = true);
 246
 247         /**
 248          * Initializes this instance of %Window with a specified layout and rectangular region.
 249          *
 250          * @since 2.1
 251          *
 252          * @return                  An error code
 253          * @param[in]   layout                                   The layout for both the portrait and landscape mode
 254          * @param[in]   rect                                      The location and size of the window
 255          * @param[in]   resizable                                Set to @c true to make the window resizable, @n
 256          *                                  else @c false
 257          * @param[in]   movable                                          Set to @c true to make the window movable, @n
 258          *                                  else @c false
 259          * @exception   E_SUCCESS                The method is successful.
 260          * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 261          * @remarks
 262          *                      - This method must be called from the derived classes's construct methods.
 263          *                      - If the @c resizable is @c false, IsResizable() returns @c false.
 264          * @see IsResizable()
 265          * @see Tizen::Ui::Layout
 266          * @see Tizen::Ui::Container::GetLayoutN()
 267          */
 268          result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::FloatRectangle& rect, bool resizable = true, bool movable = true);
 269
 270         /**
 271          * Initializes this instance of %Window with the specified layouts and rectangular region.
 272          *
 273          * @since 2.0
 274          *
 275          * @return                  An error code
 276          * @param[in]   portraitLayout              The layout for the portrait mode
 277          * @param[in]   landscapeLayout           The layout for the landscape mode
 278          * @param[in]   rect                                      The location and size of the %Window
 279          * @param[in]   resizable                                Set to @c true to make the window resizable, @n
 280          *                                  else @c false
 281          * @param[in]   movable                                          Set to @c true to make the window movable, @n
 282          *                                  else @c false
 283          * @exception   E_SUCCESS                The method is successful.
 284          * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 285          * @remarks     If the @c resizable is @c false, IsResizable() returns @c false.
 286          * @see IsResizable()
 287          * @see Tizen::Ui::Layout
 288          * @see Tizen::Ui::Layout
 289          * @see Tizen::Ui::Container::GetLayoutN()
 290          * @see Tizen::Ui::Container::GetPortraitLayoutN()
 291          * @see Tizen::Ui::Container::GetLandscapeLayoutN()
 292          */
 293         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::Rectangle& rect, bool resizable = true, bool movable = true);
 294
 295         /**
 296          * Initializes this instance of %Window with the specified layouts and rectangular region.
 297          *
 298          * @since 2.1
 299          *
 300          * @return                  An error code
 301          * @param[in]   portraitLayout              The layout for the portrait mode
 302          * @param[in]   landscapeLayout           The layout for the landscape mode
 303          * @param[in]   rect                                      The location and size of the %Window
 304          * @param[in]   resizable                                Set to @c true to make the window resizable, @n
 305          *                                  else @c false
 306          * @param[in]   movable                                          Set to @c true to make the window movable, @n
 307          *                                  else @c false
 308          * @exception   E_SUCCESS                The method is successful.
 309          * @exception   E_INVALID_ARG            A specified input parameter is invalid.
 310          * @remarks     If the @c resizable is @c false, IsResizable() returns @c false.
 311          * @see IsResizable()
 312          * @see Tizen::Ui::Layout
 313          * @see Tizen::Ui::Layout
 314          * @see Tizen::Ui::Container::GetLayoutN()
 315          * @see Tizen::Ui::Container::GetPortraitLayoutN()
 316          * @see Tizen::Ui::Container::GetLandscapeLayoutN()
 317          */
 318         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::FloatRectangle& rect, bool resizable = true, bool movable = true);
 319
 320         /**
 321          * 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.
 322          *
 323          * @since       2.0
 324          */
 325         Window(void);
 326
 327 private:
 328         //
 329         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 330         //
 331         Window(const Window& rhs);
 332
 333         //
 334         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 335         //
 336         Window& operator =(const Window& rhs);
 337
 338 protected:
 339         friend class _WindowImpl;
 340
 341         //
 342         // This method is for internal use only. Using this method can cause behavioral,
 343         // security-related, and consistency-related issues in the application.
 344         //
 345         // This method is reserved and may change its name at any time without prior notice.
 346         //
 347         virtual void Window_Reserved1(void) {}
 348
 349         //
 350         // This method is for internal use only. Using this method can cause behavioral,
 351         // security-related, and consistency-related issues in the application.
 352         //
 353         // This method is reserved and may change its name at any time without prior notice.
 354         //
 355         virtual void Window_Reserved2(void) {}
 356
 357         //
 358         // This method is for internal use only. Using this method can cause behavioral,
 359         // security-related, and consistency-related issues in the application.
 360         //
 361         // This method is reserved and may change its name at any time without prior notice.
 362         //
 363         virtual void Window_Reserved3(void) {}
 364
 365         //
 366         // This method is for internal use only. Using this method can cause behavioral,
 367         // security-related, and consistency-related issues in the application.
 368         //
 369         // This method is reserved and may change its name at any time without prior notice.
 370         //
 371         virtual void Window_Reserved4(void) {}
 372
 373         //
 374         // This method is for internal use only. Using this method can cause behavioral,
 375         // security-related, and consistency-related issues in the application.
 376         //
 377         // This method is reserved and may change its name at any time without prior notice.
 378         //
 379         virtual void Window_Reserved5(void) {}
 380 }; // Window
 381
 382 }} // Tizen::Ui
 383
 384 #endif //_FUI_WINDOW_H_