include/editeng/AccessibleContextBase.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 #ifndef INCLUDED_EDITENG_ACCESSIBLECONTEXTBASE_HXX
  21 #define INCLUDED_EDITENG_ACCESSIBLECONTEXTBASE_HXX
  22
  23 #include <com/sun/star/accessibility/XAccessible.hpp>
  24 #include <com/sun/star/accessibility/XAccessibleContext.hpp>
  25 #include <com/sun/star/accessibility/XAccessibleEventBroadcaster.hpp>
  26 #include <com/sun/star/uno/Reference.hxx>
  27 #include <com/sun/star/lang/XServiceInfo.hpp>
  28 #include <cppuhelper/compbase.hxx>
  29 #include <cppuhelper/basemutex.hxx>
  30 #include <editeng/editengdllapi.h>
  31 #include <rtl/ref.hxx>
  32
  33 namespace com::sun::star::accessibility { class XAccessibleRelationSet; }
  34 namespace com::sun::star::accessibility { struct AccessibleEventObject; }
  35
  36 namespace accessibility {
  37
  38 /** @descr
  39         This base class provides an implementation of the
  40         AccessibleContext service. Apart from the
  41         <type>XXAccessible<type> and XAccessibleContextContext
  42         interfaces it supports the XServiceInfo interface.
  43 */
  44 class EDITENG_DLLPUBLIC AccessibleContextBase
  45     :   public cppu::BaseMutex,
  46         public cppu::WeakComponentImplHelper<
  47         css::accessibility::XAccessible,
  48         css::accessibility::XAccessibleContext,
  49         css::accessibility::XAccessibleEventBroadcaster,
  50         css::lang::XServiceInfo
  51         >
  52 {
  53 public:
  54
  55     //=====  internal  ========================================================
  56
  57     /** The origin of the accessible name or description.
  58     */
  59     enum StringOrigin {
  60         ManuallySet,
  61         FromShape,
  62         AutomaticallyCreated,
  63         NotSet
  64     };
  65
  66     AccessibleContextBase (
  67         css::uno::Reference< css::accessibility::XAccessible> xParent,
  68         const sal_Int16 aRole);
  69     virtual ~AccessibleContextBase() override;
  70
  71
  72     /** Call all accessibility event listeners to inform them about the
  73         specified event.
  74         @param aEventId
  75             Id of the event type.
  76         @param rNewValue
  77             New value of the modified attribute.  Pass empty structure if
  78             not applicable.
  79         @param rOldValue
  80             Old value of the modified attribute.  Pass empty structure if
  81             not applicable.
  82     */
  83     void CommitChange (sal_Int16 aEventId,
  84         const css::uno::Any& rNewValue,
  85         const css::uno::Any& rOldValue,
  86         sal_Int32 nValueIndex);
  87
  88     /** Set a new description and, provided that the new name differs from
  89         the old one, broadcast an accessibility event.
  90         @param rsDescription
  91             The new description.
  92         @param eDescriptionOrigin
  93             The origin of the description.  This is used to determine
  94             whether the given description overrules the existing one.  An
  95             origin with a lower numerical value overrides one with a higher
  96             value.
  97         @throws css::uno::RuntimeException
  98     */
  99     void SetAccessibleDescription (
 100         const OUString& rsDescription,
 101         StringOrigin eDescriptionOrigin);
 102
 103     /** Set a new description and, provided that the new name differs from
 104         the old one, broadcast an accessibility event.
 105         @param rsName
 106             The new name.
 107         @param eNameOrigin
 108             The origin of the name.  This is used to determine whether the
 109             given name overrules the existing one.  An origin with a lower
 110             numerical value overrides one with a higher value.
 111         @throws css::uno::RuntimeException
 112     */
 113     void SetAccessibleName (
 114         const OUString& rsName,
 115         StringOrigin eNameOrigin);
 116
 117     /** Set the specified state (turn it on) and send events to all
 118         listeners to inform them of the change.
 119
 120         @param aState
 121             The state to turn on.
 122
 123         @return
 124             If the specified state changed its value due to this call
 125             <TRUE/> is returned, otherwise <FALSE/>.
 126     */
 127     virtual bool SetState (sal_Int64 aState);
 128
 129     /** Reset the specified state (turn it off) and send events to all
 130         listeners to inform them of the change.
 131
 132         @param aState
 133             The state to turn off.
 134
 135         @return
 136             If the specified state changed its value due to this call
 137             <TRUE/> is returned, otherwise <FALSE/>.
 138     */
 139     virtual bool ResetState (sal_Int64 aState);
 140
 141     /** Return the state of the specified state.
 142
 143         @param aState
 144             The state for which to return its value.
 145
 146         @return
 147             A value of <TRUE/> indicates that the state is set.  A <FALSE/>
 148             value indicates an unset state.
 149     */
 150     bool GetState (sal_Int64 aState);
 151
 152     /** Replace the current relation set with the specified one.  Send
 153         events for relations that are not in both sets.
 154
 155         @param rRelationSet
 156             The new relation set that replaces the old one.
 157
 158         @throws css::uno::RuntimeException
 159     */
 160     void SetRelationSet (
 161         const css::uno::Reference< css::accessibility::XAccessibleRelationSet>& rxRelationSet);
 162
 163
 164     //=====  XAccessible  =====================================================
 165
 166     /// Return the XAccessibleContext.
 167     virtual css::uno::Reference< css::accessibility::XAccessibleContext> SAL_CALL
 168         getAccessibleContext() override;
 169
 170
 171     //=====  XAccessibleContext  ==============================================
 172
 173     /// Return the number of currently visible children.
 174     virtual sal_Int64 SAL_CALL
 175         getAccessibleChildCount() override;
 176
 177     /// Return the specified child or throw exception.
 178     virtual css::uno::Reference< css::accessibility::XAccessible> SAL_CALL
 179         getAccessibleChild (sal_Int64 nIndex) override;
 180
 181     /// Return a reference to the parent.
 182     virtual css::uno::Reference< css::accessibility::XAccessible> SAL_CALL
 183         getAccessibleParent() override;
 184
 185     /// Return this objects index among the parents children.
 186     virtual sal_Int64 SAL_CALL
 187         getAccessibleIndexInParent() override;
 188
 189     /// Return this object's role.
 190     virtual sal_Int16 SAL_CALL
 191         getAccessibleRole() override;
 192
 193     /// Return this object's description.
 194     virtual OUString SAL_CALL
 195         getAccessibleDescription() override;
 196
 197     /// Return the object's current name.
 198     virtual OUString SAL_CALL
 199         getAccessibleName() override;
 200
 201     /// Return NULL to indicate that an empty relation set.
 202     virtual css::uno::Reference< css::accessibility::XAccessibleRelationSet> SAL_CALL
 203         getAccessibleRelationSet() override;
 204
 205     /// Return the set of current states.
 206     virtual sal_Int64 SAL_CALL getAccessibleStateSet() override;
 207
 208     /** Return the parents locale or throw exception if this object has no
 209         parent yet/anymore.
 210     */
 211     virtual css::lang::Locale SAL_CALL
 212         getLocale() override;
 213
 214     //=====  XAccessibleEventBroadcaster  ========================================
 215
 216     virtual void SAL_CALL
 217         addAccessibleEventListener (
 218             const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener) override;
 219
 220     virtual void SAL_CALL
 221         removeAccessibleEventListener (
 222             const css::uno::Reference< css::accessibility::XAccessibleEventListener >& xListener) override;
 223
 224
 225     //=====  XServiceInfo  ====================================================
 226
 227     /** Returns an identifier for the implementation of this object.
 228     */
 229     virtual OUString SAL_CALL
 230         getImplementationName() override;
 231
 232     /** Return whether the specified service is supported by this class.
 233     */
 234     virtual sal_Bool SAL_CALL
 235         supportsService (const OUString& sServiceName) override;
 236
 237     /** Returns a list of all supported services.  In this case that is just
 238         the AccessibleContext service.
 239     */
 240     virtual css::uno::Sequence< OUString> SAL_CALL
 241         getSupportedServiceNames() override;
 242
 243
 244     //=====  XTypeProvider  ===================================================
 245
 246     /** Returns an implementation id.
 247     */
 248     virtual css::uno::Sequence<sal_Int8> SAL_CALL
 249         getImplementationId() override;
 250
 251     /** Check whether or not the object has been disposed (or is in the
 252         state of being disposed).
 253
 254         @return TRUE, if the object is disposed or in the course
 255         of being disposed. Otherwise, FALSE is returned.
 256     */
 257     bool IsDisposed() const;
 258
 259 protected:
 260     /** The state set.
 261     */
 262     sal_Int64 mnStateSet;
 263
 264     /** The relation set.  Relations can be set or removed by calling the
 265         <member>AddRelation</member> and <member>RemoveRelation</member> methods.
 266     */
 267     css::uno::Reference< css::accessibility::XAccessibleRelationSet> mxRelationSet;
 268
 269     // This method is called from the component helper base class while disposing.
 270     virtual void SAL_CALL disposing() override;
 271
 272     /** Create the accessible object's name.  This method may be called more
 273         than once for a single object.
 274         @return
 275             The returned string is a unique (among the accessible object's
 276             siblings) name.
 277         @throws css::uno::RuntimeException
 278     */
 279     virtual OUString CreateAccessibleName();
 280
 281     void FireEvent (const css::accessibility::AccessibleEventObject& aEvent);
 282
 283     /** Check whether or not the object has been disposed (or is in the
 284         state of being disposed).  If that is the case then
 285         DisposedException is thrown to inform the (indirect) caller of the
 286         foul deed.
 287         @throws css::lang::DisposedException
 288     */
 289     void ThrowIfDisposed();
 290
 291     /** sets the role as returned by XaccessibleContext::getAccessibleRole
 292
 293         <p>Caution: This is only to be used in the construction phase (means within
 294         the ctor or late ctor), <em>never</em> when the object is still alive and part
 295         of an Accessibility hierarchy.</p>
 296     */
 297     void SetAccessibleRole( sal_Int16 _nRole );
 298
 299 private:
 300     /// Reference to the parent object.
 301     css::uno::Reference< css::accessibility::XAccessible> mxParent;
 302
 303     /** Description of this object.  This is not a constant because it can
 304         be set from the outside.  Furthermore, it changes according to the
 305         draw page's display mode.
 306     */
 307     OUString msDescription;
 308
 309     /** The origin of the description is used to determine whether new
 310         descriptions given to the SetAccessibleDescription is ignored or
 311         whether that replaces the old value in msDescription.
 312     */
 313     StringOrigin meDescriptionOrigin;
 314
 315     /** Name of this object.  It changes according the draw page's
 316         display mode.
 317     */
 318     OUString msName;
 319
 320     /** The origin of the name is used to determine whether new
 321         name given to the SetAccessibleName is ignored or
 322         whether that replaces the old value in msName.
 323     */
 324     StringOrigin meNameOrigin;
 325
 326     /** client id in the AccessibleEventNotifier queue
 327     */
 328     sal_uInt32 mnClientId;
 329
 330     /** This is the role of this object.
 331     */
 332     sal_Int16 maRole;
 333 };
 334
 335 }
 336
 337 #endif
 338
 339 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */