svx/inc/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 #pragma once
  21
  22 #include <com/sun/star/uno/Reference.hxx>
  23 #include <rtl/ustrbuf.hxx>
  24
  25 namespace com::sun::star::beans
  26 {
  27 class XPropertySet;
  28 }
  29 namespace com::sun::star::drawing
  30 {
  31 class XShape;
  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 DescriptionGenerator
  44 {
  45 public:
  46     enum class PropertyType
  47     {
  48         Color,
  49         Integer
  50     };
  51
  52     /** Creates a new description generator with an empty description
  53         string.  Usually you will want to call initialize next to specify
  54         a general description of the shape.
  55         @param xShape
  56             The shape from which properties will be extracted by later calls
  57             to <member>addProperty</member>.
  58     */
  59     DescriptionGenerator(const css::uno::Reference<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     */
 100     void AddProperty(const OUString& sPropertyName, PropertyType aType);
 101
 102     /** Append the given string as is to the current description.
 103         @param sString
 104             String to append to the current description.  It is not modified
 105             in any way.
 106     */
 107     void AppendString(std::u16string_view sString);
 108
 109 private:
 110     /// Reference to the shape from which the properties are extracted.
 111     css::uno::Reference<css::drawing::XShape> mxShape;
 112
 113     /// Reference to the shape's property set.
 114     css::uno::Reference<css::beans::XPropertySet> mxSet;
 115
 116     /// The description string that is build.
 117     OUStringBuffer msDescription;
 118
 119     /** This flag is used to determine whether to insert a separator e.g. a
 120         comma before the next property.
 121     */
 122     bool mbIsFirstProperty;
 123
 124     /** Add a property value formatted as color to the description string.
 125     */
 126     void AddColor(const OUString& sPropertyName);
 127
 128     /** Add a property value formatted as integer to the description string.
 129     */
 130     void AddInteger(const OUString& sPropertyName);
 131 };
 132
 133 } // end of namespace accessibility
 134
 135 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */