forms/source/xforms/binding.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_FORMS_SOURCE_XFORMS_BINDING_HXX
  21 #define INCLUDED_FORMS_SOURCE_XFORMS_BINDING_HXX
  22
  23 #include <com/sun/star/uno/Reference.hxx>
  24 #include <cppuhelper/implbase.hxx>
  25 #include "propertysetbase.hxx"
  26 #include <com/sun/star/form/binding/XValueBinding.hpp>
  27 #include <com/sun/star/form/binding/XListEntrySource.hpp>
  28 #include <com/sun/star/form/validation/XValidator.hpp>
  29 #include <com/sun/star/util/XModifyBroadcaster.hpp>
  30 #include <com/sun/star/container/XNamed.hpp>
  31 #include <com/sun/star/xml/dom/events/XEventListener.hpp>
  32 #include <com/sun/star/lang/XUnoTunnel.hpp>
  33 #include <com/sun/star/util/XCloneable.hpp>
  34
  35 #include "pathexpression.hxx"
  36 #include "boolexpression.hxx"
  37 #include "mip.hxx"
  38 #include <rtl/ustring.hxx>
  39 #include <vector>
  40
  41 // forward declaractions
  42 namespace xforms
  43 {
  44     class Model;
  45     class EvaluationContext;
  46 }
  47 namespace com::sun::star {
  48     namespace xml {
  49         namespace xpath { class XXPathAPI; }
  50         namespace dom
  51         {
  52             class XNode;
  53             class XNodeList;
  54         }
  55     }
  56     namespace container { class XNameContainer; }
  57     namespace xforms { class XModel; }
  58     namespace xsd { class XDataType; }
  59 }
  60
  61
  62 namespace xforms
  63 {
  64
  65 /** An XForms Binding. Contains:
  66  *  # a connection to its model
  67  *  # an ID
  68  *  # a binding expression
  69  *  # model item properties
  70  *  # (NOT YET IMPLEMENTED) child bindings (sequence of)
  71  *
  72  * See http://www.w3.org/TR/xforms/ for more information.
  73  */
  74
  75 typedef cppu::ImplInheritanceHelper<
  76     PropertySetBase,
  77     css::form::binding::XValueBinding,
  78     css::form::binding::XListEntrySource,
  79     css::form::validation::XValidator,
  80     css::util::XModifyBroadcaster,
  81     css::container::XNamed,
  82     css::xml::dom::events::XEventListener,
  83     css::lang::XUnoTunnel,
  84     css::util::XCloneable
  85 > Binding_t;
  86
  87 class Binding : public Binding_t
  88 {
  89 public:
  90     typedef std::vector<css::uno::Reference<css::util::XModifyListener> > ModifyListeners_t;
  91     typedef std::vector<css::uno::Reference<css::form::validation::XValidityConstraintListener> > XValidityConstraintListeners_t;
  92     typedef std::vector<css::uno::Reference<css::form::binding::XListEntryListener> > XListEntryListeners_t;
  93
  94
  95 private:
  96
  97     /// the Model to which this Binding belongs; may be NULL
  98     css::uno::Reference<css::xforms::XModel> mxModel;
  99
 100     /// binding-ID. A document-wide unique ID for this binding element.
 101     OUString msBindingID;
 102
 103     /// an XPath-expression to be instantiated on the data instance
 104     PathExpression maBindingExpression;
 105
 106     /// an XPath-expression to determine read-only status
 107     BoolExpression maReadonly;
 108
 109     /// an XPath-expression to determine relevance
 110     BoolExpression maRelevant;
 111
 112     /// an XPath-expression to determine if item is required
 113     BoolExpression maRequired;
 114
 115     /// an XPath-expression to determine if item is valid
 116     BoolExpression maConstraint;
 117
 118     /// user-readable explanation of the constraint
 119     OUString msExplainConstraint;
 120
 121     /// an XPath-expression to calculate values
 122     ComputedExpression maCalculate;
 123
 124     /// the XML namespaces used for XML names/XPath-expressions in this binding
 125     css::uno::Reference<css::container::XNameContainer> mxNamespaces;
 126
 127     /// a type name
 128     OUString msTypeName;
 129
 130     /// modify listeners
 131     ModifyListeners_t maModifyListeners;
 132
 133     /// list entry listener
 134     XListEntryListeners_t maListEntryListeners;
 135
 136     /// validity listeners;
 137     XValidityConstraintListeners_t maValidityListeners;
 138
 139     /// nodes on which we are listening for events
 140     std::vector<css::uno::Reference<css::xml::dom::XNode> > maEventNodes;
 141
 142     /// the current MIP object for the first node we are bound to
 143     MIP maMIP;
 144
 145     /// flag to detect recursions in calculate
 146     bool mbInCalculate;
 147
 148     // flags to manage deferred notifications:
 149     /// if >0, valueModified() and bindingModified() will only set flags
 150     sal_Int32 mnDeferModifyNotifications;
 151     bool mbValueModified;   /// if true, valueModified needs to be called
 152     bool mbBindingModified; /// if true, bindingModified needs to be called
 153
 154
 155     void initializePropertySet();
 156
 157
 158 public:
 159     Binding();
 160     virtual ~Binding() override;
 161
 162
 163     // property methods: get/set value
 164
 165
 166     css::uno::Reference<css::xforms::XModel> getModel() const { return mxModel;}   /// get XForms model
 167     void _setModel( const css::uno::Reference<css::xforms::XModel>& ); /// set XForms model (only called by Model)
 168
 169
 170     OUString getModelID() const;   /// get ID of XForms model
 171
 172     OUString getBindingID() const { return msBindingID;}         /// get ID for this binding
 173     void setBindingID( const OUString& );  /// set ID for this binding
 174
 175     OUString getBindingExpression() const; /// get binding expression
 176     void setBindingExpression( const OUString& );  /// set binding exp.
 177
 178     // MIPs (model item properties)
 179
 180     OUString getReadonlyExpression() const;         /// get read-only MIP
 181     void setReadonlyExpression( const OUString& );  /// set read-only MIP
 182
 183     OUString getRelevantExpression() const;         /// get relevant MIP
 184     void setRelevantExpression( const OUString& );  /// set relevant MIP
 185
 186     OUString getRequiredExpression() const;         /// get required MIP
 187     void setRequiredExpression( const OUString& );  /// set required MIP
 188
 189     OUString getConstraintExpression() const;       /// get constraint MIP
 190     void setConstraintExpression( const OUString& );/// set constraint MIP
 191
 192     OUString getCalculateExpression() const;        /// get calculate MIP
 193     void setCalculateExpression( const OUString& ); /// set calculate MIP
 194
 195     OUString getType() const { return msTypeName;}         /// get type name MIP (static)
 196     void setType( const OUString& );  /// set type name MIP (static)
 197
 198     // a binding expression can only be interpreted with respect to
 199     // suitable namespace declarations. We collect those in the model and in a binding.
 200
 201     // access to a binding's namespace
 202     // (set-method only changes local namespaces (but may add to model))
 203     css::uno::Reference<css::container::XNameContainer> getBindingNamespaces() const { return mxNamespaces; }
 204     void setBindingNamespaces( const css::uno::Reference<css::container::XNameContainer>& ); /// get binding nmsp.
 205
 206     // access to the model's namespaces
 207     // (set-method changes model's namespaces (unless a local one is present))
 208     css::uno::Reference<css::container::XNameContainer> getModelNamespaces() const;  /// set model namespaces
 209     void setModelNamespaces( const css::uno::Reference<css::container::XNameContainer>& ); /// get model nmsp.
 210
 211
 212     // read-only properties that map MIPs to control data source properties
 213     bool getReadOnly() const;       // MIP readonly
 214     bool getRelevant() const;       // MIP relevant
 215     bool getExternalData() const;   // mapped from model's ExternalData property
 216
 217
 218     // missing binding properties:
 219     // - type (static; default: xsd:string)
 220     // - minOccurs/maxOccurs (computed XPath; default: 0/inf)
 221     // - p3ptype (static; no default)
 222
 223
 224     /// get this binding's context node
 225     xforms::EvaluationContext getEvaluationContext() const;
 226
 227     /// get evaluation contexts for this binding's MIPs
 228     std::vector<xforms::EvaluationContext> getMIPEvaluationContexts();
 229
 230     /// get nodeset the bind is bound to
 231     css::uno::Reference<css::xml::dom::XNodeList> getXNodeList();
 232
 233     /// heuristically determine whether this binding is simple binding
 234     /// (here: simple binding == does not depend on other parts of the
 235     ///                          instance, it's not a 'dynamic' binding)
 236     bool isSimpleBinding() const;
 237
 238     /// heuristically determine whether this binding's binding
 239     /// expression is simple
 240     bool isSimpleBindingExpression() const;
 241
 242     /// update this binding (e.g. called by model for refresh )
 243     void update();
 244
 245     /// prevent change notifications being sent to controls
 246     void deferNotifications( bool );
 247
 248     /// is this binding valid? (are constraint, type and required MIPs ok?)
 249     bool isValid() const;
 250
 251     /// determine whether this binding currently performs a useful
 252     /// function, r whether is may be discarded
 253     bool isUseful() const;
 254
 255     /// explain why binding is invalid
 256     OUString explainInvalid();
 257
 258
 259     // the ID for XUnoTunnel calls
 260     static css::uno::Sequence<sal_Int8> getUnoTunnelId();
 261
 262
 263 private:
 264     /// check whether object is live, and throw suitable exception if not
 265     /// (to be used be API methods before acting on the object)
 266     ///
 267     /// @throws css::uno::RuntimeException
 268     void checkLive();
 269
 270     /// determine whether object is live
 271     /// live: has model, and model has been initialized
 272     bool isLive() const;
 273
 274     /// get the model implementation
 275     xforms::Model* getModelImpl() const;
 276
 277     /// get MIP evaluation contexts
 278     /// (only valid if control has already been bound)
 279     std::vector<xforms::EvaluationContext> _getMIPEvaluationContexts() const;
 280
 281     /// bind this binding, and pre-compute the affected nodes
 282     void bind( bool bForceRebind = false );
 283
 284     /// the binding value has been changed:
 285     ///   trigger a modified event on all modified listeners
 286     void valueModified();
 287
 288     /// the binding itself has changed:
 289     ///   force rebind, then call valueModified()
 290     void bindingModified();
 291
 292
 293     /// set MIPs defined by this binding on MIP item
 294     MIP getLocalMIP() const;
 295
 296     /// get the data type that applies to this binding
 297     css::uno::Reference<css::xsd::XDataType> getDataType() const;
 298
 299     /// determine whether binding is valid according to the given data type
 300     bool isValid_DataType() const;
 301
 302     /// explain validity of binding with respect to the given data type
 303     OUString explainInvalid_DataType();
 304
 305     /// 'clear' this binding - remove all listeners, etc.
 306     void clear();
 307
 308     /// distribute MIPs from current node recursively to children
 309     void distributeMIP( const css::uno::Reference<css::xml::dom::XNode> &rxNode );
 310
 311     /// implement get*Namespaces()
 312     css::uno::Reference<css::container::XNameContainer> _getNamespaces() const;
 313
 314     /// implement set*Namespaces()
 315     void _setNamespaces( const css::uno::Reference<css::container::XNameContainer>&, bool bBinding );
 316
 317     /// set a useful default binding ID (if none is set)
 318     void _checkBindingID();
 319
 320 public:
 321
 322     virtual css::uno::Sequence<css::uno::Type> SAL_CALL getSupportedValueTypes() override;
 323
 324     virtual sal_Bool SAL_CALL supportsType( const css::uno::Type& aType ) override;
 325
 326     virtual css::uno::Any SAL_CALL getValue( const css::uno::Type& aType ) override;
 327
 328     virtual void SAL_CALL setValue( const css::uno::Any& aValue ) override;
 329
 330
 331     // XListEntrySource
 332
 333
 334     virtual sal_Int32 SAL_CALL getListEntryCount() override;
 335
 336     virtual OUString SAL_CALL getListEntry( sal_Int32 nPosition ) override;
 337
 338     virtual css::uno::Sequence<OUString> SAL_CALL getAllListEntries() override;
 339
 340     virtual void SAL_CALL addListEntryListener( const css::uno::Reference<css::form::binding::XListEntryListener>& ) override;
 341
 342     virtual void SAL_CALL removeListEntryListener( const css::uno::Reference<css::form::binding::XListEntryListener>&) override;
 343
 344
 345     // XValidator:
 346
 347
 348     virtual sal_Bool SAL_CALL isValid(
 349         const css::uno::Any& ) override;
 350
 351     virtual OUString SAL_CALL explainInvalid(
 352         const css::uno::Any& ) override;
 353
 354     virtual void SAL_CALL addValidityConstraintListener(
 355         const css::uno::Reference<css::form::validation::XValidityConstraintListener>& xListener ) override;
 356
 357     virtual void SAL_CALL removeValidityConstraintListener(
 358         const css::uno::Reference<css::form::validation::XValidityConstraintListener>& xListener ) override;
 359
 360
 361     // XModifyBroadcaster & friends:
 362     //   inform listeners about changes in our values
 363
 364
 365 public:
 366
 367     virtual void SAL_CALL addModifyListener(
 368         const css::uno::Reference<css::util::XModifyListener>& xListener ) override;
 369
 370     virtual void SAL_CALL removeModifyListener(
 371         const css::uno::Reference<css::util::XModifyListener>& xListener ) override;
 372
 373
 374     // XNamed:
 375     //   get/set name
 376
 377
 378 public:
 379
 380     virtual OUString SAL_CALL getName() override;
 381
 382     virtual void SAL_CALL setName( const OUString& ) override;
 383
 384
 385     // xml::dom::event::XEventListener
 386     //   receive an event if our node changed
 387
 388
 389     virtual void SAL_CALL handleEvent(
 390         const css::uno::Reference<css::xml::dom::events::XEvent>& xEvent ) override;
 391
 392
 393     // XUnoTunnel
 394
 395
 396     virtual sal_Int64 SAL_CALL getSomething( const css::uno::Sequence<sal_Int8>& ) override;
 397
 398
 399     // XCloneable
 400
 401
 402     virtual css::uno::Reference<css::util::XCloneable> SAL_CALL createClone() override;
 403 };
 404
 405
 406 } // namespace xforms
 407
 408 #endif
 409
 410 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */