inc/FUiDataBindingContext.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        FUiDataBindingContext.h
  20  * @brief       This is the header file for the %DataBindingContext class.
  21  *
  22  * This header file contains the declarations of the %DataBindingContext class.
  23  */
  24
  25 #ifndef _FUI_DATA_BINDING_CONTEXT_H_
  26 #define _FUI_DATA_BINDING_CONTEXT_H_
  27
  28 #include <FBaseTypes.h>
  29 #include <FBaseObject.h>
  30 #include <FUiDataBindingTypes.h>
  31 #include <FUiIDataBindingListener.h>
  32 #include <FUiIDataBindingDataValidator.h>
  33 #include <FUiIDataBindingDataTransformer.h>
  34
  35 namespace Tizen { namespace Base
  36 {
  37 class String;
  38 }}
  39
  40 namespace Tizen { namespace Ui
  41 {
  42
  43 class Control;
  44 class _DataBindingContextImpl;
  45
  46 /**
  47  * @class          DataBindingContext
  48  * @brief          This class represents a data binding context and the application's data source.
  49  *
  50  * @since 2.0
  51  *
  52  * The %DataBindingContext class represents the data binding context.
  53  *
  54  * The following example demonstrates how to use the %DataBindingContext class.
  55 .*
  56  * @code
  57 // Sample code for DataBindingSample.h
  58 #include <FBase.h>
  59 #include <FUi.h>
  60
  61 class DataBindingSample
  62         : public Tizen::Ui::Controls::Form
  63         , public Osp::Ui::IActionEventListener
  64 {
  65 public:
  66         DataBindingSample(void);
  67         virtual ~DataBindingSample(void);
  68
  69         virtual bool Initialize(void);
  70         virtual result OnInitializing(void);
  71         virtual void OnActionPerformed(const Osp::Ui::Control& source, int actionId);
  72
  73 private :
  74         static const int ID_BUTTON_UNBIND = 402;
  75         static const int ID_BUTTON_UPDATE_BINDING = 403;
  76         static const int ID_BUTTON_BIND = 404;
  77
  78         Osp::Base::Integer __bindIntegerToButtonText;
  79         Osp::Ui::Controls::Button* __pUnbindButton;
  80         Osp::Ui::Controls::Button* __pUpdateBindingButton;
  81         Osp::Ui::Controls::Button* __pTargetButton;
  82         Osp::Ui::Controls::Button* __pBindButton;
  83 };
  84
  85  *      @endcode
  86  *
  87  *      @code
  88
  89 // Sample code for DataBindingSample.cpp
  90 #include "DataBindingSample.h"
  91
  92 using namespace Tizen::App;
  93 using namespace Tizen::Graphics;
  94 using namespace Tizen::Ui;
  95 using namespace Tizen::Ui::Controls;
  96
  97 bool
  98 DataBindingSample::Initialize(void)
  99 {
 100         Construct(FORM_STYLE_NORMAL| FORM_STYLE_INDICATOR| FORM_STYLE_HEADER| FORM_STYLE_FOOTER);
 101         SetFooter();
 102         return true;
 103 }
 104
 105 result
 106 DataBindingSample::OnInitializing(void)
 107 {
 108         result r = E_SUCCESS;
 109
 110         Header* pHeader = GetHeader();
 111         pHeader->SetTitleText(L"DataBinding");
 112
 113         Rectangle rect;
 114         rect = GetClientAreaBounds();
 115
 116         __pUpdateBindingButton = new (std::nothrow) Button();
 117         __pUpdateBindingButton->Construct(Rectangle(10, rect.height / 6, rect.width - 20, rect.height / 6), L"BindingTarget");
 118         __pUpdateBindingButton->SetName("Target");
 119         AddControl(*__pUpdateBindingButton);
 120
 121         __pTargetButton = new (std::nothrow) Button();
 122         __pTargetButton->Construct(Rectangle(10, (rect.height / 3) + 10 , (rect.width - 20), rect.height / 6), L"Update Binding");
 123         __pTargetButton->SetActionId(ID_BUTTON_UPDATE_BINDING);
 124         __pTargetButton->AddActionEventListener(*this);
 125         AddControl(*__pTargetButton);
 126
 127         __pUnbindButton = new (std::nothrow) Button();
 128         __pUnbindButton->Construct(Rectangle(10, (rect.height * 2 / 3), (rect.width / 2) - 10, rect.height / 6), L"Unbind");
 129         __pUnbindButton->SetActionId(ID_BUTTON_UNBIND);
 130         __pUnbindButton->AddActionEventListener(*this);
 131         AddControl(*__pUnbindButton);
 132
 133         __pBindButton = new (std::nothrow) Button();
 134         __pBindButton->Construct(Rectangle((rect.width / 2) + 10 , (rect.height * 2 / 3), (rect.width / 2) - 20 , rect.height / 6), L"Bind");
 135         __pBindButton->SetActionId(ID_BUTTON_BIND);
 136         __pBindButton->AddActionEventListener(*this);
 137         AddControl(*__pBindButton);
 138
 139         DataBindingContext* pContext = GetDataBindingContextN();
 140         r = pContext->Bind(L"bindingcount", L"Target", L"text", __bindIntegerToButtonText, DATA_BINDING_DATA_TYPE_INTEGER, DATA_BINDING_FLOW_ONE_WAY, DATA_BINDING_TRIGGER_EXPLICIT, null, null, null);
 141         delete pContext;
 142
 143         return r;
 144 }
 145
 146 void
 147 DataBindingSample::OnActionPerformed(const Control& source, int actionId)
 148 {
 149         DataBindingContext* pContext = GetDataBindingContextN();
 150         result r = E_SUCCESS;
 151         switch (actionId)
 152         {
 153         case ID_BUTTON_UNBIND:
 154                 {
 155                         pContext->Unbind(L"bindingcount");
 156                         break;
 157                 }
 158         case ID_BUTTON_BIND:
 159                 {
 160                         pContext->Bind(L"bindingcount", L"Target", L"text", __bindIntegerToButtonText, DATA_BINDING_DATA_TYPE_INTEGER, DATA_BINDING_FLOW_ONE_WAY, DATA_BINDING_TRIGGER_EXPLICIT, null, null, null);
 161                         break;
 162                         }
 163         case ID_BUTTON_UPDATE_BINDING:
 164                 {
 165                         r = pContext->UpdateBinding(L"bindingcount", DATA_BINDING_DESTINATION_TYPE_TARGET);
 166                         if (r  == E_SUCCESS)
 167                         {
 168                                 __bindIntegerToButtonText = __bindIntegerToButtonText.ToInt() + 1;
 169                         }
 170                         break;
 171                 }
 172         default:
 173                 break;
 174         }
 175         delete pContext;
 176         Invalidate(true);
 177 }
 178  * @endcode
 179  *
 180  */
 181 class _OSP_EXPORT_ DataBindingContext
 182         : public Tizen::Base::Object
 183 {
 184 public:
 185         /**
 186          * This is the destructor for this class.
 187          *
 188          * @since 2.0
 189          */
 190         virtual ~DataBindingContext(void);
 191
 192 public:
 193         /**
 194          * Gets the owner of this data binding context.
 195          *
 196          * @since 2.0
 197          *
 198          * @return        The context owner
 199          */
 200         Control* GetContextOwner(void) const;
 201
 202         /**
 203          * Binds the specified control's property and data source.
 204          *
 205          * @since 2.0
 206          *
 207          * @return        An error code
 208          * @param[in]    bindingId              The binding ID
 209          * @param[in]    controlName            The name of target property owner
 210          * @param[in]    propertyName           The target property name
 211          * @param[in]    dataSource             The data binding source
 212          * @param[in]    sourceType             The data type of the @c dataSource
 213          * @param[in]    flow                           The data flow type
 214          * @param[in]    trigger                        The data binding trigger type
 215          * @param[in]    pListener              The data binding listener
 216          * @param[in]    pValidator             The data validator
 217          * @param[in]    pTransformer           The data transformer
 218          * @exception    E_SUCCESS                      The method is successful.
 219          * @exception    E_SYSTEM                       A system error has occurred.
 220          * @exception    E_INVALID_ARG  1. sourceType is not of a supported type.
 221          *                                2. flow is not of a supported type.
 222          *                                3. trigger is not of a supported type.
 223          * @exception    E_OBJ_NOT_FOUND        1. The control named controlName does not exist.
 224          *                                         2. The parameter "propertyName" is not found in control properties.
 225          * @exception    E_UNSUPPORTED_FORMAT          The given transformer does not supported changing source type to target type.
 226          * @exception    E_UNSUPPORTED_OPERATION      In this system, binding with the given trigger and flow is not supported.
 227          * @remarks      The propertyName parameter is defined in "UI Builder Guide". @n
 228          *                     There is no duplication check for each binding ID. @n
 229          *                     Please use a unique binding ID for each binding setting.
 230          */
 231         result Bind(const Tizen::Base::String& bindingId, const Tizen::Base::String& controlName, const Tizen::Base::String& propertyName, Tizen::Base::Object& dataSource, DataBindingDataType sourceType, DataBindingFlow flow, DataBindingTrigger trigger, const IDataBindingListener* pListener, const IDataBindingDataValidator* pValidator, const IDataBindingDataTransformer* pTransformer = null);
 232
 233         /**
 234          * Sets the binding listener for the specified data binding.
 235          *
 236          * @since 2.0
 237          *
 238          * @return        An error code
 239          * @param[in]    bindingId              The binding ID
 240          * @param[in]    pListener              The data binding listener
 241          * @exception    E_SUCCESS              The method is successful.
 242          * @exception    E_SYSTEM               A system error has occurred.
 243          * @exception    E_OBJ_NOT_FOUND     The given binding ID is not registered.
 244          * @exception    E_INVALID_ARG  The given listener is not valid.
 245          * @remarks       If you give pListener parameter as 'null', the existing dataBindingEventListener will be removed.
 246          */
 247         result SetDataBindingEventListener(const Tizen::Base::String& bindingId, IDataBindingListener* pListener);
 248
 249         /**
 250          * Unbinds all bindings that exist in this context.
 251          *
 252          * @since 2.0
 253          *
 254          * @return        An error code
 255          * @exception    E_SUCCESS        The method is successful.
 256          * @exception    E_SYSTEM         A system error has occurred.
 257          */
 258         result UnbindAll(void);
 259
 260         /**
 261          * Unbinds a binding that exists in this context.
 262          *
 263          * @since 2.0
 264          *
 265          * @return        An error code
 266          * @param[in]    bindingId        The binding ID
 267          * @exception    E_SUCCESS        The method is successful.
 268          * @exception    E_SYSTEM         A system error has occurred.
 269          * @exception    E_OBJ_NOT_FOUND        The given binding ID is not registered.
 270          */
 271         result Unbind(const Tizen::Base::String& bindingId);
 272
 273         /**
 274          * Updates all 'explicit' data bindings.
 275          *
 276          * @since 2.0
 277          *
 278          * @return        An error code
 279          * @param[in]    destType               The destination type
 280          * @exception    E_SUCCESS              The method is successful.
 281          * @exception    E_SYSTEM               A system error has occurred.
 282          * @exception    E_INVALID_ARG          The specified @c destType is not of a supported type.
 283          * @remarks       If you have set a data binding listener, @n
 284          *                              this function is returned after that listener is called.
 285          * @see    IDataBindingListener
 286          */
 287         result UpdateAllBindings(DataBindingDestinationType destType);
 288
 289         /**
 290          * Updates the specified data binding.
 291          *
 292          * @since 2.0
 293          *
 294          * @param[in]    bindingId              The binding ID
 295          * @param[in]    destType               The destination type
 296          * @exception    E_SUCCESS              The method is successful.
 297          * @exception    E_SYSTEM               A system error has occurred.
 298          * @exception    E_OBJ_NOT_FOUND        The given binding ID is not registered.
 299          * @exception    E_INVALID_OPERATION    The given binding's trigger is not 'explicit' type.
 300          * @exception    E_INVALID_ARG  The specified @c destType is not supported in binding ID.
 301          * @remarks       If you have set a data binding listener, @n
 302          *                              this function is returned after that listener is called.
 303          * @see    IDataBindingListener
 304          */
 305         result UpdateBinding(const Tizen::Base::String& bindingId, DataBindingDestinationType destType);
 306
 307 private:
 308         //
 309         // This default constructor is intentionally declared as private so that only the platform can create an instance.
 310         //
 311         DataBindingContext(void);
 312
 313         //
 314         // This destructor is intentionally declared as private so that only the platform can delete an instance.
 315         //
 316         DataBindingContext(const Control& contextOwner);
 317
 318         //
 319         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 320         //
 321         DataBindingContext(const DataBindingContext& rhs);
 322
 323         //
 324         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 325         //
 326         DataBindingContext& operator =(const DataBindingContext& rhs);
 327
 328 private:
 329         _DataBindingContextImpl* __pDataBindingContextImpl;
 330
 331         friend class _DataBindingContextImpl;
 332
 333 }; // DataBindingContext
 334
 335 } } // Tizen::Ui
 336 #endif // _FUI_DATA_BINDING_CONTEXT_H_