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