bump product version to 5.0.4.1
[LibreOffice.git] / extensions / source / propctrlr / formcomponenthandler.hxx
blobd99a68e273a19c6a9592e200ad4051360ac56703
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
20 #ifndef INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_FORMCOMPONENTHANDLER_HXX
21 #define INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_FORMCOMPONENTHANDLER_HXX
23 #include "propertyhandler.hxx"
24 #include "sqlcommanddesign.hxx"
25 #include "pcrcommon.hxx"
26 #include <comphelper/uno3.hxx>
27 #include <comphelper/proparrhlp.hxx>
28 #include <comphelper/propertycontainer.hxx>
29 #include <com/sun/star/frame/XModel.hpp>
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>
38 #include <set>
41 namespace pcr
46 //= ComponentClassification
48 enum ComponentClassification
50 eFormControl,
51 eDialogControl,
52 eUnknown
56 //= FormComponentPropertyHandler
58 class FormComponentPropertyHandler;
59 typedef HandlerComponentBase< FormComponentPropertyHandler > FormComponentPropertyHandler_Base;
60 typedef ::comphelper::OPropertyArrayUsageHelper<FormComponentPropertyHandler> FormComponentPropertyHandler_PROP;
61 /** default ->XPropertyHandler for all form components.
63 class FormComponentPropertyHandler : public FormComponentPropertyHandler_Base,
64 public ::comphelper::OPropertyContainer,
65 public FormComponentPropertyHandler_PROP
67 private:
68 /// access to property states
69 ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyState > m_xPropertyState;
70 /// the parent of our component
71 ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > m_xObjectParent;
73 /// the database connection. Owned by us if and only if we created it ourself.
74 mutable ::dbtools::SharedConnection m_xRowSetConnection;
75 ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XRowSet > m_xRowSet;
76 /** helper component encapsulating the handling for the QueryDesign component for
77 interactively designing an SQL command
79 ::rtl::Reference< SQLCommandDesigner > m_xCommandDesigner;
80 ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI > m_xBrowserUI;
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 appliable
95 sal_Int16 m_nClassId;
97 public:
98 FormComponentPropertyHandler(
99 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >& _rxContext
102 DECLARE_XINTERFACE( )
104 // XPropertySet
105 virtual ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySetInfo > SAL_CALL getPropertySetInfo( ) throw(::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
107 static OUString SAL_CALL getImplementationName_static( ) throw (::com::sun::star::uno::RuntimeException);
108 static ::com::sun::star::uno::Sequence< OUString > SAL_CALL getSupportedServiceNames_static( ) throw (::com::sun::star::uno::RuntimeException);
110 protected:
111 virtual ~FormComponentPropertyHandler();
113 protected:
114 virtual ::cppu::IPropertyArrayHelper* createArrayHelper( ) const SAL_OVERRIDE;
115 virtual ::cppu::IPropertyArrayHelper& SAL_CALL getInfoHelper() SAL_OVERRIDE;
116 // XPropertyHandler overridables
117 virtual ::com::sun::star::uno::Any SAL_CALL getPropertyValue( const OUString& _rPropertyName ) throw (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
118 virtual void SAL_CALL setPropertyValue( const OUString& _rPropertyName, const ::com::sun::star::uno::Any& _rValue ) throw (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
119 virtual ::com::sun::star::uno::Any SAL_CALL convertToPropertyValue( const OUString& _rPropertyName, const ::com::sun::star::uno::Any& _rControlValue ) throw (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
120 virtual ::com::sun::star::uno::Any SAL_CALL convertToControlValue( const OUString& _rPropertyName, const ::com::sun::star::uno::Any& _rPropertyValue, const ::com::sun::star::uno::Type& _rControlValueType ) throw (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
121 virtual ::com::sun::star::beans::PropertyState SAL_CALL getPropertyState( const OUString& _rPropertyName ) throw (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
122 virtual void SAL_CALL addPropertyChangeListener( const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyChangeListener >& _rxListener ) throw (::com::sun::star::lang::NullPointerException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
123 virtual void SAL_CALL removePropertyChangeListener( const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyChangeListener >& _rxListener ) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
124 virtual ::com::sun::star::uno::Sequence< OUString > SAL_CALL getSupersededProperties() throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
125 virtual ::com::sun::star::uno::Sequence< OUString > SAL_CALL getActuatingProperties() throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
126 virtual ::com::sun::star::inspection::LineDescriptor SAL_CALL describePropertyLine( const OUString& _rPropertyName, const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XPropertyControlFactory >& _rxControlFactory ) throw (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::NullPointerException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
127 virtual ::com::sun::star::inspection::InteractiveSelectionResult
128 SAL_CALL onInteractivePropertySelection( const OUString& _rPropertyName, sal_Bool _bPrimary, ::com::sun::star::uno::Any& _rData, const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >& _rxInspectorUI ) throw (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::NullPointerException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
129 virtual void SAL_CALL actuatingPropertyChanged( const OUString& _rActuatingPropertyName, const ::com::sun::star::uno::Any& _rNewValue, const ::com::sun::star::uno::Any& _rOldValue, const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >& _rxInspectorUI, sal_Bool _bFirstTimeInit ) throw (::com::sun::star::lang::NullPointerException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
130 virtual sal_Bool SAL_CALL suspend( sal_Bool _bSuspend ) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
132 // XComponent
133 virtual void SAL_CALL disposing() SAL_OVERRIDE;
135 // PropertyHandler
136 virtual ::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property >
137 SAL_CALL doDescribeSupportedProperties() const SAL_OVERRIDE;
138 virtual void onNewComponent() SAL_OVERRIDE;
140 private:
141 /** initializes some (cached) meta data about the component
142 @throws RuntimeException
143 if a serious error occurs, for instance if the component does not provide an XPropertySetInfo instance
145 void impl_initComponentMetaData_throw();
147 /** classifies our component, in case it's a control model, by ClassId
149 Note that UNO dialog controls are also classified, though they don't have the ClassId property
151 void impl_classifyControlModel_throw();
153 /** const-version of ->getPropertyValue
155 ::com::sun::star::uno::Any impl_getPropertyValue_throw( const OUString& _rPropertyName ) const;
157 // some property values are faked, and not used in the way they're provided by our component
158 void impl_normalizePropertyValue_nothrow( ::com::sun::star::uno::Any& _rValue, PropertyId _nPropId ) const;
160 /** determines whether we should exclude a given property from our "supported properties"
162 bool impl_shouldExcludeProperty_nothrow( const ::com::sun::star::beans::Property& _rProperty ) const;
164 /** initializes the list of field names, if we're handling a control which supports the
165 DataField property
167 void impl_initFieldList_nothrow( ::std::vector< OUString >& rFieldNames ) const;
169 /** obtaines the RowSet to which our component belongs
171 If the component is a RowSet itself, it's returned directly. Else, the parent
172 is examined for the XRowSet interface. If the parent is no XRowSet, then
173 a check is made whether our component is a grid control column, and if so,
174 the parent of the grid control is examied for the XRowSet interace.
176 Normally, at least one of those methods should succeed.
178 ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XRowSet > impl_getRowSet_throw( ) const;
180 /** nothrow-version of ->impl_getRowSet_throw
182 ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XRowSet > impl_getRowSet_nothrow( ) const;
184 /** connects the row set belonging to our introspected data aware form component,
185 and remembers the connection in ->m_xRowSetConnection.
187 If the row set already is connected, ->m_xRowSetConnection will be set, too, but
188 not take the ownership of the connection.
190 If ->m_xRowSetConnection is already set, nothing happens, so if you want to
191 force creation of a connection, you need to clear ->m_xRowSetConnection.
193 bool impl_ensureRowsetConnection_nothrow() const;
195 /** clears ->m_xRowSetConnection
197 void impl_clearRowsetConnection_nothrow();
199 /** fills an ->LineDescriptor with information to represent a cursor source
200 of our form - that is, a table, a query, or an SQL statement.
202 As an example, if our form has currently a CommandType of TABLE, then the
203 value list in the LineDescriptor will contain a list of all tables
204 of the data source which the form is bound to.
206 @seealso impl_fillTableNames_throw
207 @seealso impl_fillQueryNames_throw
209 void impl_describeCursorSource_nothrow(
210 ::com::sun::star::inspection::LineDescriptor& _out_rProperty,
211 const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XPropertyControlFactory >& _rxControlFactory
212 ) const;
214 /** describes the UI for selecting a table name
216 @precond
217 m_xRowSetConnection is not <NULL/>
219 void impl_fillTableNames_throw( ::std::vector< OUString >& _out_rNames ) const;
221 /** describes the UI for selecting a query name
223 @precond
224 m_xRowSetConnection is not <NULL/>
226 void impl_fillQueryNames_throw( ::std::vector< OUString >& _out_rNames ) const;
228 /** describes the UI for selecting a query name
230 @precond
231 m_xRowSetConnection is not <NULL/>
233 void impl_fillQueryNames_throw( const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >& _xQueryNames
234 ,::std::vector< OUString >& _out_rNames
235 ,const OUString& _sName = OUString() ) const;
237 /** describes the UI for selecting a ListSource (for list-like form controls)
238 @precond
239 ->m_xRowSetConnection is not <NULL/>
240 @precond
241 ->m_xComponent is not <NULL/>
243 void impl_describeListSourceUI_throw(
244 ::com::sun::star::inspection::LineDescriptor& _out_rDescriptor,
245 const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XPropertyControlFactory >& _rxControlFactory
246 ) const;
248 /** displays a datbase-related error to the user
250 void impl_displaySQLError_nothrow( const ::dbtools::SQLExceptionInfo& _rErrorDescriptor ) const;
252 /** let's the user chose a selection of entries from a string list, and stores this
253 selection in the given property
254 @return
255 <TRUE/> if and only if the user successfully changed the property
257 bool impl_dialogListSelection_nothrow( const OUString& _rProperty, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
259 /** executes a dialog for chosing a filter or sort criterion for a database form
260 @param _bFilter
261 <TRUE/> if the Filter property should be used, <FALSE/> if it's the Order
262 property
263 @param _out_rSelectedClause
264 the filter or order clause as chosen by the user
265 @precond
266 we're really inspecting a database form (well, a RowSet at least)
267 @return
268 <TRUE/> if and only if the user successfully chose a clause
270 bool impl_dialogFilterOrSort_nothrow( bool _bFilter, OUString& _out_rSelectedClause, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
272 /** executes a dialog which allows the user to chose the columns linking
273 a sub to a master form, and sets the respective MasterFields / SlaveFields
274 properties at the form.
275 @precond
276 we're inspecting (sub) database form
277 @return
278 <TRUE/> if and only if the user successfully eneter master and slave fields
280 bool impl_dialogLinkedFormFields_nothrow( ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
282 /** executes a dialog which allows the user to modify the FormatKey
283 property of our component, by chosing a (number) format.
284 @precond
285 Our component actually has a FormatKey property.
286 @param _out_rNewValue
287 the new property value, if the user chose a new formatting
288 @return
289 <TRUE/> if and only if a new formatting has been chosen by the user.
290 In this case, ->_out_rNewValue is filled with the new property value
292 bool impl_dialogFormatting_nothrow( ::com::sun::star::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
294 /** executes a dialog which allows to the user to change the ImageURL property
295 of our component by browsing for an image file.
296 @precond
297 our component actually has a ImageURL property
298 @param _out_rNewValue
299 the new property value, if the user chose a new image url
300 @return
301 <TRUE/> if and only if a new image URL has been chosen by the user.
302 In this case, ->_out_rNewValue is filled with the new property value
304 bool impl_browseForImage_nothrow( ::com::sun::star::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
306 /** executes a dialog which allows the user to change the TargetURL property of
307 our component
308 @precond
309 our component actually has a TargetURL property
310 @param _out_rNewValue
311 the new property value, if the user chose a new TargetURL
312 @return
313 <TRUE/> if and only if a new TargetURL has been chosen by the user.
314 In this case, ->_out_rNewValue is filled with the new property value
316 bool impl_browseForTargetURL_nothrow( ::com::sun::star::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
318 /** executes a dialog which allows the user to change the font, plus related properties,
319 of our component
320 @precond
321 our component actually has a Font property
322 @param _out_rNewValue
323 a value desribing the new font, as <code>Sequence&lt; NamedValue &gt;</code>
324 @return
325 <TRUE/> if and only if the user successfully changed the font of our component
327 bool impl_executeFontDialog_nothrow( ::com::sun::star::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
329 /** allows the user browsing for a database document
330 @precond
331 our component actually has a DataSource property
332 @param _out_rNewValue
333 the new property value, if the user chose a new DataSource
334 @return
335 <TRUE/> if and only if a new DataSource has been chosen by the user.
336 In this case, ->_out_rNewValue is filled with the new property value
338 bool impl_browseForDatabaseDocument_throw( ::com::sun::star::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
340 /** raises a dialog which allows the user to choose a color
341 @param _nColorPropertyId
342 the ID of the color property
343 @param _out_rNewValue
344 the chosen color value
345 @return
346 <TRUE/> if and only if a color was chosen by the user
348 bool impl_dialogColorChooser_throw( sal_Int32 _nColorPropertyId, ::com::sun::star::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
350 /** raises a dialog which allows the user to choose a label control for our component
351 @param _out_rNewValue
352 the chosen label control, if any
353 @return
354 <TRUE/> if and only if a label control was chosen by the user
356 bool impl_dialogChooseLabelControl_nothrow( ::com::sun::star::uno::Any& _out_rNewValue, ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
358 /** raises a dialog which lets the user chose the tab order of controls of a form
359 @precond
360 we have a view control container in which our controls live
361 @return
362 <TRUE/> if and only if the user successfully changed the tab order
363 @seealso impl_getContextControlContainer_nothrow
365 bool impl_dialogChangeTabOrder_nothrow( ::osl::ClearableMutexGuard& _rClearBeforeDialog ) const;
367 /** retrieves the context for controls, whose model(s) we're inspecting
369 If we're inspecting a control model, this is usually part of a set of controls
370 and control models, where the controls live in a certain context (a ->XControlContainer).
371 If we know this context, we can enable additional special functionality.
373 The ->XComponentContext in which we were created is examined for a value
374 named "ControlContext", and this value is returned.
376 ::com::sun::star::uno::Reference< ::com::sun::star::awt::XControlContainer >
377 impl_getContextControlContainer_nothrow() const;
379 /** opens a query design window for interactively designing the SQL command of a
380 database form
381 @param _rxUIUpdate
382 access to the property browser UI
383 @param _nDesignForProperty
384 the ID for the property for which the designer is opened
385 @return
386 <TRUE/> if the window was successfully opened, or was previously open,
387 <FALSE/> otherwise
389 bool impl_doDesignSQLCommand_nothrow(
390 const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >& _rxInspectorUI,
391 PropertyId _nDesignForProperty
394 /** updates a property (UI) whose state depends on more than one other property
396 ->actuatingPropertyChanged is called for certain properties in whose changes
397 we expressed interes (->getActuatingProperty). Now such a property change can
398 result in simple UI updates, for instance another property being enabled or disabled.
400 However, it can also result in a more complex change: The current (UI) state might
401 depend on the value of more than one other property. Those dependent properties (their
402 UI, more precisely) are updated in this method.
404 @param _nPropid
405 the ->PropertyId of the dependent property whose UI state is to be updated
407 @param _rxInspectorUI
408 provides access to the property browser UI. Must not be <NULL/>.
410 void impl_updateDependentProperty_nothrow( PropertyId _nPropId, const ::com::sun::star::uno::Reference< ::com::sun::star::inspection::XObjectInspectorUI >& _rxInspectorUI ) const;
412 /** determines whether the given form has a valid data source signature.
414 Valid here means that the DataSource property denotes an existing data source, and the
415 Command property is not empty. No check is made whether the value of the Command property
416 denotes an existent object, since this would be way too expensive.
418 @param _xFormProperties
419 the form to check. Must not be <NULL/>.
420 @param _bAllowEmptyDataSourceName
421 determine whether an empty data source name is allowed (<TRUE/>), and should not
422 lead to rejection
424 static bool impl_hasValidDataSourceSignature_nothrow(
425 const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _xFormProperties,
426 bool _bAllowEmptyDataSourceName );
428 /** returns the URL of our context document
429 @return
431 OUString impl_getDocumentURL_nothrow() const;
433 private:
434 DECL_LINK( OnDesignerClosed, void* );
436 private:
437 FormComponentPropertyHandler( const FormComponentPropertyHandler& ) SAL_DELETED_FUNCTION;
438 FormComponentPropertyHandler& operator=( const FormComponentPropertyHandler& ) SAL_DELETED_FUNCTION;
440 private:
441 using ::comphelper::OPropertyContainer::addPropertyChangeListener;
442 using ::comphelper::OPropertyContainer::removePropertyChangeListener;
446 //= WaitCursor
448 /** wrapper around a ->WaitObject which can cope with a NULL window
450 class WaitCursor
452 private:
453 ::std::unique_ptr< WaitObject > m_aWaitObject;
455 public:
456 WaitCursor( vcl::Window* _pWindow )
458 if ( _pWindow )
459 m_aWaitObject.reset( new WaitObject( _pWindow ) );
464 } // namespace pcr
467 #endif // INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_FORMCOMPONENTHANDLER_HXX
469 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */