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