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 Tizen::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 Tizen::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         Tizen::Base::Integer __bindIntegerToButtonText;
  79         Tizen::Ui::Controls::Button* __pUnbindButton;
  80         Tizen::Ui::Controls::Button* __pUpdateBindingButton;
  81         Tizen::Ui::Controls::Button* __pTargetButton;
  82         Tizen::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_