svx/inc/DescriptionGenerator.hxx

   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: DescriptionGenerator.hxx,v $
  10  * $Revision: 1.6 $
  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
  32 #ifndef _SVX_ACCESSIBILITY_DESCRIPTION_GENERATOR_HXX
  33 #define _SVX_ACCESSIBILITY_DESCRIPTION_GENERATOR_HXX
  34
  35 #include <com/sun/star/drawing/XShape.hpp>
  36 #include <com/sun/star/beans/XPropertySet.hpp>
  37 #include <rtl/ustrbuf.hxx>
  38 #include "svx/svxdllapi.h"
  39
  40
  41 namespace accessibility {
  42
  43 /** This class creates description strings for shapes.
  44     <p>Initialized with a given shape additional calls to the
  45     <member>addProperty</member> method will build a descriptive string that
  46     starts with a general shape description and the shapes style.  Appended
  47     are all the specified property names and values that differ from the
  48     default values in the style.</p>
  49 */
  50 class SVX_DLLPUBLIC DescriptionGenerator
  51 {
  52 public:
  53     enum PropertyType {
  54         COLOR,
  55         INTEGER,
  56         STRING,
  57         FILL_STYLE
  58     };
  59
  60     /** Creates a new description generator with an empty description
  61         string.  Usually you will want to call initialize next to specifiy
  62         a general description of the shape.
  63         @param xShape
  64             The shape from which properties will be extracted by later calls
  65             to <member>addProperty</member>.
  66     */
  67     DescriptionGenerator (const ::com::sun::star::uno::Reference<
  68         ::com::sun::star::drawing::XShape>& xShape);
  69
  70     ~DescriptionGenerator (void);
  71
  72     /** Initialize the description with the given prefix followed by the
  73         shape's style in parantheses and a colon.
  74         @param sPrefix
  75             An introductory description of the shape that is made more
  76             specific by later calls to <member>addProperty</member>.
  77     */
  78     void Initialize (::rtl::OUString sPrefix);
  79
  80     /** Initialize the description with the specified string from the
  81         resource followed by the shape's style in parantheses and a colon.
  82         @param nResourceId
  83             A resource id the specifies the introductory description of the
  84             shape that is made more specific by later calls to
  85             <member>addProperty</member>.
  86     */
  87     void Initialize (sal_Int32 nResourceId);
  88
  89     /**  Returns the description string and then resets it.  Usually called
  90          as last method before destroying the object.
  91          @return
  92              The description string in its current form.
  93     */
  94     ::rtl::OUString operator() (void);
  95
  96     /** Add the given property name and its associated value to the
  97         description string.  If the property value does not differ from the
  98         default value of the shape's style then the description string is
  99         not modified.
 100         @param sPropertyName
 101             The Name of the property to append.
 102         @param aType
 103             Type of the property's value.  It controls the transformation
 104             into the value's string representation.
 105         @param sLocalizedName
 106             Localized name of the property.  An empty string tells the
 107             method to use the property name instead.
 108         @param nWhichId
 109             This which id is used to localize the property value.  If it is
 110             not known a value of -1 signals to use a default representation.
 111     */
 112     void AddProperty (const ::rtl::OUString& sPropertyName,
 113         PropertyType aType,
 114         const ::rtl::OUString& sLocalizedName=::rtl::OUString(),
 115         long nWhichId=-1);
 116
 117     /** Add the given property name and its associated value to the
 118         description string.  If the property value does not differ from the
 119         default value of the shape's style then the description string is
 120         not modified.  This method forwards the request to its cousing but
 121         first replaces the id of the localized name by the associated string
 122         from the resource.
 123         @param sPropertyName
 124             The Name of the property to append.
 125         @param aType
 126             Type of the property's value.  It controls the transformation
 127             into the value's string representation.
 128         @param nResourceId
 129             Id of the kocalized name of the property int the resource.
 130         @param nWhichId
 131             This which id is used to localize the property value.  If it is
 132             not known a value of -1 signals to use a default representation.
 133     */
 134     void AddProperty (const ::rtl::OUString& sPropertyName,
 135         PropertyType aType,
 136         sal_Int32 nResourceId,
 137         long nWhichId=-1);
 138
 139     /** Append the given string as is to the current description.
 140         @param sString
 141             String to append to the current description.  It is not modified
 142             in any way.
 143     */
 144     void AppendString (const ::rtl::OUString& sString);
 145
 146     /** This method adds for debuging and development the list of all known
 147         properties to the description.   Don't use in production code.
 148     */
 149     void AddPropertyNames (void);
 150
 151     /** Add properties that describe line and border attributes.
 152     */
 153     void AddLineProperties (void);
 154
 155     /** Add properties that describe how areas are filled.
 156     */
 157     void AddFillProperties (void);
 158
 159     /** Add properties that describesattributes of 3D objects.
 160     */
 161     void Add3DProperties (void);
 162
 163     /** Add properties that describe text attributes.
 164     */
 165     void AddTextProperties (void);
 166
 167 private:
 168     /// Reference to the shape from which the properties are extracted.
 169     ::com::sun::star::uno::Reference< ::com::sun::star::drawing::XShape> mxShape;
 170
 171     /// Reference to the shape's property set.
 172     ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet> mxSet;
 173
 174     /// The description string that is build.
 175     ::rtl::OUStringBuffer msDescription;
 176
 177     /** This flag is used to determine whether to insert a separator e.g. a
 178         comma before the next property.
 179     */
 180     bool mbIsFirstProperty;
 181
 182     /** Add a property value formated as color to the description string.
 183     */
 184     SVX_DLLPRIVATE void AddColor (const ::rtl::OUString& sPropertyName,
 185         const ::rtl::OUString& sLocalizedName);
 186
 187     /** Add a property value of unknown type to the description string.
 188     */
 189     SVX_DLLPRIVATE void AddUnknown (const ::rtl::OUString& sPropertyName,
 190         const ::rtl::OUString& sLocalizedName);
 191
 192     /** Add a property value formated as integer to the description string.
 193     */
 194     SVX_DLLPRIVATE void AddInteger (const ::rtl::OUString& sPropertyName,
 195         const ::rtl::OUString& sLocalizedName);
 196
 197     /** Add a property value formated as string to the description string.
 198         @param sPropertyName
 199             Name of the property.
 200     */
 201     SVX_DLLPRIVATE void AddString (const ::rtl::OUString& sPropertyName,
 202         const ::rtl::OUString& sLocalizedName, long nWhichId = -1);
 203
 204     /** Add a property value formated as fill style to the description
 205         string.  If the fill style is <const>HATCH</const>,
 206         <const>GRADIENT</const>, or <const>BITMAP</const>, then the of the
 207         hatch, gradient, or bitmap is appended as well.
 208         @param sPropertyName
 209             Name of the property.  Usually this will be "FillStyle".
 210     */
 211     SVX_DLLPRIVATE void AddFillStyle (const ::rtl::OUString& sPropertyName,
 212         const ::rtl::OUString& sLocalizedName);
 213 };
 214
 215
 216 } // end of namespace accessibility
 217
 218
 219 #endif
 220