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