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

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