AOO410/main/offapi/com/sun/star/inspection/XPropertyHandler.idl - openoffice - Git at Google

 /**************************************************************
  *
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
  * under the 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 {

 published interface XObjectInspectorUI;
 published 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 OpenOffice 2.0.3
 */
 published 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
	/**************************************************************
	*
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the 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 {

	published interface XObjectInspectorUI;
	published 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 OpenOffice 2.0.3
	*/
	published 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