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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_inspection_XObjectInspectorUI_idl__
  20 #define __com_sun_star_inspection_XObjectInspectorUI_idl__
  21
  22 #include <com/sun/star/inspection/XPropertyControl.idl>
  23 #include <com/sun/star/beans/Optional.idl>
  24 #include <com/sun/star/container/NoSuchElementException.idl>
  25 #include <com/sun/star/lang/NoSupportException.idl>
  26
  27 module com {  module sun {  module star {  module inspection {
  28
  29 interface XPropertyControlObserver;
  30
  31 /** grants access to certain aspects of the user interface of an object
  32     inspector
  33
  34     <p>This interface is used as callback for XPropertyHandlers.</p>
  35
  36     <p>As a consequence, methods operating on the UI for a property, and taking the name of this property,
  37     are tolerant against properties which do not exist. For instance, if a property handler tries to
  38     disable the UI for property <code>Foo</code>, but another handler has superseded this property, then
  39     the ObjectInspector will not <em>have</em> any UI for it. In this case, the call to
  40     <code>enablePropertyUI( "Foo" )</code> will simply be ignored.</p>
  41
  42     @since OOo 2.0.3
  43 */
  44 interface XObjectInspectorUI
  45 {
  46     /** enables or disables all components belonging to the UI representation of a property
  47
  48         <p>This is usually used by an XPropertyHandler if it handles properties,
  49         where one does only make sense if another one has a certain value.</p>
  50
  51         @param  PropertyName
  52             denotes the name of the property whose UI is to be enabled or disabled.
  53         @param  Enable
  54             `TRUE` if and only if the UI should be disabled, `FALSE` otherwise.
  55     */
  56     void    enablePropertyUI( [in] string PropertyName, [in] boolean Enable );
  57
  58     /** enables or disables the single elements which can be part of the UI representation of a property
  59
  60         <p>Note that the complete UI for the property must be enabled in order for these settings to
  61         be evaluated. That is, enablePropertyUIElements() does not have any effect if
  62         somebody previously disabled the complete UI for this property with enablePropertyUI().</p>
  63
  64         @param  PropertyName
  65             the name of the property whose user interface elements are to be enabled or disabled
  66
  67         @param  Elements
  68             a combination of PropertyLineElement flags specifying which elements are to be
  69             enabled or disabled.<br/>
  70             Note that if you don't set a particular bit here (say, PropertyLineElement::PrimaryButton),
  71             this does mean that this element's state is not affected by the call - it does
  72             <em>not</em> mean that it is disabled.
  73         @param  Enable
  74             `TRUE` if the elements denoted by _nElements should be enabled, `FALSE` if
  75             they should be disabled.
  76     */
  77     void    enablePropertyUIElements(
  78                         [in] string PropertyName,
  79                         [in] short Elements,
  80                         [in] boolean Enable
  81                     );
  82
  83     /** completely rebuilds the UI for the given property.
  84
  85         <p>This method might be used by an XPropertyHandler if it wants to change the type
  86         of control (see PropertyControlType) used to display a certain property.</p>
  87
  88         <p>The object inspector will then call describePropertyLine again, and update its UI accordingly.</p>
  89
  90         <p>Note that the property whose UI should be rebuilt must not necessarily be (though usually <em>is</em>)
  91         in the responsibility of the handler which calls this method. The object inspector will look up the
  92         handler with the responsibility for PropertyName and call its
  93         XPropertyHandler::describePropertyLine()</p>
  94
  95         @param PropertyName
  96             the name of the property whose UI is to be completely rebuilt.
  97     */
  98     void    rebuildPropertyUI( [in] string PropertyName );
  99
 100     /** shows the UI for a given property
 101
 102         @param  PropertyName
 103             the name of the property whose UI is to be shown
 104     */
 105     void    showPropertyUI( [in] string PropertyName );
 106
 107     /** hides the UI for a given property
 108
 109         @param  PropertyName
 110             the name of the property whose UI is to be hidden
 111     */
 112     void    hidePropertyUI( [in] string PropertyName );
 113
 114     /** shows or hides all properties belonging to a given category
 115         @see LineDescriptor::Category
 116         @see XObjectInspectorModel::describeCategories
 117     */
 118     void    showCategory( [in] string Category, [in] boolean Show );
 119
 120     /** retrieves the control currently used to display a given property
 121
 122         @param PropertyName
 123             the name of the property whose control should be retrieved
 124
 125         @return
 126             the XPropertyControl representing the given property, or `NULL`
 127             if there is no such property control.
 128     */
 129     XPropertyControl
 130             getPropertyControl( [in] string PropertyName );
 131
 132     /** registers an observer for all property controls
 133
 134         <p>The given XPropertyControlObserver will be notified of all changes
 135         in all property controls.</p>
 136
 137         @see revokeControlObserver
 138
 139         @since OOo 2.2
 140     */
 141     void    registerControlObserver( [in] XPropertyControlObserver Observer );
 142
 143     /** revokes a previously registered control observer
 144
 145         @see registerControlObserver
 146
 147         @since OOo 2.2
 148     */
 149     void    revokeControlObserver( [in] XPropertyControlObserver Observer );
 150
 151     /** sets the text of the help section, if the object inspector contains
 152         one.
 153
 154         @throws NoSupportException
 155             if the XObjectInspectorModel::HasHelpSection property
 156             requires the help section to be unavailable.
 157
 158         @since OOo 2.2
 159     */
 160     void setHelpSectionText( [in] string HelpText )
 161         raises ( ::com::sun::star::lang::NoSupportException );
 162 };
 163
 164
 165 }; }; }; };
 166
 167 #endif
 168
 169 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */