inc/FUiCtrlPanel.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                FUiCtrlPanel.h
  20  * @brief               This is the header file for the %Panel class.
  21  *
  22  * This header file contains the declarations of the %Panel class.
  23  */
  24
  25 #ifndef _FUI_CTRL_PANEL_H_
  26 #define _FUI_CTRL_PANEL_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseString.h>
  30 #include <FUiContainer.h>
  31 #include <FUiCtrlControlsTypes.h>
  32
  33 namespace Tizen {namespace Base
  34 {
  35 class String;
  36 }} //Tizen::Base
  37
  38 namespace Tizen { namespace Ui
  39 {
  40 class DataBindingContext;
  41 }} //Tizen::Ui
  42
  43 namespace Tizen { namespace Ui { namespace Controls
  44 {
  45
  46 /**
  47  * @class       Panel
  48  * @brief       This class provides a %Panel, that is the simplest container.
  49  *
  50  * @since       2.0
  51  *
  52  * The %Panel class displays a space where other UI elements can be placed. It is a concrete implementation of the Container class.
  53  *
  54  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_panels.htm">Panels</a>.
  55  *
  56  * The following example demonstrates how to use the %Panel class.
  57  *
  58  * @code
  59 // Sample code for PanelSample.h
  60 #include <FUi.h>
  61
  62 class PanelSample
  63         : public Tizen::Ui::Controls::Form
  64 {
  65 public:
  66         PanelSample(void)
  67         : __pPanel(null){}
  68
  69         bool Initialize(void);
  70         virtual result OnInitializing(void);
  71
  72 private:
  73         Tizen::Ui::Controls::Panel* __pPanel;
  74 };
  75  *      @endcode
  76  *
  77  *      @code
  78 // Sample code for PanelSample.cpp
  79 #include <FGraphics.h>
  80
  81 #include "PanelSample.h"
  82
  83 using namespace Tizen::Graphics;
  84 using namespace Tizen::Ui::Controls;
  85
  86 bool
  87 PanelSample::Initialize(void)
  88 {
  89         Construct(FORM_STYLE_NORMAL);
  90         return true;
  91 }
  92
  93 result
  94 PanelSample::OnInitializing(void)
  95 {
  96         result r = E_SUCCESS;
  97
  98         // Creates an instance of Panel
  99         __pPanel = new Panel();
 100         __pPanel->Construct(Rectangle(100, 200, 300, 300));
 101         __pPanel->SetBackgroundColor(Color(0x50, 0xFF, 0x38));
 102
 103         //Adds the panel to the form
 104         AddControl(__pPanel);
 105
 106         return r;
 107 }
 108  * @endcode
 109  */
 110 class _OSP_EXPORT_ Panel
 111         : public Tizen::Ui::Container
 112 {
 113 // Lifecycle
 114 public:
 115         /**
 116          * The object is not fully constructed after this constructor is called. @n
 117          *  For full construction, the %Construct() method must be called right after calling this constructor.
 118          *
 119          * @since       2.0
 120          *
 121          */
 122         Panel(void);
 123
 124         /**
 125          * This destructor overrides Tizen::Base::Object::~Object().
 126          *
 127          * @since       2.0
 128          *
 129          */
 130         virtual ~Panel(void);
 131
 132         /**
 133          * Initializes this instance of %Panel with the specified parameters.
 134          *
 135          * @since               2.0
 136          *
 137          * @return              An error code
 138          * @param[in]   rect                    The location and size of the %Panel control as an instance of Rectangle
 139          * @param[in]   groupStyle              The group style of the %Panel control
 140          * @exception   E_SUCCESS               The method is successful.
 141          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 142          * @exception   E_SYSTEM                A system error has occurred.
 143          * @remarks     The specified group style determines the border look of the %Panel control.
 144          * @see         Tizen::Ui::Container
 145          */
 146         result Construct(const Tizen::Graphics::Rectangle& rect, GroupStyle groupStyle = GROUP_STYLE_NONE);
 147
 148         /**
 149          * Initializes this instance of %Panel with the specified parameters.
 150          *
 151          * @since               2.1
 152          *
 153          * @return              An error code
 154          * @param[in]   rect                    The location and size of the %Panel control as an instance of FloatRectangle
 155          * @param[in]   groupStyle              The group style of the %Panel control
 156          * @exception   E_SUCCESS               The method is successful.
 157          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 158          * @exception   E_SYSTEM                A system error has occurred.
 159          * @remarks     The specified group style determines the border look of the %Panel control.
 160          * @see         Tizen::Ui::Container
 161          */
 162         result Construct(const Tizen::Graphics::FloatRectangle& rect, GroupStyle groupStyle = GROUP_STYLE_NONE);
 163
 164         /**
 165          * Initializes this instance of %Panel and child controls with the specified resource ID @n
 166          *
 167          * This method first attempts to find the resource file in the folder that corresponds to the current screen resolution. @n
 168          * If it fails to find the resource file, it searches in other folders in the following order when CoordinateSystem is Logical in the application manifest file @n
 169          * the density folder that corresponds to the current screen size category  "res/screen-size-normal/" folder.
 170          *
 171          * @since 2.0
 172          *
 173          * @return           An error code
 174          * @param[in]  resourceId              The resource ID describing the %Panel control
 175          * @exception  E_SUCCESS               The method is successful.
 176          * @exception  E_FILE_NOT_FOUND        The specified file cannot be found.
 177          * @exception  E_INVALID_FORMAT        The specified XML format is invalid.
 178          * @exception  E_OPERATION_FAILED      The operation has failed.
 179          * @remarks     If SetBounds(), SetSize(), SetPosition() methods are called before the control is added to the parent via AddControl(), then the new value is applied
 180          *                      to both orientations because the current orientation is not known. After AddControl() is called, then the values are applied only to the current orientation.
 181          */
 182         result Construct(const Tizen::Base::String& resourceId);
 183
 184         /**
 185          * Initializes this instance of %Panel with the specified parameters.
 186          *
 187          * @since               2.0
 188          *
 189          * @return              An error code
 190          * @param[in]   layout                          The layout for both the portrait and landscape modes
 191          * @param[in]   rect                            The location and size of the %Panel control as an instance of Rectangle
 192          * @param[in]   groupStyle                      The table view style of the %Panel control
 193          * @exception   E_SUCCESS                       The method is successful.
 194          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 195          *                                                                      The specified layout is already bound to another container.
 196          * @exception   E_SYSTEM                        A system error has occurred.
 197          * @remarks     The specified group style determines the border look of the %Panel control.
 198          * @see         Tizen::Ui::Container, Tizen::Ui::GroupStyle
 199          */
 200         result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::Rectangle& rect, GroupStyle groupStyle = GROUP_STYLE_NONE);
 201
 202         /**
 203          * Initializes this instance of %Panel with the specified parameters.
 204          *
 205          * @since               2.1
 206          *
 207          * @return              An error code
 208          * @param[in]   layout                          The layout for both the portrait and landscape modes
 209          * @param[in]   rect                            The location and size of the %Panel control as an instance of FloatRectangle
 210          * @param[in]   groupStyle                      The table view style of the %Panel control
 211          * @exception   E_SUCCESS                       The method is successful.
 212          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 213          *                                                                      The specified layout is already bound to another container.
 214          * @exception   E_SYSTEM                        A system error has occurred.
 215          * @remarks     The specified group style determines the border look of the %Panel control.
 216          * @see         Tizen::Ui::Container, Tizen::Ui::GroupStyle
 217          */
 218         result Construct(const Tizen::Ui::Layout& layout, const Tizen::Graphics::FloatRectangle& rect, GroupStyle groupStyle = GROUP_STYLE_NONE);
 219
 220         /**
 221          * Initializes this instance of %Panel with the specified layouts, rectangular region, and group style.
 222          *
 223          * @since               2.0
 224          *
 225          * @return              An error code
 226          * @param[in]   portraitLayout          The layout for the portrait mode
 227          * @param[in]   landscapeLayout         The layout for the landscape mode
 228          * @param[in]   rect                            The location and size of the %Panel control as an instance of Rectangle
 229          * @param[in]   groupStyle                      The table view style of the %Panel control
 230          * @exception   E_SUCCESS                       The method is successful.
 231          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 232          *                                                                      The specified layout is already bound to another container.
 233          * @exception   E_SYSTEM                        A system error has occurred.
 234          * @remarks     The specified group style determines the border look of the %Panel control.
 235          * @see         Tizen::Ui::Container, Tizen::Ui::GroupStyle
 236          */
 237         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::Rectangle& rect, GroupStyle groupStyle = GROUP_STYLE_NONE);
 238
 239         /**
 240          * Initializes this instance of %Panel with the specified layouts, rectangular region, and group style.
 241          *
 242          * @since               2.1
 243          *
 244          * @return              An error code
 245          * @param[in]   portraitLayout          The layout for the portrait mode
 246          * @param[in]   landscapeLayout         The layout for the landscape mode
 247          * @param[in]   rect                            The location and size of the %Panel control as an instance of FloatRectangle
 248          * @param[in]   groupStyle                      The table view style of the %Panel control
 249          * @exception   E_SUCCESS                       The method is successful.
 250          * @exception   E_INVALID_ARG           A specified input parameter is invalid. @n
 251          *                                                                      The specified layout is already bound to another container.
 252          * @exception   E_SYSTEM                        A system error has occurred.
 253          * @remarks     The specified group style determines the border look of the %Panel control.
 254          * @see         Tizen::Ui::Container, Tizen::Ui::GroupStyle
 255          */
 256         result Construct(const Tizen::Ui::Layout& portraitLayout, const Tizen::Ui::Layout& landscapeLayout, const Tizen::Graphics::FloatRectangle& rect, GroupStyle groupStyle = GROUP_STYLE_NONE);
 257
 258         /**
 259          * Gets the background color of the %Panel control.
 260          *
 261          * @since               2.0
 262          *
 263          * @return              The background color
 264          */
 265         Tizen::Graphics::Color GetBackgroundColor(void) const;
 266
 267         /**
 268          * Sets the background color of this control.
 269          *
 270          * @since               2.0
 271          *
 272          * @param[in]   color   The background color
 273          */
 274         void SetBackgroundColor(const Tizen::Graphics::Color& color);
 275
 276         /**
 277          * @if OSPDEPREC
 278          * Enables the %Panel control to be composited to the screen buffer.
 279          *
 280          * @brief <i> [Deprecated]  </i>
 281          * @deprecated  This method is deprecated because changing composition mode is not allowed any more.
 282          * @since               2.0
 283          *
 284          * @return              An error code
 285          * @param[in]   composite               Set to @c true to make the %Panel control composited to the screen buffer, @n
 286          *                                                              else @c false
 287          * @exception   E_SUCCESS               The method is successful.
 288          * @exception   E_SYSTEM        A system error has occurred.
 289          * @remarks     In case a %Panel is transparent and nothing is drawn on the canvas of the %Panel control, the graphic performance can be improved if the
 290          *                              compositing of the %Panel control to the screen buffer is disabled. @n
 291          *                              By default, compositing is enabled. For example, if a Form control has a %Panel that has a List, by disabling the compositing of the
 292          *                              %Panel, the scroll performance of the %List will improve.
 293          * @endif
 294          */
 295         result SetCompositeEnabled(bool composite);
 296
 297         /**
 298          * @if OSPDEPREC
 299          * Checks whether the %Panel control is composite to the screen buffer.
 300          *
 301          * @brief <i> [Deprecated]  </i>
 302          * @deprecated  This method is deprecated because changing composition mode is not allowed any more.
 303          * @since       2.0
 304          *
 305          * @return      @c true if the %Panel control is composite to the screen buffer, @n
 306          *                      else @c false
 307          * @endif
 308          */
 309         bool IsCompositeEnabled(void) const;
 310
 311         /**
 312          * Gets the data binding context.
 313          *
 314          * @since 2.0
 315          *
 316          * @return       The data binding context
 317          * @exception    E_SUCCESS        The method is successful.
 318          * @exception    E_SYSTEM         A system error has occurred.
 319          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 320          */
 321         DataBindingContext* GetDataBindingContextN(void) const;
 322
 323 protected:
 324
 325         friend class _PanelImpl;
 326
 327         // Reserved virtual methods for later extension
 328
 329         // The following methods are reserved and may change its name at any time without prior notice.
 330         virtual void Panel_Reserved1(void) {}
 331
 332         virtual void Panel_Reserved2(void) {}
 333
 334         virtual void Panel_Reserved3(void) {}
 335
 336 private:
 337         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 338         Panel(const Panel& rhs);
 339
 340         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 341         Panel& operator =(const Panel& rhs);
 342
 343 }; // Panel
 344
 345 }}} //Tizen::Ui::Controls
 346
 347 #endif // _FUI_CTRL_PANEL_H_
 348