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