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