include/svx/DescriptionGenerator.hxx

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