diff options
Diffstat (limited to 'offapi/com/sun/star/inspection')
22 files changed, 2625 insertions, 0 deletions
diff --git a/offapi/com/sun/star/inspection/DefaultHelpProvider.idl b/offapi/com/sun/star/inspection/DefaultHelpProvider.idl new file mode 100644 index 000000000000..900610538b35 --- /dev/null +++ b/offapi/com/sun/star/inspection/DefaultHelpProvider.idl @@ -0,0 +1,71 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __com_sun_star_inspection_DefaultHelpProvider_idl__ +#define __com_sun_star_inspection_DefaultHelpProvider_idl__ + +#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ +#include <com/sun/star/lang/IllegalArgumentException.idl> +#endif + +//============================================================================= + +module com { module sun { module star { module inspection { + +interface XObjectInspectorUI; + +//============================================================================= + +/** implements a component which can default-fill the help section of an + <type>ObjectInspector</type>. + + <p>The component registers a <type>XPropertyControlObserver</type> at an + <type>XObjectInspectoryUI</type> interface. Whenever it then is notified + of a <type>XPropertyControl</type> getting the focus, it will try to deduce + the extended help text of this control's window, and set this help text at the + object inspector's help section.</p> + */ +service DefaultHelpProvider : com::sun::star::uno::XInterface +{ + /** creates a help provider instance + @param InspectorUI + provides access to the UI of the ObjectInspector which should be + observed. Must not be <NULL/>. + @throws ::com::sun::star::lang::IllegalArgumentException + if the given inspector UI is <NULL/>. + */ + create( [in] XObjectInspectorUI InspectorUI ) + raises ( ::com::sun::star::lang::IllegalArgumentException ); +}; + +//============================================================================= + +}; }; }; }; + +//============================================================================= + +#endif + diff --git a/offapi/com/sun/star/inspection/GenericPropertyHandler.idl b/offapi/com/sun/star/inspection/GenericPropertyHandler.idl new file mode 100644 index 000000000000..c93f7a958ba5 --- /dev/null +++ b/offapi/com/sun/star/inspection/GenericPropertyHandler.idl @@ -0,0 +1,63 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_GenericPropertyHandler_idl__ +#define __com_sun_star_inspection_GenericPropertyHandler_idl__ + +#ifndef __com_sun_star_inspection_XPropertyHandler_idl__ +#include <com/sun/star/inspection/XPropertyHandler.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** implements a general-purpose XPropertyHandler + + <p>The property handler implemented by this service will do an introspection + on the provided components, and expose the properties obtained via + XIntrospectionAccess::getProperties.</p> + + <p>The handler will automatically determine the best type of property control + to represent a certain property, depending on the property type. This includes, + for example, list box controls to represent enumeration properties.</p> + + @see XPropertyHandler + @see scom::sun::star::beans::XIntrospectionAccess + @see XPropertyControl + + @since OOo 2.0.3 +*/ +service GenericPropertyHandler : XPropertyHandler; + +//============================================================================= + +}; }; }; }; + +#endif + + diff --git a/offapi/com/sun/star/inspection/InteractiveSelectionResult.idl b/offapi/com/sun/star/inspection/InteractiveSelectionResult.idl new file mode 100644 index 000000000000..0447da8ed4ab --- /dev/null +++ b/offapi/com/sun/star/inspection/InteractiveSelectionResult.idl @@ -0,0 +1,76 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __com_sun_star_inspection_InteractiveSelectionResult_idl__ +#define __com_sun_star_inspection_InteractiveSelectionResult_idl__ + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** describes possible results of an interactive selection of a property value + in an object inspector + + @see XPropertyHandler::onInteractivePropertySelection + + @since OOo 2.0.3 +*/ +enum InteractiveSelectionResult +{ + /** The interactive selection of a property value was cancelled. + */ + Cancelled, + + /** The interactive selection of a property value succeeded, and the + new property value chosen by the user has already been set at the + inspected component. + */ + Success, + + /** The interactive selection of a property value succeeded, a new + property value has been obtained, but not yet set at the inspected + component. + + <p>In this case, the obtained value is passed to the caller of + <member>XPropertyHandler::onInteractivePropertySelection<member>, which is + responsible for forwarding this value to the inspected component.</p> + */ + ObtainedValue, + + /** The interactive selection of a property value is still pending. + + <p>This is usually used when this selection involves non-modal user interface.</p> + */ + Pending +}; + +//============================================================================= + +}; }; }; }; + +#endif + + diff --git a/offapi/com/sun/star/inspection/LineDescriptor.idl b/offapi/com/sun/star/inspection/LineDescriptor.idl new file mode 100644 index 000000000000..5bf9486f82ee --- /dev/null +++ b/offapi/com/sun/star/inspection/LineDescriptor.idl @@ -0,0 +1,201 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_LineDescriptor_idl__ +#define __com_sun_star_inspection_LineDescriptor_idl__ + +#ifndef com_sun_star_graphic_XGraphic_idl +#include <com/sun/star/graphic/XGraphic.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +interface XPropertyControl; + +//----------------------------------------------------------------------------- +/** describes the appearance of a line representing a single property in an <type>ObjectInspector</type>. + + Such a line consists of + <ul><li>a label with a human-readable name for the property</li> + <li>a control which is used for user interaction - i.e. it displays the current property + value, and allows the user entering a new one.</li> + <li>(optional) one or two buttons which, when clicked, can start a more complex, interactive + property value input. For instance, if you have a property whose value is a path in the + file system, such a button could be used to let the user browse for a path with a + usual file picker.</li> + </ul> + + @see XPropertyHandler::describePropertyLine + @see PropertyLineElement + + @since OOo 2.0.3 +*/ +struct LineDescriptor +{ + /** denotes the human-readable display name used to present a property to the user + */ + string DisplayName; + + /** denotes the control which should be used to represent the property at the UI. + + @see XPropertyControlFactory + */ + XPropertyControl Control; + + /** specifies the URL to the help topic to be associated with the property + */ + string HelpURL; + + /** detetrmines whether a button exists which can be used for a more complex, interactive + property value input. + + <p>If no image for the primary button is specified, but a primary button is present, + the three dots will be displayed on the button.</p> + + @see XPropertyHandler::onInteractivePropertySelection + @see HasSecondaryButton + @see PrimaryButtonImageURL + @see PrimaryButtonImage + */ + boolean HasPrimaryButton; + + /** describes a unique id to associate with the primary button + + <p>In OpenOffice.org, UI elements sometimes require a so-called UniqueID, which can be + used to uniquely (within the whole application) identify this UI element. For instance, + automating the OpenOffice.org UI via a dedicated separate application ("TestTool") requires + such IDs.</p> + + <p>If a primary button exists for a property's UI representation (<member>HasPrimaryButton</member>), + it gets the ID specified herein.</p> + */ + long PrimaryButtonId; + + /** describes the URL of an image to display on the primary button, if any. + + <p>This URL will be used to obtain an actual <type scope="com::sun::star::graphic">XGraphic</type> + object from an <type scope="com::sun::star::graphic">GraphicProvider</type>.</p> + + <p>The property will be ignored if <member>HasPrimaryButton</member> is <FALSE/>.</p> + + <p>If you need to specify a graphic which does not have an URL, but is available as + <type scope="com::sun::star::graphic">XGraphic</type> only, then you must leave + <code>PrimaryButtonImageURL</code> empty, and use the <member>PrimaryButtonImage</member> property. + + @see PrimaryButtonImage + */ + string PrimaryButtonImageURL; + + /** describes a graphics to display at the primary button, if any. + + <p>The property will be ignored if <member>HasPrimaryButton</member> is <FALSE/>, or + if <member>PrimaryButtonImageURL</member> is a non-empty string.</p> + + @see HasPrimaryButton + @see PrimaryButtonImageURL + */ + com::sun::star::graphic::XGraphic PrimaryButtonImage; + + /** detetrmines whether a secondary button exists which can be used for a more complex, interactive + property value input. + + <p>A secondary button subordinated to the primary button. If no primary button exists + (<member>HasPrimaryButton</member>), this member is ignored.</p> + + @see XPropertyHandler::onInteractivePropertySelection + @see HasSecondaryButton + */ + boolean HasSecondaryButton; + + /** describes a unique id to associate with the primary button + + <p>If a secondary button exists for a property's UI representation (<member>HasSecondaryButton</member>), + it gets the ID specified herein.</p> + + @see PrimaryButtonId + */ + long SecondaryButtonId; + + /** describes the URL of an image to display on the secondary button, if any. + + <p>This URL will be used to obtain an actual <type scope="com::sun::star::graphic">XGraphic</type> + object from an <type scope="com::sun::star::graphic">GraphicProvider</type>.</p> + + <p>The property will be ignored if <member>HasSecondaryButton</member> is <FALSE/>.</p> + + <p>If you need to specify a graphic which does not have an URL, but is available as + <type scope="com::sun::star::graphic">XGraphic</type> only, then you must leave + <code>SecondaryButtonImageURL</code> empty, and use the <member>SecondaryButtonImage</member> property. + + @see SecondaryButtonImage + */ + string SecondaryButtonImageURL; + + /** describes a graphics to display at the secondary button, if any. + + <p>The property will be ignored if <member>HasSecondaryButton</member> is <FALSE/>, or + if <member>SecondaryButtonImageURL</member> is a non-empty string.</p> + + @see HasSecondaryButton + @see SecondaryButtonImageURL + */ + com::sun::star::graphic::XGraphic SecondaryButtonImage; + + /** describes the indent level for the property + + <p>If a given property semantically depends on another one, the indent level + can be used to visually represent this fact. For this, the dependent property's + indent level would be one larger than the indent level of the other property.</p> + + <p>Normally, <type>XPropertyHandler</type>s will set this to <code>0</code> when describing + the UI for a normal property. + */ + short IndentLevel; + + /** describes the category into which the property should be sorted by the <type>ObjectInspector</type>. + + <p>An <type>ObjectInspector</type> can visually group properties which semantically belong + together (for instance using tab pages). The decision which properties actually belong together + is made using this <member>Category</member> attribute.</p> + + <p>For your implementation of <type>XPropertyHandler</type>, it's recommended that you document the programmatic + names used for property categories. This way, your handler might be re-used in + different contexts, where only the <type>XObjectInspectorModel</type> needs to provide consistent + UI names for the categories.</p> + + @see XObjectInspectorModel::describeCategories + */ + string Category; +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/ObjectInspector.idl b/offapi/com/sun/star/inspection/ObjectInspector.idl new file mode 100644 index 000000000000..9a0386bee9f0 --- /dev/null +++ b/offapi/com/sun/star/inspection/ObjectInspector.idl @@ -0,0 +1,111 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __com_sun_star_inspection_ObjectInspector_idl__ +#define __com_sun_star_inspection_ObjectInspector_idl__ + +#ifndef __com_sun_star_inspection_XObjectInspector_idl__ +#include <com/sun/star/inspection/XObjectInspector.idl> +#endif + +#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ +#include <com/sun/star/lang/IllegalArgumentException.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** describes an <type scope="com::sun::star::frame">Controller</type> which can be used to + browse and modify properties of components. + + <p>The controller can be plugged into an <type scope="com::sun::star::frame">XFrame</type>, and will + provide a visual component for inspecting and modifying component properties.<br/> + Note that "property" here is a generic term - any aspect of a component can be considered a property, + as long as some property handler is able to describe this aspect in a property-like way.</p> + + <p>The basic idea is that one facet of the inspected component is represented by a single line + of controls: A label, an input control, and optionally one or two buttons which, when pressed, + trigger additional user interaction (e.g. a more sophisticated dialog to enter a property value).</p> + + <p>Additionally, property lines can be grouped into different categories. A usual implementation + of such categories would be tab pages, but other implementations are possible, too.</p> + + <p>Even more, the inspector can optionally display a help section at the bottom of its + window, which can display arbitrary (context-sensitive) help texts.</p> + + <p>An <type>ObjectInspector</type> needs one or more property handlers which describe + the facets of an inspected component - without such handlers, the inspector window will simply + stay empty.</p> + + <p>The property handlers, as well as more information about the layout of the inspector, + are provided by a inspector model, which has to be implemented by the user of the inspector.</p> + <p/> + + <p>Since property handlers might have the need to raise UI, they will be created with a context + value named "DialogParentWindow", which contains an XWindow which should be used as parent of + any windows to raise.<br/> + If the <type scope="com::sun::star::uno">XComponentContext</type> in which the <type>ObjectInspector</type> + was created already contains such a value, it is not overwritten. Only if it doesn't, the inspector + will add an own value - which contains the inspector's main window - to the context when creating + handlers.</p> + + @see XPropertyHandler + @see LineDescriptor + @see PropertyControlType + @see ObjectInspectorModel + @see com::sun::star::uno::XComponentContext + @see com::sun::star::lang::XMultiComponentFactory + + @since OOo 2.0.3 +*/ +service ObjectInspector : XObjectInspector +{ + /** creates a default instance of the ObjectInspector + + @since OOo 2.2 + */ + createDefault(); + + /** creates an instance of the ObjectInspector, using a given <type>ObjectInspectorModel</type> + + @throws ::com::sun::star::lang::IllegalArgumentException + if <arg>Model</arg> is <NULL/>. + + @since OOo 2.2 + */ + createWithModel( [in] XObjectInspectorModel Model ) + raises ( ::com::sun::star::lang::IllegalArgumentException ); +}; + +//============================================================================= + +}; }; }; }; + +#endif + + + diff --git a/offapi/com/sun/star/inspection/ObjectInspectorModel.idl b/offapi/com/sun/star/inspection/ObjectInspectorModel.idl new file mode 100644 index 000000000000..00a55a0b43c3 --- /dev/null +++ b/offapi/com/sun/star/inspection/ObjectInspectorModel.idl @@ -0,0 +1,121 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_ObjectInspectorModel_idl__ +#define __com_sun_star_inspection_ObjectInspectorModel_idl__ + +#ifndef __com_sun_star_inspection_XObjectInspectorModel_idl__ +#include <com/sun/star/inspection/XObjectInspectorModel.idl> +#endif + +#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ +#include <com/sun/star/lang/IllegalArgumentException.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** describes a default implementation of an ObjectInspectorModel + + <p>This service simplifies usage of an <type>ObjectInspector</type>.</p> + + <p>The <type>XObjectInspectorModel</type> implemented by this service will not provide any property + categories, nor apply any particular order to the properties provided by its handler(s).</p> + + @see ObjectInspector + @see XObjectInspectorModel + @see XObjectInspectorModel::describeCategories + @see XObjectInspectorModel::getPropertyOrderIndex + + @since OOo 2.0.3 +*/ +service ObjectInspectorModel : XObjectInspectorModel +{ + /** creates a default ObjectInspectorModel, whose one and only handler factory + creates a <type>GenericPropertyHandler</type>. + */ + createDefault(); + + /** creates a default ObjectInspectorModel, using an externally provided sequence of property handler + factories. + + @param handlerFactories + a sequence of handler factories, as to be provided in the XObjectInspectorModel::HandlerFactories + method. + @throws ::com::sun::star::lang::IllegalArgumentException + if the given sequence is empty. + + @see XObjectInspectorModel::HandlerFactories + */ + createWithHandlerFactories( [in] sequence< any > handlerFactories ) + raises ( ::com::sun::star::lang::IllegalArgumentException ); + + /** creates a default ObjectInspectorModel, using an externally provided sequence of property handler + factories, and describing an ObjectInspector which has a help section. + + @param handlerFactories + a sequence of handler factories, as to be provided in the XObjectInspectorModel::HandlerFactories + method. + + @param minHelpTextLines + denotes the minimum number of lines of text to be reserved for the help + section. + + @param maxHelpTextLines + denotes the maximum number of lines of text to be reserved for the help + section. + + @throws ::com::sun::star::lang::IllegalArgumentException + if <arg>handlerFactories</arg> is empty. + + @throws ::com::sun::star::lang::IllegalArgumentException + if <arg>minHelpTextLines</arg> or <arg>maxHelpTextLines</arg> are negative, + or if <arg>minHelpTextLines</arg> is greater than <arg>maxHelpTextLines</arg>. + + @see XObjectInspectorModel::HandlerFactories + @see XObjectInspectorModel::HasHelpSection + @see XObjectInspectorModel::MinHelpTextLines + @see XObjectInspectorModel::MaxHelpTextLines + + @since OOo 2.2 + */ + createWithHandlerFactoriesAndHelpSection( + [in] sequence< any > handlerFactories, + [in] long minHelpTextLines, + [in] long maxHelpTextLines + ) + raises ( ::com::sun::star::lang::IllegalArgumentException ); +}; + +//============================================================================= + +}; }; }; }; + +#endif + + diff --git a/offapi/com/sun/star/inspection/PropertyCategoryDescriptor.idl b/offapi/com/sun/star/inspection/PropertyCategoryDescriptor.idl new file mode 100644 index 000000000000..5e58701e3c03 --- /dev/null +++ b/offapi/com/sun/star/inspection/PropertyCategoryDescriptor.idl @@ -0,0 +1,67 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __com_sun_star_inspection_PropertyCategoryDescriptor_idl__ +#define __com_sun_star_inspection_PropertyCategoryDescriptor_idl__ + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** describes a category of properties + @see ObjectInspector + @see XObjectInspectorModel::describeCategory + @see LineDescriptor::Category + + @since OOo 2.0.3 +*/ +struct PropertyCategoryDescriptor +{ + /** contains the programmatic name of the category. + + <p>This programmatic name is used internally: <member>XPropertyHandler::describePropertyLine</member> + sets a programmatic category name at <member>LineDescriptor::Category</member>, + and an object inspector uses this to find the proper <type>PropertyCategoryDescriptor</type>.</p> + */ + string ProgrammaticName; + + /** provides a human-readable name (which can be presented at the UI) for a category. + */ + string UIName; + + /** provides a help URL to be associated with a category + */ + string HelpURL; +}; + +//============================================================================= + +}; }; }; }; + +#endif + + + diff --git a/offapi/com/sun/star/inspection/PropertyControlType.idl b/offapi/com/sun/star/inspection/PropertyControlType.idl new file mode 100644 index 000000000000..1f61dfe6ed97 --- /dev/null +++ b/offapi/com/sun/star/inspection/PropertyControlType.idl @@ -0,0 +1,153 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_PropertyControlType_idl__ +#define __com_sun_star_inspection_PropertyControlType_idl__ + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** describes pre-defined possible control types to be used to display and enter + property values within a <type>ObjectInspector</type>. + + <p>The type of a control determines its visual appearance, its behaviour, and - important + for property handlers using a control - the expected type when reading and writing the + control's value.</p> + + @see XPropertyControl + @see XPropertyControlFactory + @see XPropertyControl::ValueType + + @since OOo 2.0.3 +*/ +constants PropertyControlType +{ + /** denotes a control which allows the user to choose from a list of + possible property values + + <p>Controls of type <member>ListBox</member> exchange their values as <code>string</code>.</p> + + <p>Additionally, those controls support the <type>XStringListControl</type> interface.</p> + */ + const short ListBox = 1; + + /** denotes a control which allows the user to choose from a list of + possible property values, combined with the possibility to enter a new + property value. + + <p>Controls of type <member>ComboBox</member> exchange their values as <code>string</code>.</p> + + <p>Additionally, those controls support the <type>XStringListControl</type> interface.</p> + */ + const short ComboBox = 2; + + /** denotes a control which allows the user to enter property values consisting of a single line of text + + <p>Controls of type <member>TextField</member> exchange their values as <code>string</code>.</p> + */ + const short TextField = 3; + + /** denotes a control which allows the user to enter pure text, including line breaks + + <p>Controls of type <member>MultiLineTextField</member> exchange their values as <code>string</code>.</p> + */ + const short MultiLineTextField = 4; + + /** denotes a control which allows the user to enter a single character + + <p>Controls of type <member>CharacterField</member> exchange their values as <code>short</code>, + being a single UTF-16 character.</p> + */ + const short CharacterField = 5; + + /** denotes a control which allows the user to enter a list of single-line strings + + <p>Controls of type <member>StringListField</member> exchange their values as <code>sequence< string ><code>.</p> + */ + const short StringListField = 6; + + /** denotes a control which allows the user to choose from a list of colors. + + <p>Controls of type <member>ColorListBox</member> usually exchange their values as + <type scope="com::sun::star::util">Color</type>.</p> + + <p>Additionally, those controls support the <type>XStringListControl</type> interface. If you use + this interface to add additional entries to the list box, which have no color associated with it, + then you can also exchange values as <code>string</code>. That is, if you write a string into + <member>XPropertyControl::Value</member>, and if this string has previously been added to the list + using the <type>XStringListControl</type> interface, this string is selected. Vice versa, if the user + selects one of those non-color strings in the list, then reading <member>XPropertyControl::Value</member> + will retrieve you this stting.</p> + */ + const short ColorListBox = 7; + + /** denotes a control which allows the user to enter a numerical value + + <p>Controls of type <member>NumericField</member> exchange their values as <code>double</code>.</p> + + <p>Additionally, those controls support the <type>XNumericControl</type> interface.</p> + */ + const short NumericField = 8; + + /** denotes a control which allows the user to enter a date value + + <p>Controls of type <member>DateField</member> exchange their values as <type scope="com::sun::star::util">Date</type>.</p> + */ + const short DateField = 9; + + /** denotes a control which allows the user to enter a time value + + <p>Controls of type <member>TimeField</member> exchange their values as <type scope="com::sun::star::util">Time</type>.</p> + */ + const short TimeField = 10; + + /** denotes a control which allows the user to enter a combined date/time value + + <p>Controls of type <member>DateTimeField</member> exchange their values as <type scope="com::sun::star::util">DateTime</type>.</p> + */ + const short DateTimeField = 11; + + /** denotes a control which displays a string in a hyperlink-like appearance + + <p>Controls of type <member>HyperlinkField</member> exchange their values as <code>string</code>.</p> + + <p>Additionally, those controls support the <type>XHyperlinkControl</type> interface.</p> + */ + const short HyperlinkField = 12; + + /** denotes a non-standard property control, which is usually provided by an <type>XPropertyHandler</type> + */ + const short Unknown = 13; +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/PropertyLineElement.idl b/offapi/com/sun/star/inspection/PropertyLineElement.idl new file mode 100644 index 000000000000..35d7c47e7a17 --- /dev/null +++ b/offapi/com/sun/star/inspection/PropertyLineElement.idl @@ -0,0 +1,61 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_PropertyLineElement_idl__ +#define __com_sun_star_inspection_PropertyLineElement_idl__ + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** describes elements of a single line in an object inspector, used to represent a + single property + + @see XPropertyHandler::describePropertyLine + @see LineDescriptor + + @since OOo 2.0.3 +*/ +constants PropertyLineElement +{ + /// specifies the input control in a group of controls related to a single property + const short InputControl = 0x01; + /// specifies the primary button (if present) in a group of controls related to a single property + const short PrimaryButton = 0x02; + /// specifies the secondary button (if present) in a group of controls related to a single property + const short SecondaryButton = 0x04; + + /// specifies all elements + const short All = 0xFF; +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/XHyperlinkControl.idl b/offapi/com/sun/star/inspection/XHyperlinkControl.idl new file mode 100644 index 000000000000..f6daa5f8c179 --- /dev/null +++ b/offapi/com/sun/star/inspection/XHyperlinkControl.idl @@ -0,0 +1,69 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XHyperlinkControl_idl__ +#define __com_sun_star_inspection_XHyperlinkControl_idl__ + +#ifndef __com_sun_star_inspection_XPropertyControl_idl__ +#include <com/sun/star/inspection/XPropertyControl.idl> +#endif +#ifndef __com_sun_star_awt_XActionListener_idl__ +#include <com/sun/star/awt/XActionListener.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** defines the interface for an <type>XPropertyControl</type> which displays its value + in a hyperlink-like way + + <p>Hyperlink controls exchange their value (<member>XPropertyControl::Value</member>) as strings.</p> + + @since OOo 2.0.3 +*/ +interface XHyperlinkControl : XPropertyControl +{ + /** adds a listener which will be notified when the user clicked the hyperlink text in the control + @param listener + the listener to notify of hyperlink clicks + */ + void addActionListener( [in] com::sun::star::awt::XActionListener listener ); + + /** removes a listener which was previously added via <member>addActionListener</member> + @param listener + the listener to revoke + */ + void removeActionListener( [in] com::sun::star::awt::XActionListener listener ); +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/XNumericControl.idl b/offapi/com/sun/star/inspection/XNumericControl.idl new file mode 100644 index 000000000000..13e4631a3959 --- /dev/null +++ b/offapi/com/sun/star/inspection/XNumericControl.idl @@ -0,0 +1,98 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XNumericControl_idl__ +#define __com_sun_star_inspection_XNumericControl_idl__ + +#ifndef __com_sun_star_inspection_XPropertyControl_idl__ +#include <com/sun/star/inspection/XPropertyControl.idl> +#endif +#ifndef __com_sun_star_beans_Optional_idl__ +#include <com/sun/star/beans/Optional.idl> +#endif +#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ +#include <com/sun/star/lang/IllegalArgumentException.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** defines the interface for an <type>XPropertyControl</type> which supports + displaying and entering numerical values. + + @since OOo 2.0.3 +*/ +interface XNumericControl : XPropertyControl +{ + /** describes the number of decimal digits to use for the value + */ + [attribute] short DecimalDigits; + + /** describes the minimum value which is allowed to be entered in the control + */ + [attribute] com::sun::star::beans::Optional<double> MinValue; + + /** describes the maximum value which is allowed to be entered in the control + */ + [attribute] com::sun::star::beans::Optional<double> MaxValue; + + /** describes a <type scope="com::sun::star::util">MeasureUnit</type> to be applied + for displaying values. + + <p>Only a certain set of <type scope="com::sun::star::util">MeasureUnit</type> values is + supported. In particular, every value which denotes a fraction of another + unit (like 100th millimiters) cannot be used as DisplayUnit.</p> + + @throws com::sun::star::lang::IllegalArgumentException + if the caller attempts to set an unsupported <type scope="com::sun::star::util">MeasureUnit</type> + */ + [attribute] short DisplayUnit + { + set raises (com::sun::star::lang::IllegalArgumentException); + }; + + /** describes a <type scope="com::sun::star::util">MeasureUnit</type> to be + applied for transfering values. + + <p>The core measurement unit for a property value might differ from the unit which + is used by the control to display it. For instance, your property value might require + that your values denote 100th millimeters, but to the user, you want to present the + value as, say, inches. In this case, a numeric control can automatically handle the + value conversion for you, if you give it a ValueUnit different from the DisplayUnit.</p> + + @see XPropertyControl::Value + */ + [attribute] short ValueUnit; +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/XObjectInspector.idl b/offapi/com/sun/star/inspection/XObjectInspector.idl new file mode 100644 index 000000000000..664221ff03fd --- /dev/null +++ b/offapi/com/sun/star/inspection/XObjectInspector.idl @@ -0,0 +1,133 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XObjectInspector_idl__ +#define __com_sun_star_inspection_XObjectInspector_idl__ + +#ifndef __com_sun_star_frame_XController_idl__ +#include <com/sun/star/frame/XController.idl> +#endif +#ifndef __com_sun_star_frame_XDispatchProvider_idl__ +#include <com/sun/star/frame/XDispatchProvider.idl> +#endif +#ifndef __com_sun_star_util_VetoException_idl__ +#include <com/sun/star/util/VetoException.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +interface XObjectInspectorModel; +interface XObjectInspectorUI; + +//----------------------------------------------------------------------------- +/** describes the main interface of an <type>ObjectInspector</type>. + + @see ObjectInspector + + @since OOo 2.0.3 +*/ +interface XObjectInspector +{ + /** allows to plug the inspector into an <type scope="com::sun::star::frame">XFrame</type> + + <p>The <member scope="com::sun::star::frame">XController::setModel</member> method + accepts only <type>XObjectInspectorModel</type>s, and will return <FALSE/> if the + to-be-attached model is not <NULL/>, but does not support this interface.</p> + + <p>If you do not want to support a full-blown <type scope="com::sun::star::frame">XModel</type>, + use the <member>InspectorModel</member> attribute instead.</p> + + <p>The <member scope="com::sun::star::frame">XController::getViewData</member> and + <member scope="com::sun::star::frame">XController::restoreViewData</member> exchange + string values, which describes as much of the current view state as possible.</p> + */ + interface com::sun::star::frame::XController; + + /** allows to intercept functionality + + <p>This interface is inherited from the <type scope="com::sun::star::frame">Controller</type> + service, currently, there is no functionality to intercept at an <type>XObjectInspector</type>.</p> + */ + interface com::sun::star::frame::XDispatchProvider; + + /** provides access to the current model of the inspector + + <p>The model is mainly responsible for providing the property handlers. Additionally, + it can provide user interface names and help URLs for property categories.</p> + + <p>Note that there are two ways of setting or retrieving the current model: You can either + use <member scope="com::sun::star::frame">XModel::setModel</member>, or, if you do not want + or need to implement the full-blown <type scope="com::sun::star::frame">XModel</type> interface, + you can use this property directly. Both approaches are semantically equivalent.</p> + + <p>If a new model is set at the inspector, the complete UI will be rebuilt to reflect + the change, using the new property handlers provided by the new model.</p> + */ + [attribute] XObjectInspectorModel InspectorModel; + + /** provides access to the user interface of the object inspector. + + <p>This interface can be used to access and manipulate various aspects of + the user interface. For instance, you can enable and disable certain + property controls (or parts thereof), or register observers for all property + controls.</p> + + @since OOo 2.2 + */ + [attribute, readonly] XObjectInspectorUI InspectorUI; + + /** inspects a new collection of one or more objects. + + <p>If the sequence is empty, the UI of the <type>ObjectInspector</type> will be + cleared.</p> + + <p>If the sequence contains more than one object, the <type>XObjectInspector</type> + will create a complete set of property handlers (as indicated by + <member>XObjectInspectorModel::HandlerFactories</member>) for <em>every</em> of + the objects, and compose their output.</p> + + @throws com::sun::star::util::VetoException + if the inspector cannot switch to another object set. This typically happens if + one of the active <type>XPropertyHandler</type>'s raised a non-modal user interface, + and vetoed suspension of this UI. + + @see XPropertyHandler::isComposable + @see XPropertyHandler::onInteractivePropertySelection + @see XPropertyHandler::suspend + */ + void inspect( [in] sequence< com::sun::star::uno::XInterface > Objects ) + raises (com::sun::star::util::VetoException); +}; + +//============================================================================= + +}; }; }; }; + +#endif + + diff --git a/offapi/com/sun/star/inspection/XObjectInspectorModel.idl b/offapi/com/sun/star/inspection/XObjectInspectorModel.idl new file mode 100644 index 000000000000..b7248d87d25f --- /dev/null +++ b/offapi/com/sun/star/inspection/XObjectInspectorModel.idl @@ -0,0 +1,192 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XObjectInspectorModel_idl__ +#define __com_sun_star_inspection_XObjectInspectorModel_idl__ + +#ifndef __com_sun_star_uno_XInterface_idl__ +#include <com/sun/star/uno/XInterface.idl> +#endif +#ifndef __com_sun_star_inspection_PropertyCategoryDescriptor_idl__ +#include <com/sun/star/inspection/PropertyCategoryDescriptor.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +interface XPropertyHandler; + +//----------------------------------------------------------------------------- +/** describes the model of an <type>ObjectInspector</type> + + @see ObjectInspector + + @since OOo 2.0.3 +*/ +interface XObjectInspectorModel +{ + /** describes a set of factories for creating <type>XPropertyHandler</type>s + + <p>Every element of the sequence must contain information to create a + <type>XPropertyHandler</type> instance. Two ways are currently supported: + <ul> + <li>A sevice name:</br> + If a sequence element contains a string, this string is interpreted + as service name, and an <type scope="com::sun::star::lang">XMultiComponentFactory</type> + is asked to create an instance of this service.</li> + <li>A factory:<br/> + If a sequence element contains an instance implementing the + <type scope="com::sun::star::lang">XSingleComponentFactory</type> interface, this factory + is used to create a property handler.</li> + </ul></p> + + <p>This attribute is usually only evaluated by the <type>ObjectInspector</type> instance + which the model is currently bound to.</p> + + <p>The order of factories is important: If two property handlers declare themself responsible + for the same property, the one whose factory is listed <strong>last</strong> wins. Also, + if a handler <code>B</code> wants to supersede a property of another handler <code>A</code>, + <code>A</code>'s factory must precede the factory of <code>B</code>.</p> + + @see XPropertyHandler::getSupportedProperties + @see XPropertyHandler::getSupersededProperties + */ + [attribute, readonly] sequence< any > HandlerFactories; + + /** describes the property categories used by the property handlers. + + <p>Properties can be sorted into different categories, described by the <member>LineDescriptor::Category</member> + attribute, which is filled in <member>XPropertyHandler::describePropertyLine</member> + method of your property handler.<br/> + Those names provided by the handlers are programmatic names. All other information + about categories is part of the <type>PropertyCategoryDescriptor</type>, and + <member>describeCategories</member> assembles information about all categories which + all property handlers provided by the model use.</p> + + @return + a sequence of category descriptors. Their relative ordering also describes + the relative ordering of the categories in the <type>ObjectInspector</type>'s + user interface.<br/> + The sequence must not contain two entries with the same programmatic name.<br/> + <br/> + The model implementation might return an empty sequence here, in this case, the ObjectInspector + automatically builds its category information from the categories provided by the + property handlers. + @see PropertyCategoryDescriptor + @see LineDescriptor::Category + */ + sequence< PropertyCategoryDescriptor > describeCategories(); + + /** retrieves an index in a global property ordering, for a given property name + + <p>In the user interface of an ObjectInspector, single properties are represented by + single lines, and those lines are displayed successively. To determine an order of + the property lines, the inspector model can associate an "order index" with each property. + The <type>ObjectInspector</type> will then sort the property lines in a way that they + have the same relative ordering as the "order indexes" of their properties.</p> + + <p>Note that the concrete value the model returns for a given property does not + matter. All what matters is that if you want a certain property <code>Foo</code> + to be displayed after another property <code>Bar</code>, then the order index + of <code>Foo</code> should be greater than the order index of <code>Bar</code>. + + <p>If for two different properties the same order index is returned, the + <type>ObjectInspector</type> will assume the order in which those properties + were provided by the respective property handler + (<member>XPropertyHandler::getSupportedProperties</member>).<br/> + If two such properties originate from different handlers, they will be ordered according + to the order of the handlers, as provided in the <member>HandlerFactories</member> attribute.</p> + + @param PropertyName + the property whose global order index should be retrieved + @return + the global order index of <arg>PropertyName</arg>. + */ + long getPropertyOrderIndex( [in] string PropertyName ); + + /** indicates that the object inspector should have a help section. + + <p>The object inspector displays lines of property/values, optionally grouped + into categories, as described by the property handlers.<br/> + Additionally, the inspector can optionally display a section dedicated to help + texts. Clients could use this section to display context-sensitive help, for + instance short texts explaining the currently selected property.</p> + + @since OOo 2.2 + */ + [attribute, readonly] boolean HasHelpSection; + + /** denotes the minimum number of lines of text to be reserved for the help + section. + + <p>This property is ignored by the <type>ObjectInspector</type> if + <member>HasHelpSection</member> is <FALSE/>.</p> + + <p>The layout of the <type>ObjectInspector</type> is undefined if + <member>MinHelpTextLines</member> is larger than + <member>MaxHelpTextLines</member>.</p> + + @since OOo 2.2 + */ + [attribute, readonly] long MinHelpTextLines; + + /** denotes the maximum number of lines of text to be reserved for the help + section. + + <p>This property is ignored by the <type>ObjectInspector</type> if + <member>HasHelpSection</member> is <FALSE/>.</p> + + <p>The layout of the <type>ObjectInspector</type> is undefined if + <member>MaxHelpTextLines</member> is smaller than + <member>MinHelpTextLines</member>.</p> + + @since OOo 2.2 + */ + [attribute, readonly] long MaxHelpTextLines; + + /** determines whether the object inspector's UI should be read-only. + + <p>In this case, the user is able to browse through all properties, but cannot + change any of them.</p> + + <p>In a read-only object inspector, the property controls are readonly or + disabled themself, and the primary and secondary buttons of a property line + are both disabled.</p> + + @see XPropertyControl + @see LineDescriptor + */ + [attribute, bound] boolean IsReadOnly; +}; + +//============================================================================= + +}; }; }; }; + +#endif + + diff --git a/offapi/com/sun/star/inspection/XObjectInspectorUI.idl b/offapi/com/sun/star/inspection/XObjectInspectorUI.idl new file mode 100644 index 000000000000..f6a90c824426 --- /dev/null +++ b/offapi/com/sun/star/inspection/XObjectInspectorUI.idl @@ -0,0 +1,187 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __com_sun_star_inspection_XObjectInspectorUI_idl__ +#define __com_sun_star_inspection_XObjectInspectorUI_idl__ + +#ifndef __com_sun_star_inspection_XPropertyControl_idl__ +#include <com/sun/star/inspection/XPropertyControl.idl> +#endif +#ifndef __com_sun_star_beans_Optional_idl__ +#include <com/sun/star/beans/Optional.idl> +#endif +#ifndef __com_sun_star_container_NoSuchElementException_idl__ +#include <com/sun/star/container/NoSuchElementException.idl> +#endif +#ifndef __com_sun_star_lang_NoSupportException_idl__ +#include <com/sun/star/lang/NoSupportException.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +interface XPropertyControlObserver; + +//----------------------------------------------------------------------------- +/** grants access to certain aspects of the user interface of an object + inspector + + <p>This interface is used as callback for <type>XPropertyHandler</type>s.</p> + + <p>As a consequence, methods operating on the UI for a property, and taking the name of this property, + are tolerant against properties which do not exist. For instance, if a property handler tries to + disable the UI for property <code>Foo</code>, but another handler has superseded this property, then + the <type>ObjectInspector</type> will not <em>have</em> any UI for it. In this case, the call to + <code>enablePropertyUI( "Foo" )</code> will simply be ignored.</p> + + @since OOo 2.0.3 +*/ +interface XObjectInspectorUI +{ + /** enables or disables all components belonging to the UI representation of a property + + <p>This is usually used by an <type>XPropertyHandler</type> if it handles properties, + where one does only make sense if another one has a certain value.</p> + + @param PropertyName + denotes the name of the property whose UI is to be enabled or disabled. + @param Enable + <TRUE/> if and only if the UI should be disabled, <FALSE/> otherwise. + */ + void enablePropertyUI( [in] string PropertyName, [in] boolean Enable ); + + /** enables or disables the single elements which can be part of the UI representation of a property + + <p>Note that the complete UI for the property must be enabled in order for these settings to + be evaluated. That is, <member>enablePropertyUIElements</member> does not have any effect if + somebody previously disabled the complete UI for this property with <member>enablePropertyUI</member>.</p> + + @param PropertyName + the name of the property whose user interface elements are to be enabled or disabled + + @param Elements + a combination of <type>PropertyLineElement</type> flags specifying which elements are to be + enabled or disabled.<br/> + Note that if you don't set a particular bit here (say, <member>PropertyLineElement::PrimaryButton</member>), + this does mean that this element's state is not affected by the call - it does + <em>not</em> mean that it is disabled. + @param Enable + <TRUE/> if the elements denoted by <arg>_nElements</arg> should be enabled, <FALSE/> if + they should be disabled. + */ + void enablePropertyUIElements( + [in] string PropertyName, + [in] short Elements, + [in] boolean Enable + ); + + /** completely rebuilds the UI for the given property. + + <p>This method might be used by an <type>XPropertyHandler</type> if it wants to change the type + of control (see <type>PropertyControlType</type>) used to display a certain property.</p> + + <p>The object inspector will then call describePropertyLine again, and update its UI accordingly.</p> + + <p>Note that the property whose UI should be rebuilt must not necessarily be (though usually <em>is</em>) + in the responsibility of the handler which calls this method. The object inspector will look up the + handler with the responsibility for <arg>PropertyName</arg> and call its + <member>XPropertyHandler::describePropertyLine</member></p> + + @param PropertyName + the name of the property whose UI is to be completely rebuilt. + */ + void rebuildPropertyUI( [in] string PropertyName ); + + /** shows the UI for a given property + + @param PropertyName + the name of the property whose UI is to be shown + */ + void showPropertyUI( [in] string PropertyName ); + + /** hides the UI for a given property + + @param PropertyName + the name of the property whose UI is to be hidden + */ + void hidePropertyUI( [in] string PropertyName ); + + /** shows or hides all properties belonging to a given category + @see LineDescriptor::Category + @see XObjectInspectorModel::describeCategories + */ + void showCategory( [in] string Category, [in] boolean Show ); + + /** retrieves the control currently used to display a given property + + @param PropertyName + the name of the property whose control should be retrieved + + @return + the <type>XPropertyControl</type> representing the given property, or <NULL/> + if there is no such property control. + */ + XPropertyControl + getPropertyControl( [in] string PropertyName ); + + /** registers an observer for all property controls + + <p>The given XPropertyControlObserver will be notified of all changes + in all property controls.</p> + + @see revokeControlObserver + + @since OOo 2.2 + */ + void registerControlObserver( [in] XPropertyControlObserver Observer ); + + /** revokes a previously registered control observer + + @see registerControlObserver + + @since OOo 2.2 + */ + void revokeControlObserver( [in] XPropertyControlObserver Observer ); + + /** sets the text of the help section, if the object inspector contains + one. + + @throws NoSupportException + if the <member>XObjectInspectorModel::HasHelpSection</member> property + requires the help section to be unavailable. + + @since OOo 2.2 + */ + void setHelpSectionText( [in] string HelpText ) + raises ( ::com::sun::star::lang::NoSupportException ); +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/XPropertyControl.idl b/offapi/com/sun/star/inspection/XPropertyControl.idl new file mode 100644 index 000000000000..b48f730fa7d9 --- /dev/null +++ b/offapi/com/sun/star/inspection/XPropertyControl.idl @@ -0,0 +1,120 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XPropertyControl_idl__ +#define __com_sun_star_inspection_XPropertyControl_idl__ + +#ifndef __com_sun_star_beans_IllegalTypeException_idl__ +#include <com/sun/star/beans/IllegalTypeException.idl> +#endif +#ifndef __com_sun_star_awt_XWindow_idl__ +#include <com/sun/star/awt/XWindow.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +interface XPropertyControlContext; + +//----------------------------------------------------------------------------- +/** defines the interface for a single control in an <type>ObjectInspector</type> + + @since OOo 2.0.3 +*/ +interface XPropertyControl +{ + /** denotes the type of the control, as one of the <type>PropertyControlType</type> + constants + */ + [attribute, readonly] short ControlType; + + /** denotes the current content of the control. + + <p>At every point in time, this value is either <void/>, or of the type + described by <member>ValueType</member>.</p> + + @throws com::sun::star::beans::IllegalTypeException + if an attempt is made to set a value which is not <void/> and whose + type does not equal <member>ValueType</member>. + */ + [attribute] any Value + { + set raises ( com::sun::star::beans::IllegalTypeException ); + }; + + /** denotes the value type of the control. + + @see Value + */ + [attribute, readonly] type ValueType; + + /** specifies the context of the control within the <type>ObjectInspector</type>. + + <p>The property control should actively notify its state changes to the context. + In particular, changes in the focus and the value of the control must be notified. + */ + [attribute] XPropertyControlContext ControlContext; + + /** determines whether the control content is currently modified + + <p>An <type>XPropertyControl</type> internally manages a flag indicating whether + its content is modified. This flag is reset to <FALSE/> every time our + <member>ControlContext</member> is notified of our current value. Also, the control + implementation must set this flag to <TRUE/> if and only if the user changed the + control content.</p> + + @see notifyModifiedValue + @see ControlContext + @see XPropertyControlContext::valueChanged + */ + boolean isModified(); + + /** notifies the context in which the control lives of the current control value, + if this value is currently modified + + @see isModified + @see ControlContext + @see XPropertyControlListener::valueChanged + */ + void notifyModifiedValue(); + + /** denotes the window which is the real UI representation of the property control. + + <p>The <type>ObjectInspector</type> will automatically position and size this control + as needed, care for its Z-order, and so on.</p> + + <p>This Window must not be <NULL/>, else the whole control is not usable.</p> + */ + [attribute, readonly] com::sun::star::awt::XWindow ControlWindow; +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/XPropertyControlContext.idl b/offapi/com/sun/star/inspection/XPropertyControlContext.idl new file mode 100644 index 000000000000..457ef549652d --- /dev/null +++ b/offapi/com/sun/star/inspection/XPropertyControlContext.idl @@ -0,0 +1,60 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XPropertyControlContext_idl__ +#define __com_sun_star_inspection_XPropertyControlContext_idl__ + +#ifndef __com_sun_star_inspection_XPropertyControlObserver_idl__ +#include <com/sun/star/inspection/XPropertyControlObserver.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** specifies the interface of the context of an <type>XPropertyControl</type>. + + @see XPropertyControl::ControlContext + + @since OOo 2.0.3 +*/ +interface XPropertyControlContext : XPropertyControlObserver +{ + /** instructs the <type>XPropertyControlContext</type> to active the next control + + @param CurrentControl + denotes the control which initiated the request. + */ + [oneway] void activateNextControl( [in] XPropertyControl CurrentControl ); +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/XPropertyControlFactory.idl b/offapi/com/sun/star/inspection/XPropertyControlFactory.idl new file mode 100644 index 000000000000..964a2c4fb3e8 --- /dev/null +++ b/offapi/com/sun/star/inspection/XPropertyControlFactory.idl @@ -0,0 +1,81 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XPropertyControlFactory_idl__ +#define __com_sun_star_inspection_XPropertyControlFactory_idl__ + +#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ +#include <com/sun/star/lang/IllegalArgumentException.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +interface XPropertyControl; + +//----------------------------------------------------------------------------- +/** a factory for <type>XPropertyControl</type>s + + @since OOo 2.0.3 +*/ +interface XPropertyControlFactory +{ + /** creates a <type>XPropertyControl</type> + + <p>A <type>XPropertyControlFactory</type> can create any of the control types denoted by + the <type>PropertyControlType</type> constants.</p> + + @param ControlType + the type of the requested control + + @param CreateReadOnly + determines whether the newly created control should be readonly. + + <p>If this argument is <TRUE/>, this does not necessarily mean that the property cannot be + changed at all in the <type>ObjectInspector</type>. Instead, an <type>XPropertyHandler</type> + can still decide that there is a dedicated UI for entering the property value, + which is usually triggered by a <member>LineDescriptor::PrimaryButton</member>.</p> + + <p>Note that this parameter might be ignored if the <member>XObjectInspectorModel::IsReadOnly</member> + attribute is <TRUE/>, in which case all created property controls must be readonly.</p> + + @returns + a control of the given type. + + @throws com::sun::star::lang::IllegalArgumentException + if the given <arg>ControlType</arg> is not a value <type>PropertyControlType</type> + */ + XPropertyControl createPropertyControl( [in] short ControlType, [in] boolean CreateReadOnly ) + raises ( com::sun::star::lang::IllegalArgumentException ); +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/XPropertyControlObserver.idl b/offapi/com/sun/star/inspection/XPropertyControlObserver.idl new file mode 100644 index 000000000000..51263e6824a5 --- /dev/null +++ b/offapi/com/sun/star/inspection/XPropertyControlObserver.idl @@ -0,0 +1,75 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XPropertyControlObserver_idl__ +#define __com_sun_star_inspection_XPropertyControlObserver_idl__ + +#ifndef __com_sun_star_uno_XInterface_idl__ +#include <com/sun/star/uno/XInterface.idl> +#endif + +//============================================================================= + +module com { module sun { module star { module inspection { + +interface XPropertyControl; + +//============================================================================= + +/** specifies an interface for components to observer certain aspects + of an <type>XPropertyControl</type>. + + @since OOo 2.2 +*/ +interface XPropertyControlObserver +{ + /** notifies the observer that a certain <type>XPropertyControl</type>'s UI + representation gained the focus. + + @param Control + denotes the control whose UI representation gained the focus + */ + [oneway] void focusGained( [in] XPropertyControl Control ); + + /** notifies the observer that a certain <type>XPropertyControl</type>'s value + changed. + + @param Control + denotes the control whose value changed. + + @see XPropertyControl::Value + */ + [oneway] void valueChanged( [in] XPropertyControl Control ); +}; + +//============================================================================= + +}; }; }; }; + +//============================================================================= + +#endif diff --git a/offapi/com/sun/star/inspection/XPropertyHandler.idl b/offapi/com/sun/star/inspection/XPropertyHandler.idl new file mode 100644 index 000000000000..81a105b8b9a5 --- /dev/null +++ b/offapi/com/sun/star/inspection/XPropertyHandler.idl @@ -0,0 +1,471 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __com_sun_star_inspection_XPropertyHandler_idl__ +#define __com_sun_star_inspection_XPropertyHandler_idl__ + +#ifndef __com_sun_star_beans_PropertyState_idl__ +#include <com/sun/star/beans/PropertyState.idl> +#endif +#ifndef __com_sun_star_beans_Property_idl__ +#include <com/sun/star/beans/Property.idl> +#endif +#ifndef __com_sun_star_beans_XPropertyChangeListener_idl__ +#include <com/sun/star/beans/XPropertyChangeListener.idl> +#endif +#ifndef __com_sun_star_inspection_LineDescriptor_idl__ +#include <com/sun/star/inspection/LineDescriptor.idl> +#endif +#ifndef __com_sun_star_lang_NullPointerException_idl__ +#include <com/sun/star/lang/NullPointerException.idl> +#endif +#ifndef __com_sun_star_beans_UnknownPropertyException_idl__ +#include <com/sun/star/beans/UnknownPropertyException.idl> +#endif +#ifndef __com_sun_star_lang_XComponent_idl__ +#include <com/sun/star/lang/XComponent.idl> +#endif +#ifndef __com_sun_star_inspection_InteractiveSelectionResult_idl__ +#include <com/sun/star/inspection/InteractiveSelectionResult.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +interface XObjectInspectorUI; +interface XPropertyControlFactory; + +//----------------------------------------------------------------------------- +/** is the basic interface for object inspection. + + <p>The <type>ObjectInspector</type> itself does not know anything about the object + it is inspecting, all information is obtained via <type>XPropertyHandler</type>s. + Also, property handlers are responsible for describing the user interface which should + be used to interact with the user, with respect to a given aspect of the inspected + component.</p> + + @see ObjectInspector + @see LineDescriptor + + @since OOo 2.0.3 +*/ +interface XPropertyHandler +{ + /** used for controlling resources acquired by the handler + + <p><member scope="com::sun::star::lang">XComponent::dispose</member> is invoked when the property handler is not + needed by the object inspector anymore. Handler implementations should clean up any + resources here.</p> + */ + interface com::sun::star::lang::XComponent; + + /** binds the property handler to a new component + @param Component + the component to inspect. Must not be <NULL/> + @throws com::sun::star::lang::NullPointerException + if the component is <NULL/> + */ + void inspect( [in] com::sun::star::uno::XInterface Component ) + raises( com::sun::star::lang::NullPointerException ); + + /** retrieves the current value of a property + @param PropertyName + the name of the property whose value is to be retrieved + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by the property handler + */ + any + getPropertyValue( [in] string PropertyName ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** sets the value of a property + + @param PropertyName + the name of the property whose value is to be set + @param Value + the property value to set + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by the property handler + */ + void + setPropertyValue( [in] string PropertyName, [in] any Value ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** returns the state of a property + + @param PropertyName + the name of the property whose state is to be retrieved + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by the property handler + */ + com::sun::star::beans::PropertyState + getPropertyState( [in] string PropertyName ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** describes the UI to be used to represent the property + @param PropertyName + the name of the property whose user interface is to be described + implementation + @param ControlFactory + a factory for creating <type>XPropertyControl</type> instances. Must not be <NULL/>. + @return + the descriptor of the property line. + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by this handler + @throws com::sun::star::lang::NullPointerException + if <arg>ControlFactory</arg> is <NULL/>. + @see PropertyControlType + @see LineDescriptor + */ + LineDescriptor + describePropertyLine( + [in] string PropertyName, + [in] XPropertyControlFactory ControlFactory + ) + raises (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::NullPointerException); + + /** converts a given control-compatible value to a property value + + <p>In <member>describePropertyLine</member>, a property handler declared which type of control + should be used to display the value of a certain property. To allow to use the same control + type for different properties, and in particular, for properties of different type, + conversions between controls values and property values are needed.</p> + + <p>This method converts a control value into a property value, which subsequently can be used + in conjunction with <member>setPropertyValue</member>.</p> + + @param PropertyName + The name of the conversion's target property. + @param ControlValue + The to-be-converted control value. This value has been obtained from an <type>XPropertyControl</type>, + using its <member>Value</member> attribute. + + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by the property handler + + @see convertToControlValue + @see describePropertyLine + @see XPropertyControl + @see getPropertyValue + */ + any + convertToPropertyValue( + [in] string PropertyName, + [in] any ControlValue + ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** converts a given property value to a control-compatible value + + <p>In <member>describePropertyLine</member>, a property handler declared which type of control + should be used to display the value of a certain property. To allow to use the same control + type for different properties, and in particular, for properties of different type, + conversions between controls values and property values are needed.</p> + + <p>This method converts a property value, which has previously been obtained using + <member>getPropertyValue</member>, into a control-compatible value, which can be used + with <type>XPropertyControl</type>'s <member>XPropertyControl::Value</member> attribute.</p> + + <p>A usual application of this method are list boxes: There is a generic list box implementation, + which is able to display a simple list of strings. Usually, every string represents one + possible property value. To translate between those property values and the displayed strings, + <member>convertToControlValue</member> and <member>convertToPropertyValue</member> are used.</p> + + <p>The method is not invoked if the control's value type (<member>XPropertyControl::ValueType</member> + equals the property's value type.</p> + + @param PropertyName + The name of the property whose value is to be converted. + @param PropertyValue + The to-be-converted property value. + @param ControlValueType + The target type of the conversion. This type is determined by the control which + is used to display the property, which in turn is determined by the handler itself + in <member>describePropertyLine</member>.<br/> + Speaking strictly, this is passed for convenience only, since every <type>XPropertyHandler</type> + implementation should know exactly which type to expect, since it implicitly determined this type + in <member>describePropertyLine</member> by creating an appropriate <type>XPropertyControl</type>. + + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by the property handler + + @see convertToPropertyValue + @see describePropertyLine + @see XPropertyControl + @see getPropertyValue + */ + any + convertToControlValue( + [in] string PropertyName, + [in] any PropertyValue, + [in] type ControlValueType + ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** registers a listener for notification about property value changes + + <p>An <type>XPropertyHandler</type> implementation might decide to ignore this call. + However, in this case property value changes made by third party components are not + reflected in the object inspector.</p> + + <p>If a handler implementation supports property change listeners, it must be able to cope + with a call to <member>addPropertyChangeListener</member> even if currently no component is + being inspected. In this case, the listener must become active as soon as a new introspectee + is set in the next <member>inspect</member> call.</p> + + @param Listener + the listener to notify about property changes + @throws com::sun::star::lang::NullPointerException + if the listener is <NULL/> + @see removePropertyChangeListener + */ + void + addPropertyChangeListener( [in] com::sun::star::beans::XPropertyChangeListener Listener ) + raises ( com::sun::star::lang::NullPointerException ); + + /** revokes a listener for notification about property value changes + @see addPropertyChangeListener + */ + void + removePropertyChangeListener( [in] com::sun::star::beans::XPropertyChangeListener Listener ); + + /** returns the properties which the handler can handle + + <p>A handler is allowed to return an empty sequence here, indicating that for + the given introspectee, no properties handling can be provided. This might happen + when a fixed set of property handlers is used for a variety of components to inspect, + where not all handlers can really cope with all components.</p> + + <p>In the case of returning an empty sequence here, the property handler is ignored + by all further processing in the object inspector.</p> + */ + sequence< com::sun::star::beans::Property > + getSupportedProperties(); + + /** returns the properties which are to be superseded by this handler + + <p>Besides defining an own set of properties (see <member>getSupportedProperties</member>), + a property handler can also declare that foreign properties (which it is + <em>not</em> responsible for) are superseded by its own properties.</p> + + <p>This is usually used if your handler is used with another, more generic one, which + should continue to be responsible for all properties, except a few which your + handler handles more elegantly.</p> + + <p>In such a case, simply return those properties here.</p> + + <p>There is a precedence in the property handlers used by an <type>ObjectInspector</type>, + which also is important for the superseded properties. This precendence is implied by the + precendence of factories to create the property handlers, as denoted in the + <member>XObjectInspectorModel::HandlerFactories</member> attribute.</p> + + <p>With this in mind, property handlers can only supersede properties which are supported + by a handler preceding them, but not properties of handlers succeeding them.</p> + + <p>For instance, imaging an <type>XObjectInspectorModel</type> which provides three + factories, for handler <code>A</code>, <code>B</code>, and <code>C</code> - in this order. + Now if <code>A</code> supports the property <code>Foo</code>, <code>C</code> supports + <code>Bar</code>, and <code>B</code> supersedes both <code>Foo</code> and <code>Bar</code>, + them the result is <code>Bar</code> is still present. This is because <code>B</code> precedes + <code>C</code>, so it cannot, by definition, supersede properties which are supported by + <code>C</code>.</p> + + <p>If <member>getSupportedProperties</member> returned an empty sequence, this method will + not be called.</p> + + @see XObjectInspectorModel::HandlerFactories + */ + sequence< string > + getSupersededProperties( ); + + /** retrieve the actuating properties which this handler is interested in + + <p>In general, properties can be declared as "actuating", that is, when their value + changes, the UI for other properties needs to be updated (e.g. enabled or disabled).</p> + + <p>With this method, a handler can declare that it feels responsible for some/all + of the depending properties of certain actuating properties.</p> + + <p>Whenever the value of an actuating property changes, all handlers which expressed + their interest in this particular actuating properties are called with their + <member>actuatingPropertyChanged</member> method.</p> + + <p>If <member>getSupportedProperties</member> returned an empty sequence, this method will + not be called</p> + */ + sequence< string > + getActuatingProperties( ); + + /** determines whether a given property, which the handler is responsible for, is composable. + + <p>An object inspector can inspect multiple components at once, displaying the <em>intersection</em> + of their properties. For this, all components are examined for their properties, and all properties + which exist for all components, <em>and</em> are declared to be composable by their respective handler, + are displayed in the inspector UI.</p> + + @param PropertyName + the name of the property whose composability is to be determined + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by the property handler + */ + boolean isComposable( [in] string PropertyName ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** called when a browse button belonging to a property UI represenation has been clicked + + <p>Property handlers can raise a dedicated UI for entering or somehow changing a property value. + Usually, this will be a modal dialog, but it can also be a non-modal user interface component.</p> + + <p>Availability of this feature is indicated by the <member>LineDescriptor::HasPrimaryButton</member> + and <member>LineDescriptor::HasSecondaryButton</member> members of a <type>LineDescriptor</type>, + which the <type>XPropertyHandler</type> fills in its <member>describePropertyLine</member> method.</p> + + <p>When this method is called, the property handler should raise the UI needed to enter the + property value, and return the result of this (see <type>InteractiveSelectionResult</type>).</p> + + <p>It is recommended that property handlers do not directly set the property value which has + been obatined from the user, but store it in the output-parameter Data, and return + <member>InteractiveSelectionResult::ObtainedValue</member>.</p> + + <p>If a handler sets the new property value directly, and returns + <member>InteractiveSelectionResult::ObtainedValue</member>, this implies that the property + cannot properly be handled in case the object inspector is inspecting an intersection of + multiple components, since in this case <member>onInteractivePropertySelection</member> + will be called at one handler only, however the new property would have to be forwarded to + all handlers.</p> + + <p>If a property is not composeable, directly setting the new property value does not yield any problem, + as long as property listeners are properly notified of the change.</p> + + @param PropertyName + The name of the property whose browse button has been clicked + + @param Primary + <TRUE/> if and only if the primary button has been clicked, <FALSE/> otherwise + + @param out_Data + If the method returns <member>InteractiveSelectionResult::ObtainedValue</member>, + then <arg>out_Data</arg> contains the value which has been interactively obtained + from the user, and which still needs to be set at the inspected component. + + @param InspectorUI + provides access to the object inspector UI. Implementations should use this if + the property selection requires non-modal user input. In those cases, + <member>onInteractivePropertySelection</member> should return <member>InteractiveSelectionResult::Pending</member>, + and the UI for (at least) the property whose input is still pending should be disabled. + + @return + the result of the interactive property value selection. + + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by the property handler + @throws com::sun::star::lang::NullPointerException + if <arg>InspectorUI</arg> is <NULL/> + + @see describePropertyLine + @see addPropertyChangeListener + @see isComposable + */ + ::com::sun::star::inspection::InteractiveSelectionResult + onInteractivePropertySelection( + [in] string PropertyName, + [in] boolean Primary, + [out] any out_Data, + [in] XObjectInspectorUI InspectorUI + ) + raises (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::NullPointerException); + + /** updates the UI of dependent properties when the value of a certain actuating property changed + + <p>This method is called whenever a property value changes, limited to those properties + whose changes the handler expressed interest in (see <member>getActuatingProperties</member>).</p> + + @param ActuatingPropertyName + the id of the actuating property. + @param NewValue + the new value of the property + @param OldValue + the old value of the property + @param InspectorUI + a callback for updating the object inspector UI + @param FirstTimeInit + If <TRUE/>, the method is called for the first-time update of the respective property, that + is, when the property browser is just initializing with the properties of the introspected + object.<br/> + If <FALSE/>, there was a real <member scope="com::sun::star::beans">XPropertyChangeListener::propertyChange</member> + event which triggered the call.<br/> + <br/> + In some cases it may be necessary to differentiate between both situations. For instance, + if you want to set the value of another property when an actuating property's value changed, + you should definately not do this when <arg>FirstTimeInit</arg> is <TRUE/>. + @throws com::sun::star::lang::NullPointerException + if <arg>InspectorUI</arg> is <NULL/> + */ + void + actuatingPropertyChanged( + [in] string ActuatingPropertyName, + [in] any NewValue, + [in] any OldValue, + [in] XObjectInspectorUI InspectorUI, + [in] boolean FirstTimeInit + ) + raises (::com::sun::star::lang::NullPointerException); + + /** suspends the handler + + <p>A <type>XPropertyHandler</type> is used by a <type>XObjectInspector</type> instance, + which implements the XController interface. By definition, a XObjectInspector always forwards + all suspend requests (<member scope="com::sun::star::frame">XController::suspend</member>) to + all it's handlers.</p> + + <p>The usual use case for this method are non-modal user interface components used + for property value input. Such a component might have been opened during + <member>onInteractivePropertySelection</member>. If a property handler receives a + <member>suspend</member> call, it should forward the suspension request to the UI + component, and veto suspension of the <type>XObjectInspector</type> as appropriate.</p> + + <p>If suspension is not to be vetoed, then all non-modal UI components opened + by the handler should have been closed when it returns from the <member>suspend</member> call.</p> + + @param Suspend + Whether the handler is to be suspended <TRUE/> or reactivated (<FALSE/>). The + latter happens if a handler was successfully suspended, but an external instance + vetoed the whole suspension process. + + @return + <TRUE/> if the handler does allow suspension, <FALSE/> if it vetoes it. + */ + boolean suspend( [in] boolean Suspend ); +}; + +//============================================================================= + +}; }; }; }; + +#endif + + + diff --git a/offapi/com/sun/star/inspection/XStringListControl.idl b/offapi/com/sun/star/inspection/XStringListControl.idl new file mode 100644 index 000000000000..640741961090 --- /dev/null +++ b/offapi/com/sun/star/inspection/XStringListControl.idl @@ -0,0 +1,73 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XStringListControl_idl__ +#define __com_sun_star_inspection_XStringListControl_idl__ + +#ifndef __com_sun_star_inspection_XPropertyControl_idl__ +#include <com/sun/star/inspection/XPropertyControl.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** defines the interface for an <type>XPropertyControl</type> which, additionally + to the basic behaviour, supports a list of strings interpreted as possible + property values. + + <p>A control which would canonically implement this interface is a list box control: + The string list defined by <type>XStringListControl</type> would in the control be + represented as drop-down list containing all the strings.</p> + + @since OOo 2.0.3 +*/ +interface XStringListControl : XPropertyControl +{ + /** clears the whole list + */ + void clearList(); + + /** prepends a new entry to the beginning of the list + */ + void prependListEntry( [in] string NewEntry ); + + /** appends a new entry to the end of the list + */ + void appendListEntry( [in] string NewEntry ); + + /** gets all list entries + */ + sequence< string > getListEntries(); +}; + +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/XStringRepresentation.idl b/offapi/com/sun/star/inspection/XStringRepresentation.idl new file mode 100644 index 000000000000..66888f3cc240 --- /dev/null +++ b/offapi/com/sun/star/inspection/XStringRepresentation.idl @@ -0,0 +1,76 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_inspection_XStringRepresentation_idl__ +#define __com_sun_star_inspection_XStringRepresentation_idl__ + +#ifndef __com_sun_star_script_XTypeConverter_idl__ +#include <com/sun/star/script/XTypeConverter.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +//----------------------------------------------------------------------------- +/** handles string representations of property values. + @see +*/ +interface XStringRepresentation +{ + /** converts a into a string. + @param PropertyValue + The to-be-converted property value. + @return + The converted string representation of the property value. + @see <member>XPropertyHandler::convertToControlValue</member> + */ + string convertToControlValue([in]any PropertyValue) raises( com::sun::star::uno::Exception ); + + /** converts a string into an any with the type defined by the target tpye. + @param ControlValue + The to-be-converted control value. + @param ControlValueType + The target type of the conversion. + @see <member>XPropertyHandler::convertToPropertyValue</member> + */ + any convertToPropertyValue( + [in]string ControlValue, + [in]type ControlValueType + ) raises( com::sun::star::uno::Exception ); +}; + +service StringRepresentation : XStringRepresentation +{ + create([in]com::sun::star::script::XTypeConverter TypeConverter)raises( com::sun::star::lang::IllegalArgumentException ); + createConstant([in]com::sun::star::script::XTypeConverter TypeConverter,[in] string Constant,[in] sequence<string> Values)raises( com::sun::star::lang::IllegalArgumentException ); +}; +//============================================================================= + +}; }; }; }; + +#endif + diff --git a/offapi/com/sun/star/inspection/makefile.mk b/offapi/com/sun/star/inspection/makefile.mk new file mode 100644 index 000000000000..bca5fd1e1f17 --- /dev/null +++ b/offapi/com/sun/star/inspection/makefile.mk @@ -0,0 +1,66 @@ +#************************************************************************* +# +# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. +# +# Copyright 2000, 2010 Oracle and/or its affiliates. +# +# OpenOffice.org - a multi-platform office productivity suite +# +# This file is part of OpenOffice.org. +# +# OpenOffice.org is free software: you can redistribute it and/or modify +# it under the terms of the GNU Lesser General Public License version 3 +# only, as published by the Free Software Foundation. +# +# OpenOffice.org is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU Lesser General Public License version 3 for more details +# (a copy is included in the LICENSE file that accompanied this code). +# +# You should have received a copy of the GNU Lesser General Public License +# version 3 along with OpenOffice.org. If not, see +# <http://www.openoffice.org/license.html> +# for a copy of the LGPLv3 License. +# +#************************************************************************* + +PRJ=..$/..$/..$/.. + +PRJNAME=offapi + +TARGET=cssinspection +PACKAGE=com$/sun$/star$/inspection + +# --- Settings ----------------------------------------------------- +.INCLUDE : $(PRJ)$/util$/makefile.pmk + +# ------------------------------------------------------------------------ +IDLFILES=\ + DefaultHelpProvider.idl \ + GenericPropertyHandler.idl \ + InteractiveSelectionResult.idl \ + LineDescriptor.idl \ + ObjectInspector.idl \ + ObjectInspectorModel.idl \ + PropertyCategoryDescriptor.idl \ + PropertyControlType.idl \ + PropertyLineElement.idl \ + XHyperlinkControl.idl \ + XNumericControl.idl \ + XObjectInspector.idl \ + XObjectInspectorModel.idl \ + XObjectInspectorUI.idl \ + XPropertyControl.idl \ + XPropertyControlContext.idl \ + XPropertyControlFactory.idl \ + XPropertyControlObserver.idl \ + XPropertyHandler.idl \ + XStringListControl.idl \ + XStringRepresentation.idl + +# ------------------------------------------------------------------ +.INCLUDE : target.mk +.INCLUDE : $(PRJ)$/util$/target.pmk + + |