offapi/com/sun/star/inspection/LineDescriptor.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
  28 #ifndef __com_sun_star_inspection_LineDescriptor_idl__
  29 #define __com_sun_star_inspection_LineDescriptor_idl__
  30
  31 #ifndef com_sun_star_graphic_XGraphic_idl
  32 #include <com/sun/star/graphic/XGraphic.idl>
  33 #endif
  34
  35 //=============================================================================
  36 module com {  module sun {  module star {  module inspection {
  37
  38 interface XPropertyControl;
  39
  40 //-----------------------------------------------------------------------------
  41 /** describes the appearance of a line representing a single property in an <type>ObjectInspector</type>.
  42
  43     Such a line consists of
  44     <ul><li>a label with a human-readable name for the property</li>
  45         <li>a control which is used for user interaction - i.e. it displays the current property
  46             value, and allows the user entering a new one.</li>
  47         <li>(optional) one or two buttons which, when clicked, can start a more complex, interactive
  48             property value input. For instance, if you have a property whose value is a path in the
  49             file system, such a button could be used to let the user browse for a path with a
  50             usual file picker.</li>
  51     </ul>
  52
  53     @see XPropertyHandler::describePropertyLine
  54     @see PropertyLineElement
  55
  56     @since OOo 2.0.3
  57 */
  58 struct LineDescriptor
  59 {
  60     /** denotes the human-readable display name used to present a property to the user
  61     */
  62     string  DisplayName;
  63
  64     /** denotes the control which should be used to represent the property at the UI.
  65
  66         @see XPropertyControlFactory
  67     */
  68     XPropertyControl Control;
  69
  70     /** specifies the URL to the help topic to be associated with the property
  71     */
  72     string HelpURL;
  73
  74     /** detetrmines whether a button exists which can be used for a more complex, interactive
  75         property value input.
  76
  77         <p>If no image for the primary button is specified, but a primary button is present,
  78         the three dots will be displayed on the button.</p>
  79
  80         @see XPropertyHandler::onInteractivePropertySelection
  81         @see HasSecondaryButton
  82         @see PrimaryButtonImageURL
  83         @see PrimaryButtonImage
  84     */
  85     boolean HasPrimaryButton;
  86
  87     /** describes a unique id to associate with the primary button
  88
  89         <p>In OpenOffice.org, UI elements sometimes require a so-called UniqueID, which can be
  90         used to uniquely (within the whole application) identify this UI element. For instance,
  91         automating the OpenOffice.org UI via a dedicated separate application ("TestTool") requires
  92         such IDs.</p>
  93
  94         <p>If a primary button exists for a property's UI representation (<member>HasPrimaryButton</member>),
  95         it gets the ID specified herein.</p>
  96     */
  97     long PrimaryButtonId;
  98
  99     /** describes the URL of an image to display on the primary button, if any.
 100
 101         <p>This URL will be used to obtain an actual <type scope="com::sun::star::graphic">XGraphic</type>
 102         object from an <type scope="com::sun::star::graphic">GraphicProvider</type>.</p>
 103
 104         <p>The property will be ignored if <member>HasPrimaryButton</member> is <FALSE/>.</p>
 105
 106         <p>If you need to specify a graphic which does not have an URL, but is available as
 107         <type scope="com::sun::star::graphic">XGraphic</type> only, then you must leave
 108         <code>PrimaryButtonImageURL</code> empty, and use the <member>PrimaryButtonImage</member> property.
 109
 110         @see PrimaryButtonImage
 111     */
 112     string  PrimaryButtonImageURL;
 113
 114     /** describes a graphics to display at the primary button, if any.
 115
 116         <p>The property will be ignored if <member>HasPrimaryButton</member> is <FALSE/>, or
 117         if <member>PrimaryButtonImageURL</member> is a non-empty string.</p>
 118
 119         @see HasPrimaryButton
 120         @see PrimaryButtonImageURL
 121     */
 122     com::sun::star::graphic::XGraphic PrimaryButtonImage;
 123
 124     /** detetrmines whether a secondary button exists which can be used for a more complex, interactive
 125         property value input.
 126
 127         <p>A secondary button subordinated to the primary button. If no primary button exists
 128         (<member>HasPrimaryButton</member>), this member is ignored.</p>
 129
 130         @see XPropertyHandler::onInteractivePropertySelection
 131         @see HasSecondaryButton
 132     */
 133     boolean HasSecondaryButton;
 134
 135     /** describes a unique id to associate with the primary button
 136
 137         <p>If a secondary button exists for a property's UI representation (<member>HasSecondaryButton</member>),
 138         it gets the ID specified herein.</p>
 139
 140         @see PrimaryButtonId
 141     */
 142     long SecondaryButtonId;
 143
 144     /** describes the URL of an image to display on the secondary button, if any.
 145
 146         <p>This URL will be used to obtain an actual <type scope="com::sun::star::graphic">XGraphic</type>
 147         object from an <type scope="com::sun::star::graphic">GraphicProvider</type>.</p>
 148
 149         <p>The property will be ignored if <member>HasSecondaryButton</member> is <FALSE/>.</p>
 150
 151         <p>If you need to specify a graphic which does not have an URL, but is available as
 152         <type scope="com::sun::star::graphic">XGraphic</type> only, then you must leave
 153         <code>SecondaryButtonImageURL</code> empty, and use the <member>SecondaryButtonImage</member> property.
 154
 155         @see SecondaryButtonImage
 156     */
 157     string  SecondaryButtonImageURL;
 158
 159     /** describes a graphics to display at the secondary button, if any.
 160
 161         <p>The property will be ignored if <member>HasSecondaryButton</member> is <FALSE/>, or
 162         if <member>SecondaryButtonImageURL</member> is a non-empty string.</p>
 163
 164         @see HasSecondaryButton
 165         @see SecondaryButtonImageURL
 166     */
 167     com::sun::star::graphic::XGraphic SecondaryButtonImage;
 168
 169     /** describes the indent level for the property
 170
 171         <p>If a given property semantically depends on another one, the indent level
 172         can be used to visually represent this fact. For this, the dependent property's
 173         indent level would be one larger than the indent level of the other property.</p>
 174
 175         <p>Normally, <type>XPropertyHandler</type>s will set this to <code>0</code> when describing
 176         the UI for a normal property.
 177     */
 178     short IndentLevel;
 179
 180     /** describes the category into which the property should be sorted by the <type>ObjectInspector</type>.
 181
 182         <p>An <type>ObjectInspector</type> can visually group properties which semantically belong
 183         together (for instance using tab pages). The decision which properties actually belong together
 184         is made using this <member>Category</member> attribute.</p>
 185
 186         <p>For your implementation of <type>XPropertyHandler</type>, it's recommended that you document the programmatic
 187         names used for property categories. This way, your handler might be re-used in
 188         different contexts, where only the <type>XObjectInspectorModel</type> needs to provide consistent
 189         UI names for the categories.</p>
 190
 191         @see XObjectInspectorModel::describeCategories
 192     */
 193     string Category;
 194 };
 195
 196 //=============================================================================
 197
 198 }; }; }; };
 199
 200 #endif
 201