1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 * Copyright 2008 by Sun Microsystems, Inc.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * $RCSfile: formcomponenthandler.hxx,v $
12 * This file is part of OpenOffice.org.
14 * OpenOffice.org is free software: you can redistribute it and/or modify
15 * it under the terms of the GNU Lesser General Public License version 3
16 * only, as published by the Free Software Foundation.
18 * OpenOffice.org is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU Lesser General Public License version 3 for more details
22 * (a copy is included in the LICENSE file that accompanied this code).
24 * You should have received a copy of the GNU Lesser General Public License
25 * version 3 along with OpenOffice.org. If not, see
26 * <http://www.openoffice.org/license.html>
27 * for a copy of the LGPLv3 License.
29 ************************************************************************/
31 #ifndef EXTENSIONS_SOURCE_PROPCTRLR_FORMCOMPONENTHANDLER_HXX
32 #define EXTENSIONS_SOURCE_PROPCTRLR_FORMCOMPONENTHANDLER_HXX
34 #include "propertyhandler.hxx"
35 #include "sqlcommanddesign.hxx"
36 #include "pcrcommon.hxx"
37 #include <comphelper/uno3.hxx>
38 #include <comphelper/proparrhlp.hxx>
39 #include <comphelper/propertycontainer.hxx>
40 /** === begin UNO includes === **/
41 #include <com/sun/star/frame/XModel.hpp>
42 #include <com/sun/star/beans/XPropertyState.hpp>
43 #include <com/sun/star/sdbc/XRowSet.hpp>
44 #include <com/sun/star/awt/XControlContainer.hpp>
45 #include <com/sun/star/form/XForm.hpp>
46 /** === end UNO includes === **/
47 #include <vcl/fldunit.hxx>
48 #include <vcl/waitobj.hxx>
49 #include <connectivity/dbtools.hxx>
53 //........................................................................
56 //........................................................................
58 //====================================================================
59 //= ComponentClassification
60 //====================================================================
61 enum ComponentClassification
68 //====================================================================
69 //= FormComponentPropertyHandler
70 //====================================================================
71 class FormComponentPropertyHandler
;
72 typedef HandlerComponentBase
< FormComponentPropertyHandler
> FormComponentPropertyHandler_Base
;
73 typedef ::comphelper::OPropertyArrayUsageHelper
<FormComponentPropertyHandler
> FormComponentPropertyHandler_PROP
;
74 /** default ->XPropertyHandler for all form components.
76 class FormComponentPropertyHandler
: public FormComponentPropertyHandler_Base
,
77 public ::comphelper::OPropertyContainer
,
78 public FormComponentPropertyHandler_PROP
81 /// access to property states
82 ::com::sun::star::uno::Reference
< ::com::sun::star::beans::XPropertyState
> m_xPropertyState
;
83 /// the parent of our component
84 ::com::sun::star::uno::Reference
< ::com::sun::star::uno::XInterface
> m_xObjectParent
;
86 /// the database connection. Owned by us if and only if we created it ourself.
87 mutable ::dbtools::SharedConnection m_xRowSetConnection
;
88 ::com::sun::star::uno::Reference
< ::com::sun::star::sdbc::XRowSet
> m_xRowSet
;
89 /** helper component encapsulating the handling for the QueryDesign component for
90 interactively designing an SQL command
92 ::rtl::Reference
< SQLCommandDesigner
> m_xCommandDesigner
;
93 ::com::sun::star::uno::Reference
< ::com::sun::star::inspection::XObjectInspectorUI
> m_xBrowserUI
;
95 /// the string indicating a "default" (VOID) value in list-like controls
96 ::rtl::OUString m_sDefaultValueString
;
97 /// all properties to whose control's we added ->m_sDefaultValueString
98 ::std::set
< ::rtl::OUString
> m_aPropertiesWithDefListEntry
;
99 /// type of our component
100 ComponentClassification m_eComponentClass
;
101 /// is our component a (database) sub form?
102 bool m_bComponentIsSubForm
: 1;
103 /// our component has a "ListSource" property
104 bool m_bHaveListSource
: 1;
105 /// our component has a "Command" property
106 bool m_bHaveCommand
: 1;
107 /// the class id of the component - if appliable
108 sal_Int16 m_nClassId
;
111 FormComponentPropertyHandler(
112 const ::com::sun::star::uno::Reference
< ::com::sun::star::uno::XComponentContext
>& _rxContext
115 DECLARE_XINTERFACE( )
118 virtual ::com::sun::star::uno::Reference
< ::com::sun::star::beans::XPropertySetInfo
> SAL_CALL
getPropertySetInfo( ) throw(::com::sun::star::uno::RuntimeException
);
120 static ::rtl::OUString SAL_CALL
getImplementationName_static( ) throw (::com::sun::star::uno::RuntimeException
);
121 static ::com::sun::star::uno::Sequence
< ::rtl::OUString
> SAL_CALL
getSupportedServiceNames_static( ) throw (::com::sun::star::uno::RuntimeException
);
124 ~FormComponentPropertyHandler();
127 virtual ::cppu::IPropertyArrayHelper
* createArrayHelper( ) const;
128 virtual ::cppu::IPropertyArrayHelper
& SAL_CALL
getInfoHelper();
129 // XPropertyHandler overridables
130 virtual ::com::sun::star::uno::Any SAL_CALL
getPropertyValue( const ::rtl::OUString
& _rPropertyName
) throw (::com::sun::star::beans::UnknownPropertyException
, ::com::sun::star::uno::RuntimeException
);
131 virtual void SAL_CALL
setPropertyValue( const ::rtl::OUString
& _rPropertyName
, const ::com::sun::star::uno::Any
& _rValue
) throw (::com::sun::star::beans::UnknownPropertyException
, ::com::sun::star::uno::RuntimeException
);
132 virtual ::com::sun::star::uno::Any SAL_CALL
convertToPropertyValue( const ::rtl::OUString
& _rPropertyName
, const ::com::sun::star::uno::Any
& _rControlValue
) throw (::com::sun::star::beans::UnknownPropertyException
, ::com::sun::star::uno::RuntimeException
);
133 virtual ::com::sun::star::uno::Any SAL_CALL
convertToControlValue( const ::rtl::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
);
134 virtual ::com::sun::star::beans::PropertyState SAL_CALL
getPropertyState( const ::rtl::OUString
& _rPropertyName
) throw (::com::sun::star::beans::UnknownPropertyException
, ::com::sun::star::uno::RuntimeException
);
135 virtual void SAL_CALL
addPropertyChangeListener( const ::com::sun::star::uno::Reference
< ::com::sun::star::beans::XPropertyChangeListener
>& _rxListener
) throw (::com::sun::star::uno::RuntimeException
);
136 virtual void SAL_CALL
removePropertyChangeListener( const ::com::sun::star::uno::Reference
< ::com::sun::star::beans::XPropertyChangeListener
>& _rxListener
) throw (::com::sun::star::uno::RuntimeException
);
137 virtual ::com::sun::star::uno::Sequence
< ::rtl::OUString
> SAL_CALL
getSupersededProperties() throw (::com::sun::star::uno::RuntimeException
);
138 virtual ::com::sun::star::uno::Sequence
< ::rtl::OUString
> SAL_CALL
getActuatingProperties() throw (::com::sun::star::uno::RuntimeException
);
139 virtual ::com::sun::star::inspection::LineDescriptor SAL_CALL
describePropertyLine( const ::rtl::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
);
140 virtual ::com::sun::star::inspection::InteractiveSelectionResult
141 SAL_CALL
onInteractivePropertySelection( const ::rtl::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
);
142 virtual void SAL_CALL
actuatingPropertyChanged( const ::rtl::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
);
143 virtual sal_Bool SAL_CALL
suspend( sal_Bool _bSuspend
) throw (::com::sun::star::uno::RuntimeException
);
146 virtual void SAL_CALL
disposing();
149 virtual ::com::sun::star::uno::Sequence
< ::com::sun::star::beans::Property
>
150 SAL_CALL
doDescribeSupportedProperties() const;
151 virtual void onNewComponent();
154 /** initializes some (cached) meta data about the component
155 @throws RuntimeException
156 if a serious error occurs, for instance if the component does not provide an XPropertySetInfo instance
158 void impl_initComponentMetaData_throw();
160 /** classifies our component, in case it's a control model, by ClassId
162 Note that UNO dialog controls are also classified, though they don't have the ClassId property
164 void impl_classifyControlModel_throw();
166 /** const-version of ->getPropertyValue
168 ::com::sun::star::uno::Any
impl_getPropertyValue_throw( const ::rtl::OUString
& _rPropertyName
) const;
170 // some property values are faked, and not used in the way they're provided by our component
171 void impl_normalizePropertyValue_nothrow( ::com::sun::star::uno::Any
& _rValue
, PropertyId _nPropId
) const;
173 /** determines whether we should exclude a given property from our "supported properties"
175 bool impl_shouldExcludeProperty_nothrow( const ::com::sun::star::beans::Property
& _rProperty
) const;
177 /** initializes the list of field names, if we're handling a control which supports the
180 void impl_initFieldList_nothrow( ::std::vector
< ::rtl::OUString
>& rFieldNames
) const;
182 /** obtaines the RowSet to which our component belongs
184 If the component is a RowSet itself, it's returned directly. Else, the parent
185 is examined for the XRowSet interface. If the parent is no XRowSet, then
186 a check is made whether our component is a grid control column, and if so,
187 the parent of the grid control is examied for the XRowSet interace.
189 Normally, at least one of those methods should succeed.
191 ::com::sun::star::uno::Reference
< ::com::sun::star::sdbc::XRowSet
> impl_getRowSet_throw( ) const;
193 /** nothrow-version of ->impl_getRowSet_throw
195 ::com::sun::star::uno::Reference
< ::com::sun::star::sdbc::XRowSet
> impl_getRowSet_nothrow( ) const;
197 /** connects the row set belonging to our introspected data aware form component,
198 and remembers the connection in ->m_xRowSetConnection.
200 If the row set already is connected, ->m_xRowSetConnection will be set, too, but
201 not take the ownership of the connection.
203 If ->m_xRowSetConnection is already set, nothing happens, so if you want to
204 force creation of a connection, you need to clear ->m_xRowSetConnection.
206 bool impl_ensureRowsetConnection_nothrow() const;
208 /** clears ->m_xRowSetConnection
210 void impl_clearRowsetConnection_nothrow();
212 /** fills an ->LineDescriptor with information to represent a cursor source
213 of our form - that is, a table, a query, or an SQL statement.
215 As an example, if our form has currently a CommandType of TABLE, then the
216 value list in the LineDescriptor will contain a list of all tables
217 of the data source which the form is bound to.
219 @seealso impl_fillTableNames_throw
220 @seealso impl_fillQueryNames_throw
222 void impl_describeCursorSource_nothrow(
223 ::com::sun::star::inspection::LineDescriptor
& _out_rProperty
,
224 const ::com::sun::star::uno::Reference
< ::com::sun::star::inspection::XPropertyControlFactory
>& _rxControlFactory
227 /** describes the UI for selecting a table name
230 m_xRowSetConnection is not <NULL/>
232 void impl_fillTableNames_throw( ::std::vector
< ::rtl::OUString
>& _out_rNames
) const;
234 /** describes the UI for selecting a query name
237 m_xRowSetConnection is not <NULL/>
239 void impl_fillQueryNames_throw( ::std::vector
< ::rtl::OUString
>& _out_rNames
) const;
241 /** describes the UI for selecting a ListSource (for list-like form controls)
243 ->m_xRowSetConnection is not <NULL/>
245 ->m_xComponent is not <NULL/>
247 void impl_describeListSourceUI_throw(
248 ::com::sun::star::inspection::LineDescriptor
& _out_rDescriptor
,
249 const ::com::sun::star::uno::Reference
< ::com::sun::star::inspection::XPropertyControlFactory
>& _rxControlFactory
252 /** displays a datbase-related error to the user
254 void impl_displaySQLError_nothrow( const ::dbtools::SQLExceptionInfo
& _rErrorDescriptor
) const;
256 /** let's the user chose a selection of entries from a string list, and stores this
257 selection in the given property
259 <TRUE/> if and only if the user successfully changed the property
261 bool impl_dialogListSelection_nothrow( const ::rtl::OUString
& _rProperty
, ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
263 /** executes a dialog for chosing a filter or sort criterion for a database form
265 <TRUE/> if the Filter property should be used, <FALSE/> if it's the Order
267 @param _out_rSelectedClause
268 the filter or order clause as chosen by the user
270 we're really inspecting a database form (well, a RowSet at least)
272 <TRUE/> if and only if the user successfully chose a clause
274 bool impl_dialogFilterOrSort_nothrow( bool _bFilter
, ::rtl::OUString
& _out_rSelectedClause
, ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
276 /** executes a dialog which allows the user to chose the columns linking
277 a sub to a master form, and sets the respective MasterFields / SlaveFields
278 properties at the form.
280 we're inspecting (sub) database form
282 <TRUE/> if and only if the user successfully eneter master and slave fields
284 bool impl_dialogLinkedFormFields_nothrow( ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
286 /** executes a dialog which allows the user to modify the FormatKey
287 property of our component, by chosing a (number) format.
289 Our component actually has a FormatKey property.
290 @param _out_rNewValue
291 the new property value, if the user chose a new formatting
293 <TRUE/> if and only if a new formatting has been chosen by the user.
294 In this case, ->_out_rNewValue is filled with the new property value
296 bool impl_dialogFormatting_nothrow( ::com::sun::star::uno::Any
& _out_rNewValue
, ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
298 /** executes a dialog which allows to the user to change the ImageURL property
299 of our component by browsing for an image file.
301 our component actually has a ImageURL property
302 @param _out_rNewValue
303 the new property value, if the user chose a new image url
305 <TRUE/> if and only if a new image URL has been chosen by the user.
306 In this case, ->_out_rNewValue is filled with the new property value
308 bool impl_browseForImage_nothrow( ::com::sun::star::uno::Any
& _out_rNewValue
, ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
310 /** executes a dialog which allows the user to change the TargetURL property of
313 our component actually has a TargetURL property
314 @param _out_rNewValue
315 the new property value, if the user chose a new TargetURL
317 <TRUE/> if and only if a new TargetURL has been chosen by the user.
318 In this case, ->_out_rNewValue is filled with the new property value
320 bool impl_browseForTargetURL_nothrow( ::com::sun::star::uno::Any
& _out_rNewValue
, ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
322 /** executes a dialog which allows the user to change the font, plus related properties,
325 our component actually has a Font property
326 @param _out_rNewValue
327 a value desribing the new font, as <code>Sequence< NamedValue ></code>
329 <TRUE/> if and only if the user successfully changed the font of our component
331 bool impl_executeFontDialog_nothrow( ::com::sun::star::uno::Any
& _out_rNewValue
, ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
333 /** allows the user browsing for a database document
335 our component actually has a DataSource property
336 @param _out_rNewValue
337 the new property value, if the user chose a new DataSource
339 <TRUE/> if and only if a new DataSource has been chosen by the user.
340 In this case, ->_out_rNewValue is filled with the new property value
342 bool impl_browseForDatabaseDocument_throw( ::com::sun::star::uno::Any
& _out_rNewValue
, ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
344 /** raises a dialog which allows the user to choose a color
345 @param _nColorPropertyId
346 the ID of the color property
347 @param _out_rNewValue
348 the chosen color value
350 <TRUE/> if and only if a color was chosen by the user
352 bool impl_dialogColorChooser_throw( sal_Int32 _nColorPropertyId
, ::com::sun::star::uno::Any
& _out_rNewValue
, ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
354 /** raises a dialog which allows the user to choose a label control for our component
355 @param _out_rNewValue
356 the chosen label control, if any
358 <TRUE/> if and only if a label control was chosen by the user
360 bool impl_dialogChooseLabelControl_nothrow( ::com::sun::star::uno::Any
& _out_rNewValue
, ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
362 /** raises a dialog which lets the user chose the tab order of controls of a form
364 we have a view control container in which our controls live
366 <TRUE/> if and only if the user successfully changed the tab order
367 @seealso impl_getContextControlContainer_nothrow
369 bool impl_dialogChangeTabOrder_nothrow( ::osl::ClearableMutexGuard
& _rClearBeforeDialog
) const;
371 /** retrieves the context for controls, whose model(s) we're inspecting
373 If we're inspecting a control model, this is usually part of a set of controls
374 and control models, where the controls live in a certain context (a ->XControlContainer).
375 If we know this context, we can enable additional special functionality.
377 The ->XComponentContext in which we were created is examined for a value
378 named "ControlContext", and this value is returned.
380 ::com::sun::star::uno::Reference
< ::com::sun::star::awt::XControlContainer
>
381 impl_getContextControlContainer_nothrow() const;
383 /** opens a query design window for interactively designing the SQL command of a
386 access to the property browser UI
387 @param _nDesignForProperty
388 the ID for the property for which the designer is opened
390 <TRUE/> if the window was successfully opened, or was previously open,
393 bool impl_doDesignSQLCommand_nothrow(
394 const ::com::sun::star::uno::Reference
< ::com::sun::star::inspection::XObjectInspectorUI
>& _rxInspectorUI
,
395 PropertyId _nDesignForProperty
398 /** updates a property (UI) whose state depends on more than one other property
400 ->actuatingPropertyChanged is called for certain properties in whose changes
401 we expressed interes (->getActuatingProperty). Now such a property change can
402 result in simple UI updates, for instance another property being enabled or disabled.
404 However, it can also result in a more complex change: The current (UI) state might
405 depend on the value of more than one other property. Those dependent properties (their
406 UI, more precisly) are updated in this method.
409 the ->PropertyId of the dependent property whose UI state is to be updated
411 @param _rxInspectorUI
412 provides access to the property browser UI. Must not be <NULL/>.
414 void impl_updateDependentProperty_nothrow( PropertyId _nPropId
, const ::com::sun::star::uno::Reference
< ::com::sun::star::inspection::XObjectInspectorUI
>& _rxInspectorUI
) const;
416 /** determines whether the given form has a valid data source signature.
418 Valid here means that the DataSource property denotes an existing data source, and the
419 Command property is not empty. No check is made whether the value of the Command property
420 denotes an existent object, since this would be way too expensive.
422 @param _xFormProperties
423 the form to check. Must not be <NULL/>.
424 @param _bAllowEmptyDataSourceName
425 determine whether an empty data source name is allowed (<TRUE/>), and should not
428 static bool impl_hasValidDataSourceSignature_nothrow(
429 const ::com::sun::star::uno::Reference
< ::com::sun::star::beans::XPropertySet
>& _xFormProperties
,
430 bool _bAllowEmptyDataSourceName
);
432 /** returns the URL of our context document
435 ::rtl::OUString
impl_getDocumentURL_nothrow() const;
438 DECL_LINK( OnDesignerClosed
, void* );
441 FormComponentPropertyHandler(); // never implemented
442 FormComponentPropertyHandler( const FormComponentPropertyHandler
& ); // never implemented
443 FormComponentPropertyHandler
& operator=( const FormComponentPropertyHandler
& ); // never implemented
446 using ::comphelper::OPropertyContainer::addPropertyChangeListener
;
447 using ::comphelper::OPropertyContainer::removePropertyChangeListener
;
450 //====================================================================
452 //====================================================================
453 /** wrapper around a ->WaitObject which can cope with a NULL window
458 ::std::auto_ptr
< WaitObject
> m_aWaitObject
;
461 WaitCursor( Window
* _pWindow
)
464 m_aWaitObject
.reset( new WaitObject( _pWindow
) );
468 //........................................................................
470 //........................................................................
472 #endif // EXTENSIONS_SOURCE_PROPCTRLR_FORMCOMPONENTHANDLER_HXX