inc/FUiDataBindingContext.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        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         virtual bool Initialize(void);
  67         virtual result OnInitializing(void);
  68         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
  69
  70 private :
  71         static const int ID_BUTTON_UNBIND = 402;
  72         static const int ID_BUTTON_UPDATE_BINDING = 403;
  73         static const int ID_BUTTON_BIND = 404;
  74
  75         Tizen::Base::Integer __bindIntegerToButtonText;
  76         Tizen::Ui::Controls::Button* __pUnbindButton;
  77         Tizen::Ui::Controls::Button* __pUpdateBindingButton;
  78         Tizen::Ui::Controls::Button* __pTargetButton;
  79         Tizen::Ui::Controls::Button* __pBindButton;
  80 };
  81
  82  *      @endcode
  83  *
  84  *      @code
  85
  86 // Sample code for DataBindingSample.cpp
  87 #include "DataBindingSample.h"
  88
  89 using namespace Tizen::App;
  90 using namespace Tizen::Graphics;
  91 using namespace Tizen::Ui;
  92 using namespace Tizen::Ui::Controls;
  93
  94 bool
  95 DataBindingSample::Initialize(void)
  96 {
  97         Construct(FORM_STYLE_NORMAL| FORM_STYLE_PORTRAIT_INDICATOR| FORM_STYLE_HEADER| FORM_STYLE_FOOTER);
  98         return true;
  99 }
 100
 101 result
 102 DataBindingSample::OnInitializing(void)
 103 {
 104         result r = E_SUCCESS;
 105
 106         Header* pHeader = GetHeader();
 107         pHeader->SetTitleText(L"DataBinding");
 108
 109         Rectangle rect;
 110         rect = GetClientAreaBounds();
 111
 112         __pUpdateBindingButton = new (std::nothrow) Button();
 113         __pUpdateBindingButton->Construct(Rectangle(10, rect.height / 6, rect.width - 20, rect.height / 6), L"BindingTarget");
 114         __pUpdateBindingButton->SetName("Target");
 115         AddControl(__pUpdateBindingButton);
 116
 117         __pTargetButton = new (std::nothrow) Button();
 118         __pTargetButton->Construct(Rectangle(10, (rect.height / 3) + 10 , (rect.width - 20), rect.height / 6), L"Update Binding");
 119         __pTargetButton->SetActionId(ID_BUTTON_UPDATE_BINDING);
 120         __pTargetButton->AddActionEventListener(*this);
 121         AddControl(__pTargetButton);
 122
 123         __pUnbindButton = new (std::nothrow) Button();
 124         __pUnbindButton->Construct(Rectangle(10, (rect.height * 2 / 3), (rect.width / 2) - 10, rect.height / 6), L"Unbind");
 125         __pUnbindButton->SetActionId(ID_BUTTON_UNBIND);
 126         __pUnbindButton->AddActionEventListener(*this);
 127         AddControl(__pUnbindButton);
 128
 129         __pBindButton = new (std::nothrow) Button();
 130         __pBindButton->Construct(Rectangle((rect.width / 2) + 10 , (rect.height * 2 / 3), (rect.width / 2) - 20 , rect.height / 6), L"Bind");
 131         __pBindButton->SetActionId(ID_BUTTON_BIND);
 132         __pBindButton->AddActionEventListener(*this);
 133         AddControl(__pBindButton);
 134
 135         DataBindingContext* pContext = GetDataBindingContextN();
 136         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);
 137         delete pContext;
 138
 139         return r;
 140 }
 141
 142 void
 143 DataBindingSample::OnActionPerformed(const Control& source, int actionId)
 144 {
 145         DataBindingContext* pContext = GetDataBindingContextN();
 146         result r = E_SUCCESS;
 147         switch (actionId)
 148         {
 149         case ID_BUTTON_UNBIND:
 150                 {
 151                         pContext->Unbind(L"bindingcount");
 152                         break;
 153                 }
 154         case ID_BUTTON_BIND:
 155                 {
 156                         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);
 157                         break;
 158                         }
 159         case ID_BUTTON_UPDATE_BINDING:
 160                 {
 161                         r = pContext->UpdateBinding(L"bindingcount", DATA_BINDING_DESTINATION_TYPE_TARGET);
 162                         if (r  == E_SUCCESS)
 163                         {
 164                                 __bindIntegerToButtonText = __bindIntegerToButtonText.ToInt() + 1;
 165                         }
 166                         break;
 167                 }
 168         default:
 169                 break;
 170         }
 171         delete pContext;
 172         Invalidate(true);
 173 }
 174  * @endcode
 175  *
 176  */
 177 class _OSP_EXPORT_ DataBindingContext
 178         : public Tizen::Base::Object
 179 {
 180 public:
 181         /**
 182         * This is the destructor for this class.
 183         *
 184         * @since 2.0
 185         */
 186         virtual ~DataBindingContext(void);
 187
 188 public:
 189         /**
 190         * Gets the owner of this data binding context.
 191         *
 192         * @since 2.0
 193         *
 194         * @return        The context owner
 195         */
 196         Control* GetContextOwner(void) const;
 197
 198         /**
 199         * Binds the specified control's property and data source.
 200         *
 201         * @since 2.0
 202         *
 203         * @return        An error code
 204         * @param[in]    bindingId               The binding ID
 205         * @param[in]    controlName             The name of target property owner
 206         * @param[in]    propertyName            The target property name
 207         * @param[in]    dataSource              The data binding source
 208         * @param[in]    sourceType              The data type of the @c dataSource
 209         * @param[in]    flow                            The data flow type
 210         * @param[in]    trigger                         The data binding trigger type
 211         * @param[in]    pListener               The data binding listener
 212         * @param[in]    pValidator              The data validator
 213         * @param[in]    pTransformer            The data transformer
 214         * @exception    E_SUCCESS                       The method is successful.
 215         * @exception    E_SYSTEM                        A system error has occurred.
 216         * @exception    E_INVALID_ARG  1. sourceType is not of a supported type.
 217                                          2. flow is not of a supported type.
 218                                          3. trigger is not of a supported type.
 219         * @exception    E_OBJ_NOT_FOUND        1. The control named controlName does not exist.
 220                                                   2. The parameter "propertyName" is not found in control properties.
 221         * @exception    E_UNSUPPORTED_FORMAT          The given transformer does not supported changing source type to target type.
 222         * @exception    E_UNSUPPORTED_OPERATION      In this system, binding with the given trigger and flow is not supported.
 223         * @remarks      The propertyName parameter is defined in "UI Builder Guide". @n
 224         *                     There is no duplication check for each binding ID. @n
 225         *                     Please use a unique binding ID for each binding setting.
 226         */
 227         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);
 228
 229         /**
 230         * Sets the binding listener for the specified data binding.
 231         *
 232         * @since 2.0
 233         *
 234         * @return        An error code
 235         * @param[in]    bindingId               The binding ID
 236         * @param[in]    pListener               The data binding listener
 237         * @exception    E_SUCCESS               The method is successful.
 238         * @exception    E_SYSTEM                A system error has occurred.
 239         * @exception    E_OBJ_NOT_FOUND     The given binding ID is not registered.
 240         * @exception    E_INVALID_ARG  The given listener is not valid.
 241         * @remarks       If you give pListener parameter as 'null', the existing dataBindingEventListener will be removed.
 242         */
 243         result SetDataBindingEventListener(const Tizen::Base::String& bindingId, IDataBindingListener* pListener);
 244
 245         /**
 246         * Unbinds all bindings that exist in this context.
 247         *
 248         * @since 2.0
 249         *
 250         * @return        An error code
 251         * @exception    E_SUCCESS        The method is successful.
 252         * @exception    E_SYSTEM         A system error has occurred.
 253         */
 254         result UnbindAll(void);
 255
 256         /**
 257         * Unbinds a binding that exists in this context.
 258         *
 259         * @since 2.0
 260         *
 261         * @return        An error code
 262         * @param[in]    bindingId        The binding ID
 263         * @exception    E_SUCCESS        The method is successful.
 264         * @exception    E_SYSTEM         A system error has occurred.
 265         * @exception    E_OBJ_NOT_FOUND        The given binding ID is not registered.
 266         */
 267         result Unbind(const Tizen::Base::String& bindingId);
 268
 269         /**
 270         * Updates all 'explicit' data bindings.
 271         *
 272         * @since 2.0
 273         *
 274         * @return        An error code
 275         * @param[in]    destType                The destination type
 276         * @exception    E_SUCCESS               The method is successful.
 277         * @exception    E_SYSTEM                A system error has occurred.
 278         * @exception    E_INVALID_ARG           The specified @c destType is not of a supported type.
 279         * @remarks
 280         *                                       - If you have set a data binding listener, @n
 281         *                                       this method is returned after that listener is called.
 282         *                                       - The behavior of this method is dependent on the system default locale setting.
 283         * @see    IDataBindingListener
 284         */
 285         result UpdateAllBindings(DataBindingDestinationType destType);
 286
 287         /**
 288         * Updates the specified data binding.
 289
 290         * @since 2.0
 291         *
 292         * @param[in]    bindingId               The binding ID
 293         * @param[in]    destType                The destination type
 294         * @exception    E_SUCCESS               The method is successful.
 295         * @exception    E_SYSTEM                A system error has occurred.
 296         * @exception    E_OBJ_NOT_FOUND         The given binding ID is not registered.
 297         * @exception    E_INVALID_OPERATION    The given binding's trigger is not 'explicit' type.
 298         * @exception    E_INVALID_ARG  The specified @c destType is not supported in binding ID.
 299         * @remarks
 300         *                               - If you have set a data binding listener, @n
 301         *                               this method is returned after that listener is called.
 302         *                               - The behavior of this method is dependent on the system default locale setting.
 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_