offapi/com/sun/star/inspection/XObjectInspectorUI.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XObjectInspectorUI.idl,v $
  10  * $Revision: 1.5 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_inspection_XObjectInspectorUI_idl__
  31 #define __com_sun_star_inspection_XObjectInspectorUI_idl__
  32
  33 #ifndef __com_sun_star_inspection_XPropertyControl_idl__
  34 #include <com/sun/star/inspection/XPropertyControl.idl>
  35 #endif
  36 #ifndef __com_sun_star_beans_Optional_idl__
  37 #include <com/sun/star/beans/Optional.idl>
  38 #endif
  39 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  40 #include <com/sun/star/container/NoSuchElementException.idl>
  41 #endif
  42 #ifndef __com_sun_star_lang_NoSupportException_idl__
  43 #include <com/sun/star/lang/NoSupportException.idl>
  44 #endif
  45
  46 //=============================================================================
  47 module com {  module sun {  module star {  module inspection {
  48
  49 interface XPropertyControlObserver;
  50
  51 //-----------------------------------------------------------------------------
  52 /** grants access to certain aspects of the user interface of an object
  53     inspector
  54
  55     <p>This interface is used as callback for <type>XPropertyHandler</type>s.</p>
  56
  57     <p>As a consequence, methods operating on the UI for a property, and taking the name of this property,
  58     are tolerant against properties which do not exist. For instance, if a property handler tries to
  59     disable the UI for property <code>Foo</code>, but another handler has superseded this property, then
  60     the <type>ObjectInspector</type> will not <em>have</em> any UI for it. In this case, the call to
  61     <code>enablePropertyUI( "Foo" )</code> will simply be ignored.</p>
  62
  63     @since OOo 2.0.3
  64 */
  65 interface XObjectInspectorUI
  66 {
  67     /** enables or disables all components belonging to the UI representation of a property
  68
  69         <p>This is usually used by an <type>XPropertyHandler</type> if it handles properties,
  70         where one does only make sense if another one has a certain value.</p>
  71
  72         @param  PropertyName
  73             denotes the name of the property whose UI is to be enabled or disabled.
  74         @param  Enable
  75             <TRUE/> if and only if the UI should be disabled, <FALSE/> otherwise.
  76     */
  77     void    enablePropertyUI( [in] string PropertyName, [in] boolean Enable );
  78
  79     /** enables or disables the single elements which can be part of the UI representation of a property
  80
  81         <p>Note that the complete UI for the property must be enabled in order for these settings to
  82         be evaluated. That is, <member>enablePropertyUIElements</member> does not have any effect if
  83         somebody previously disabled the complete UI for this property with <member>enablePropertyUI</member>.</p>
  84
  85         @param  PropertyName
  86             the name of the property whose user interface elements are to be enabled or disabled
  87
  88         @param  Elements
  89             a combination of <type>PropertyLineElement</type> flags specifying which elements are to be
  90             enabled or disabled.<br/>
  91             Note that if you don't set a particular bit here (say, <member>PropertyLineElement::PrimaryButton</member>),
  92             this does mean that this element's state is not affected by the call - it does
  93             <em>not</em> mean that it is disabled.
  94         @param  Enable
  95             <TRUE/> if the elements denoted by <arg>_nElements</arg> should be enabled, <FALSE/> if
  96             they should be disabled.
  97     */
  98     void    enablePropertyUIElements(
  99                         [in] string PropertyName,
 100                         [in] short Elements,
 101                         [in] boolean Enable
 102                     );
 103
 104     /** completely rebuilds the UI for the given property.
 105
 106         <p>This method might be used by an <type>XPropertyHandler</type> if it wants to change the type
 107         of control (see <type>PropertyControlType</type>) used to display a certain property.</p>
 108
 109         <p>The object inspector will then call describePropertyLine again, and update its UI accordingly.</p>
 110
 111         <p>Note that the property whose UI should be rebuilt must not necessarily be (though usually <em>is</em>)
 112         in the responsibility of the handler which calls this method. The object inspector will look up the
 113         handler with the responsibility for <arg>PropertyName</arg> and call its
 114         <member>XPropertyHandler::describePropertyLine</member></p>
 115
 116         @param PropertyName
 117             the name of the property whose UI is to be completely rebuilt.
 118     */
 119     void    rebuildPropertyUI( [in] string PropertyName );
 120
 121     /** shows the UI for a given property
 122
 123         @param  PropertyName
 124             the name of the property whose UI is to be shown
 125     */
 126     void    showPropertyUI( [in] string PropertyName );
 127
 128     /** hides the UI for a given property
 129
 130         @param  PropertyName
 131             the name of the property whose UI is to be hidden
 132     */
 133     void    hidePropertyUI( [in] string PropertyName );
 134
 135     /** shows or hides all properties belonging to a given category
 136         @see LineDescriptor::Category
 137         @see XObjectInspectorModel::describeCategories
 138     */
 139     void    showCategory( [in] string Category, [in] boolean Show );
 140
 141     /** retrieves the control currently used to display a given property
 142
 143         @param PropertyName
 144             the name of the property whose control should be retrieved
 145
 146         @return
 147             the <type>XPropertyControl</type> representing the given property, or <NULL/>
 148             if there is no such property control.
 149     */
 150     XPropertyControl
 151             getPropertyControl( [in] string PropertyName );
 152
 153     /** registers an observer for all property controls
 154
 155         <p>The given XPropertyControlObserver will be notified of all changes
 156         in all property controls.</p>
 157
 158         @see revokeControlObserver
 159
 160         @since OOo 2.2
 161     */
 162     void    registerControlObserver( [in] XPropertyControlObserver Observer );
 163
 164     /** revokes a previously registered control observer
 165
 166         @see registerControlObserver
 167
 168         @since OOo 2.2
 169     */
 170     void    revokeControlObserver( [in] XPropertyControlObserver Observer );
 171
 172     /** sets the text of the help section, if the object inspector contains
 173         one.
 174
 175         @throws NoSupportException
 176             if the <member>XObjectInspectorModel::HasHelpSection</member> property
 177             requires the help section to be unavailable.
 178
 179         @since OOo 2.2
 180     */
 181     void setHelpSectionText( [in] string HelpText )
 182         raises ( ::com::sun::star::lang::NoSupportException );
 183 };
 184
 185 //=============================================================================
 186
 187 }; }; }; };
 188
 189 #endif
 190