extensions/source/propctrlr/formcomponenthandler.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_EXTENSIONS_SOURCE_PROPCTRLR_FORMCOMPONENTHANDLER_HXX
  21 #define INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_FORMCOMPONENTHANDLER_HXX
  22
  23 #include <memory>
  24 #include "propertyhandler.hxx"
  25 #include "sqlcommanddesign.hxx"
  26 #include "pcrcommon.hxx"
  27 #include <comphelper/uno3.hxx>
  28 #include <comphelper/proparrhlp.hxx>
  29 #include <comphelper/propertycontainer.hxx>
  30 #include <com/sun/star/beans/XPropertyState.hpp>
  31 #include <com/sun/star/sdbc/XRowSet.hpp>
  32 #include <com/sun/star/awt/XControlContainer.hpp>
  33 #include <com/sun/star/form/XForm.hpp>
  34 #include <tools/fldunit.hxx>
  35 #include <vcl/waitobj.hxx>
  36 #include <connectivity/dbtools.hxx>
  37
  38 #include <set>
  39
  40
  41 namespace pcr
  42 {
  43
  44
  45     //= ComponentClassification
  46
  47     enum ComponentClassification
  48     {
  49         eFormControl,
  50         eDialogControl,
  51         eUnknown
  52     };
  53
  54
  55     //= FormComponentPropertyHandler
  56
  57     class FormComponentPropertyHandler;
  58     typedef HandlerComponentBase< FormComponentPropertyHandler > FormComponentPropertyHandler_Base;
  59     typedef ::comphelper::OPropertyArrayUsageHelper<FormComponentPropertyHandler> FormComponentPropertyHandler_PROP;
  60     /** default ->XPropertyHandler for all form components.
  61     */
  62     class FormComponentPropertyHandler :    public FormComponentPropertyHandler_Base,
  63                                             public ::comphelper::OPropertyContainer,
  64                                             public FormComponentPropertyHandler_PROP
  65     {
  66     private:
  67         /// access to property states
  68         css::uno::Reference< css::beans::XPropertyState >             m_xPropertyState;
  69         /// the parent of our component
  70         css::uno::Reference< css::uno::XInterface >                   m_xObjectParent;
  71
  72         /// the database connection. Owned by us if and only if we created it ourself.
  73         mutable ::dbtools::SharedConnection                           m_xRowSetConnection;
  74         css::uno::Reference< css::sdbc::XRowSet >                     m_xRowSet;
  75         /** helper component encapsulating the handling for the QueryDesign component for
  76             interactively designing an SQL command
  77         */
  78         ::rtl::Reference< SQLCommandDesigner >                        m_xCommandDesigner;
  79         css::uno::Reference< css::inspection::XObjectInspectorUI >    m_xBrowserUI;
  80
  81         /// the string indicating a "default" (VOID) value in list-like controls
  82         OUString                        m_sDefaultValueString;
  83         /// all properties to whose control's we added ->m_sDefaultValueString
  84         std::set< OUString >          m_aPropertiesWithDefListEntry;
  85         /// type of our component
  86         ComponentClassification         m_eComponentClass;
  87         /// is our component a (database) sub form?
  88         bool                            m_bComponentIsSubForm : 1;
  89         /// our component has a "ListSource" property
  90         bool                            m_bHaveListSource : 1;
  91         /// our component has a "Command" property
  92         bool                            m_bHaveCommand : 1;
  93         /// the class id of the component - if applicable
  94         sal_Int16                       m_nClassId;
  95
  96     public:
  97         explicit FormComponentPropertyHandler(
  98             const css::uno::Reference< css::uno::XComponentContext >& _rxContext
  99         );
 100
 101         DECLARE_XINTERFACE( )
 102
 103         // XPropertySet
 104         virtual css::uno::Reference< css::beans::XPropertySetInfo > SAL_CALL getPropertySetInfo(  ) override;
 105
 106         /// @throws css::uno::RuntimeException
 107         static OUString getImplementationName_static(  );
 108         /// @throws css::uno::RuntimeException
 109         static css::uno::Sequence< OUString > getSupportedServiceNames_static(  );
 110
 111     protected:
 112         virtual ~FormComponentPropertyHandler() override;
 113
 114     protected:
 115         virtual ::cppu::IPropertyArrayHelper* createArrayHelper( ) const override;
 116         virtual ::cppu::IPropertyArrayHelper& SAL_CALL getInfoHelper() override;
 117         // XPropertyHandler overridables
 118         virtual css::uno::Any                          SAL_CALL getPropertyValue( const OUString& _rPropertyName ) override;
 119         virtual void                                   SAL_CALL setPropertyValue( const OUString& _rPropertyName, const css::uno::Any& _rValue ) override;
 120         virtual css::uno::Any                          SAL_CALL convertToPropertyValue( const OUString& _rPropertyName, const css::uno::Any& _rControlValue ) override;
 121         virtual css::uno::Any                          SAL_CALL convertToControlValue( const OUString& _rPropertyName, const css::uno::Any& _rPropertyValue, const css::uno::Type& _rControlValueType ) override;
 122         virtual css::beans::PropertyState              SAL_CALL getPropertyState( const OUString& _rPropertyName ) override;
 123         virtual void                                   SAL_CALL addPropertyChangeListener( const css::uno::Reference< css::beans::XPropertyChangeListener >& _rxListener ) override;
 124         virtual void                                   SAL_CALL removePropertyChangeListener( const css::uno::Reference< css::beans::XPropertyChangeListener >& _rxListener ) override;
 125         virtual css::uno::Sequence< OUString >         SAL_CALL getSupersededProperties() override;
 126         virtual css::uno::Sequence< OUString >         SAL_CALL getActuatingProperties() override;
 127         virtual css::inspection::LineDescriptor        SAL_CALL describePropertyLine( const OUString& _rPropertyName, const css::uno::Reference< css::inspection::XPropertyControlFactory >& _rxControlFactory ) override;
 128         virtual css::inspection::InteractiveSelectionResult
 129                                                        SAL_CALL onInteractivePropertySelection( const OUString& _rPropertyName, sal_Bool _bPrimary, css::uno::Any& _rData, const css::uno::Reference< css::inspection::XObjectInspectorUI >& _rxInspectorUI ) override;
 130         virtual void                                   SAL_CALL actuatingPropertyChanged( const OUString& _rActuatingPropertyName, const css::uno::Any& _rNewValue, const css::uno::Any& _rOldValue, const css::uno::Reference< css::inspection::XObjectInspectorUI >& _rxInspectorUI, sal_Bool _bFirstTimeInit ) override;
 131         virtual sal_Bool                               SAL_CALL suspend( sal_Bool _bSuspend ) override;
 132
 133         // XComponent
 134         virtual void                                   SAL_CALL disposing() override;
 135
 136         // PropertyHandler
 137         virtual css::uno::Sequence< css::beans::Property >
 138                                                     doDescribeSupportedProperties() const override;
 139         virtual void onNewComponent() override;
 140
 141     private:
 142         /** classifies our component, in case it's a control model, by ClassId
 143
 144             Note that UNO dialog controls are also classified, though they don't have the ClassId property
 145         */
 146         void    impl_classifyControlModel_throw();
 147
 148         bool isReportModel() const;
 149
 150         /** const-version of ->getPropertyValue
 151         */
 152         css::uno::Any impl_getPropertyValue_throw( const OUString& _rPropertyName ) const;
 153
 154         // some property values are faked, and not used in the way they're provided by our component
 155         void impl_normalizePropertyValue_nothrow( css::uno::Any& _rValue, PropertyId _nPropId ) const;
 156
 157         /** determines whether we should exclude a given property from our "supported properties"
 158         */
 159         bool impl_shouldExcludeProperty_nothrow( const css::beans::Property& _rProperty ) const;
 160
 161         /** initializes the list of field names, if we're handling a control which supports the
 162             DataField property
 163         */
 164         void impl_initFieldList_nothrow( std::vector< OUString >& rFieldNames ) const;
 165
 166         /** obtains the RowSet to which our component belongs
 167
 168             If the component is a RowSet itself, it's returned directly. Else, the parent
 169             is examined for the XRowSet interface. If the parent is no XRowSet, then
 170             a check is made whether our component is a grid control column, and if so,
 171             the parent of the grid control is examined for the XRowSet interface.
 172
 173             Normally, at least one of those methods should succeed.
 174         */
 175         css::uno::Reference< css::sdbc::XRowSet > impl_getRowSet_throw( ) const;
 176
 177         /** nothrow-version of ->impl_getRowSet_throw
 178         */
 179         css::uno::Reference< css::sdbc::XRowSet > impl_getRowSet_nothrow( ) const;
 180
 181         /** connects the row set belonging to our introspected data aware form component,
 182             and remembers the connection in ->m_xRowSetConnection.
 183
 184             If the row set already is connected, ->m_xRowSetConnection will be set, too, but
 185             not take the ownership of the connection.
 186
 187             If ->m_xRowSetConnection is already set, nothing happens, so if you want to
 188             force creation of a connection, you need to clear ->m_xRowSetConnection.
 189         */
 190         bool impl_ensureRowsetConnection_nothrow() const;
 191
 192         /** fills an ->LineDescriptor with information to represent a cursor source
 193             of our form - that is, a table, a query, or an SQL statement.
 194
 195             As an example, if our form has currently a CommandType of TABLE, then the
 196             value list in the LineDescriptor will contain a list of all tables
 197             of the data source which the form is bound to.
 198
 199             @seealso impl_fillTableNames_throw
 200             @seealso impl_fillQueryNames_throw
 201         */
 202         void impl_describeCursorSource_nothrow(
 203                 css::inspection::LineDescriptor& _out_rProperty,
 204                 const css::uno::Reference< css::inspection::XPropertyControlFactory >& _rxControlFactory
 205             ) const;
 206
 207         /** describes the UI for selecting a table name
 208
 209             @precond
 210                 m_xRowSetConnection is not <NULL/>
 211         */
 212         void impl_fillTableNames_throw( std::vector< OUString >& _out_rNames ) const;
 213
 214         /** describes the UI for selecting a query name
 215
 216             @precond
 217                 m_xRowSetConnection is not <NULL/>
 218         */
 219         void impl_fillQueryNames_throw( std::vector< OUString >& _out_rNames ) const;
 220
 221         /** describes the UI for selecting a query name
 222
 223             @precond
 224                 m_xRowSetConnection is not <NULL/>
 225         */
 226         void impl_fillQueryNames_throw( const css::uno::Reference< css::container::XNameAccess >& _xQueryNames
 227                     ,std::vector< OUString >& _out_rNames
 228                     ,const OUString& _sName = OUString() ) const;
 229
 230         /** describes the UI for selecting a ListSource (for list-like form controls)
 231             @precond
 232                 ->m_xRowSetConnection is not <NULL/>
 233             @precond
 234                 ->m_xComponent is not <NULL/>
 235         */
 236         void impl_describeListSourceUI_throw(
 237                 css::inspection::LineDescriptor& _out_rDescriptor,
 238                 const css::uno::Reference< css::inspection::XPropertyControlFactory >& _rxControlFactory
 239             ) const;
 240
 241         /** displays a database-related error to the user
 242         */
 243         void impl_displaySQLError_nothrow( const ::dbtools::SQLExceptionInfo& _rErrorDescriptor ) const;
 244
 245         /** let's the user chose a selection of entries from a string list, and stores this
 246             selection in the given property
 247             @return
 248                 <TRUE/> if and only if the user successfully changed the property
 249         */
 250         bool impl_dialogListSelection_nothrow( const OUString& _rProperty, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 251
 252         /** executes a dialog for choosing a filter or sort criterion for a database form
 253             @param _bFilter
 254                 <TRUE/> if the Filter property should be used, <FALSE/> if it's the Order
 255                 property
 256             @param _out_rSelectedClause
 257                 the filter or order clause as chosen by the user
 258             @precond
 259                 we're really inspecting a database form (well, a RowSet at least)
 260             @return
 261                 <TRUE/> if and only if the user successfully chose a clause
 262         */
 263         bool impl_dialogFilterOrSort_nothrow( bool _bFilter, OUString& _out_rSelectedClause, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 264
 265         /** executes a dialog which allows the user to chose the columns linking
 266             a sub to a master form, and sets the respective MasterFields / SlaveFields
 267             properties at the form.
 268             @precond
 269                 we're inspecting (sub) database form
 270             @return
 271                 <TRUE/> if and only if the user successfully enter master and slave fields
 272         */
 273         bool impl_dialogLinkedFormFields_nothrow( ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 274
 275         /** executes a dialog which allows the user to modify the FormatKey
 276             property of our component, by choosing a (number) format.
 277             @precond
 278                 Our component actually has a FormatKey property.
 279             @param _out_rNewValue
 280                 the new property value, if the user chose a new formatting
 281             @return
 282                 <TRUE/> if and only if a new formatting has been chosen by the user.
 283                 In this case, ->_out_rNewValue is filled with the new property value
 284         */
 285         bool impl_dialogFormatting_nothrow( css::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 286
 287         /** executes a dialog which allows to the user to change the ImageURL property
 288             of our component by browsing for an image file.
 289             @precond
 290                 our component actually has an ImageURL property
 291             @param _out_rNewValue
 292                 the new property value, if the user chose a new image url
 293             @return
 294                 <TRUE/> if and only if a new image URL has been chosen by the user.
 295                 In this case, ->_out_rNewValue is filled with the new property value
 296         */
 297         bool impl_browseForImage_nothrow( css::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 298
 299         /** executes a dialog which allows the user to change the TargetURL property of
 300             our component
 301             @precond
 302                 our component actually has a TargetURL property
 303             @param _out_rNewValue
 304                 the new property value, if the user chose a new TargetURL
 305             @return
 306                 <TRUE/> if and only if a new TargetURL has been chosen by the user.
 307                 In this case, ->_out_rNewValue is filled with the new property value
 308         */
 309         bool impl_browseForTargetURL_nothrow( css::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 310
 311         /** executes a dialog which allows the user to change the font, plus related properties,
 312             of our component
 313             @precond
 314                 our component actually has a Font property
 315             @param _out_rNewValue
 316                 a value describing the new font, as <code>Sequence&lt; NamedValue &gt;</code>
 317             @return
 318                 <TRUE/> if and only if the user successfully changed the font of our component
 319         */
 320         bool impl_executeFontDialog_nothrow( css::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 321
 322         /** allows the user browsing for a database document
 323             @precond
 324                 our component actually has a DataSource property
 325             @param _out_rNewValue
 326                 the new property value, if the user chose a new DataSource
 327             @return
 328                 <TRUE/> if and only if a new DataSource has been chosen by the user.
 329                 In this case, ->_out_rNewValue is filled with the new property value
 330         */
 331         bool impl_browseForDatabaseDocument_throw( css::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 332
 333         /** raises a dialog which allows the user to choose a color
 334             @param  _nColorPropertyId
 335                 the ID of the color property
 336             @param  _out_rNewValue
 337                 the chosen color value
 338             @return
 339                 <TRUE/> if and only if a color was chosen by the user
 340         */
 341         bool impl_dialogColorChooser_throw( sal_Int32 _nColorPropertyId, css::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 342
 343         /** raises a dialog which allows the user to choose a label control for our component
 344             @param  _out_rNewValue
 345                 the chosen label control, if any
 346             @return
 347                 <TRUE/> if and only if a label control was chosen by the user
 348         */
 349         bool impl_dialogChooseLabelControl_nothrow( css::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 350
 351         /** raises a dialog which lets the user chose the tab order of controls of a form
 352             @precond
 353                 we have a view control container in which our controls live
 354             @return
 355                 <TRUE/> if and only if the user successfully changed the tab order
 356             @seealso impl_getContextControlContainer_nothrow
 357         */
 358         bool impl_dialogChangeTabOrder_nothrow( ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
 359
 360         /** retrieves the context for controls, whose model(s) we're inspecting
 361
 362             If we're inspecting a control model, this is usually part of a set of controls
 363             and control models, where the controls live in a certain context (a ->XControlContainer).
 364             If we know this context, we can enable additional special functionality.
 365
 366             The ->XComponentContext in which we were created is examined for a value
 367             named "ControlContext", and this value is returned.
 368         */
 369         css::uno::Reference< css::awt::XControlContainer >
 370             impl_getContextControlContainer_nothrow() const;
 371
 372         /** opens a query design window for interactively designing the SQL command of a
 373             database form
 374             @param _rxUIUpdate
 375                 access to the property browser UI
 376             @param _nDesignForProperty
 377                 the ID for the property for which the designer is opened
 378             @return
 379                 <TRUE/> if the window was successfully opened, or was previously open,
 380                 <FALSE/> otherwise
 381         */
 382         bool impl_doDesignSQLCommand_nothrow(
 383             const css::uno::Reference< css::inspection::XObjectInspectorUI >& _rxInspectorUI,
 384             PropertyId _nDesignForProperty
 385         );
 386
 387         /** updates a property (UI) whose state depends on more than one other property
 388
 389             ->actuatingPropertyChanged is called for certain properties in whose changes
 390             we expressed interes (->getActuatingProperty). Now such a property change can
 391             result in simple UI updates, for instance another property being enabled or disabled.
 392
 393             However, it can also result in a more complex change: The current (UI) state might
 394             depend on the value of more than one other property. Those dependent properties (their
 395             UI, more precisely) are updated in this method.
 396
 397             @param _nPropid
 398                 the ->PropertyId of the dependent property whose UI state is to be updated
 399
 400             @param _rxInspectorUI
 401                 provides access to the property browser UI. Must not be <NULL/>.
 402         */
 403         void impl_updateDependentProperty_nothrow( PropertyId _nPropId, const css::uno::Reference< css::inspection::XObjectInspectorUI >& _rxInspectorUI ) const;
 404
 405         /** determines whether the given form has a valid data source signature.
 406
 407             Valid here means that the DataSource property denotes an existing data source, and the
 408             Command property is not empty. No check is made whether the value of the Command property
 409             denotes an existent object, since this would be way too expensive.
 410
 411             @param _xFormProperties
 412                 the form to check. Must not be <NULL/>.
 413             @param _bAllowEmptyDataSourceName
 414                 determine whether an empty data source name is allowed (<TRUE/>), and should not
 415                 lead to rejection
 416         */
 417         static bool impl_hasValidDataSourceSignature_nothrow(
 418                 const css::uno::Reference< css::beans::XPropertySet >& _xFormProperties,
 419                 bool _bAllowEmptyDataSourceName );
 420
 421         /** returns the URL of our context document
 422             @return
 423         */
 424         OUString impl_getDocumentURL_nothrow() const;
 425
 426     private:
 427         DECL_LINK( OnDesignerClosed, SQLCommandDesigner&, void );
 428
 429     private:
 430         FormComponentPropertyHandler( const FormComponentPropertyHandler& ) = delete;
 431         FormComponentPropertyHandler& operator=( const FormComponentPropertyHandler& ) = delete;
 432
 433     private:
 434         using ::comphelper::OPropertyContainer::addPropertyChangeListener;
 435         using ::comphelper::OPropertyContainer::removePropertyChangeListener;
 436     };
 437
 438
 439 } // namespace pcr
 440
 441
 442 #endif // INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_FORMCOMPONENTHANDLER_HXX
 443
 444 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */