Quelle XPropertyHandler.idl
Sprache: C
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* * This file is part of the LibreOffice project . * * This Source Code Form is subject to the terms of the Mozilla Public * License , v . 2 . 0 . If a copy of the MPL was not distributed with this * file , You can obtain one at http : //mozilla.org/MPL/2.0/. * * This file incorporates work covered by the following license notice : * * 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 . /** is the basic interface for object inspection. < p > The ObjectInspector itself does not know anything about the object it is inspecting , all information is obtained via XPropertyHandlers . 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 /** used for controlling resources acquired by the handler < p > com : : sun : : star : : lang : : XComponent : : dispose ( ) is invoked when the property handler is not needed by the object inspector anymore . Handler implementations should clean up any resources here . < / p > /** 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 )/** 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 /** 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 /** 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 /** 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 XPropertyControl 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 ControlFactory is ` NULL ` . @ see PropertyControlType @ see LineDescriptor :NullPointerException);/** converts a given control-compatible value to a property value < p > In describePropertyLine ( ) , 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 setPropertyValue ( ) . < / 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 XPropertyControl , using its XPropertyControl : : Value 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 /** converts a given property value to a control-compatible value < p > In describePropertyLine ( ) , 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 getPropertyValue ( ) , into a control - compatible value , which can be used with XPropertyControl ' s XPropertyControl : : Value 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 , convertToControlValue ( ) and convertToPropertyValue ( ) are used . < / p > < p > The method is not invoked if the control ' s value type ( XPropertyControl : : ValueType 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 describePropertyLine ( ) . < br / > Speaking strictly , this is passed for convenience only , since every XPropertyHandler implementation should know exactly which type to expect , since it implicitly determined this type in describePropertyLine ( ) by creating an appropriate XPropertyControl . @ 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 /** registers a listener for notification about property value changes < p > An XPropertyHandler 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 addPropertyChangeListener ( ) even if currently no component is being inspected . In this case , the listener must become active as soon as a new introspection is set in the next inspect ( ) 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 ener )/** revokes a listener for notification about property value changes @ see addPropertyChangeListener void istener );/** returns the properties which the handler can handle < p > A handler is allowed to return an empty sequence here , indicating that for the given introspection , 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 > /** returns the properties which are to be superseded by this handler < p > Besides defining an own set of properties ( see getSupportedProperties ( ) ) , 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 ObjectInspector , which also is important for the superseded properties . This precedence is implied by the precedence of factories to create the property handlers , as denoted in the XObjectInspectorModel : : HandlerFactories 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 XObjectInspectorModel 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 getSupportedProperties ( ) returned an empty sequence , this method will not be called . < / p > @ see XObjectInspectorModel : : HandlerFactories /** 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 actuatingPropertyChanged ( ) method . < / p > < p > If getSupportedProperties ( ) returned an empty sequence , this method will not be called < / p > /** 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 /** called when a browse button belonging to a property UI representation 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 LineDescriptor : : HasPrimaryButton and LineDescriptor : : HasSecondaryButton members of a LineDescriptor , which the XPropertyHandler fills in its describePropertyLine ( ) 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 InteractiveSelectionResult ) . < / p > < p > It is recommended that property handlers do not directly set the property value which has been obtained from the user , but store it in the output - parameter Data , and return InteractiveSelectionResult : : ObtainedValue . < / p > < p > If a handler sets the new property value directly , and returns InteractiveSelectionResult : : ObtainedValue , 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 onInteractivePropertySelection ( ) 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 composable , 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 outData If the method returns InteractiveSelectionResult : : ObtainedValue , then outData 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 , onInteractivePropertySelection ( ) should return InteractiveSelectionResult : : Pending , 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 InspectorUI is ` NULL ` @ see describePropertyLine @ see addPropertyChangeListener @ see isComposable :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 getActuatingProperties ( ) ) . < / 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 com : : sun : : star : : beans : : XPropertyChangeListener : : propertyChange ( ) 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 definitely not do this when FirstTimeInit is ` TRUE ` . @ throws com : : sun : : star : : lang : : NullPointerException if InspectorUI is ` NULL ` void /** suspends the handler < p > A XPropertyHandler is used by a XObjectInspector instance , which implements the XController interface . By definition , a XObjectInspector always forwards all suspend requests ( com : : sun : : star : : frame : : XController : : suspend ( ) ) to all its 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 onInteractivePropertySelection ( ) . If a property handler receives a suspend ( ) call , it should forward the suspension request to the UI component , and veto suspension of the XObjectInspector 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 suspend ( ) 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 . /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
Messung V0.5 in Prozent C=95 H=100 G=97
¤ Dauer der Verarbeitung: 0.31 Sekunden
(vorverarbeitet am 2026-10-06)
¤ *© Formatika GbR, Deutschland
2026-10-10
Neuigkeiten Aktuelles Motto des Tages Open Source Software
Jenseits des Üblichen ....
Besucherstatistik
Statistik #Sources=1126864 #Domains=1897691
