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