include/svx/AccessibleShape.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_ACCESSIBLESHAPE_HXX
  22 #define INCLUDED_SVX_ACCESSIBLESHAPE_HXX
  23
  24 #include <editeng/AccessibleContextBase.hxx>
  25 #include <editeng/AccessibleComponentBase.hxx>
  26 #include <svx/IAccessibleViewForwarderListener.hxx>
  27 #include <com/sun/star/document/XEventListener.hpp>
  28 #include <com/sun/star/accessibility/XAccessible.hpp>
  29 #include <com/sun/star/accessibility/XAccessibleExtendedComponent.hpp>
  30 #include <com/sun/star/accessibility/AccessibleRole.hpp>
  31 #include <com/sun/star/drawing/XShape.hpp>
  32 #include <com/sun/star/lang/XEventListener.hpp>
  33 #include <com/sun/star/lang/XUnoTunnel.hpp>
  34 #include <svx/AccessibleTextHelper.hxx>
  35 #include <svx/svxdllapi.h>
  36 #include <svx/ChildrenManager.hxx>
  37
  38 class SdrObject;
  39
  40 namespace accessibility {
  41
  42 class AccessibleShapeInfo;
  43 class AccessibleShapeTreeInfo;
  44 class IAccessibleParent;
  45
  46 /** This base class provides a base implementation for all shapes.  For more
  47     detailed documentation about the methods refer to the descriptions of
  48     the implemented interfaces.  These are, among others,
  49     XAccessible, <type>XAccessibleContext</type>,
  50     XAccessibleComponent and
  51     XAccessibleExtendedComponent.
  52
  53     <p>The children of a shape can stem from two sources which, in case of
  54     SVX and SD shapes, are mutually exclusive.  This implementation,
  55     however, handles both simultaniously to cope with future extensions or
  56     shapes from other projects.
  57     <ul>
  58         <li>If this shape is a group shape, i.e. a
  59         SvxShapeGroup or a <type>Svx3DSceneObject</type>, it
  60         can have nested shapes.</li>
  61         <li>If this shape is a descendant from SvxShapeText
  62         then the text paragraphs are its children.</li>
  63     </ul>
  64     </p>
  65
  66     <p>Accessible shapes do not listen for disposing() calls of the UNO
  67     shapes they make accessible.  This is the task of their owner, usually a
  68     container, who can then call dispose() at the accessible object.</p>
  69 */
  70 class SVX_DLLPUBLIC AccessibleShape
  71     :   public AccessibleContextBase,
  72         public AccessibleComponentBase,
  73         public IAccessibleViewForwarderListener,
  74         public ::com::sun::star::document::XEventListener,
  75         public ::com::sun::star::lang::XUnoTunnel
  76 {
  77 public:
  78     //=====  internal  ========================================================
  79
  80     /** Create a new accessible object that makes the given shape accessible.
  81         @param rShapeInfo
  82             This object contains all information specific to the new
  83             accessible shape.  That are e.g. the shape to be made accessible
  84             and the accessible object that will become the parent of the new
  85             object.
  86         @param rShapeTreeInfo
  87             Bundel of information passed to this shape and all of its desendants.
  88         @attention
  89             Always call the <member>init</member> method after creating a
  90             new accessible shape.  This is one way to overcome the potential
  91             problem of registering the new object with e.g. event
  92             broadcasters.  That would delete the new object if a broadcaster
  93             would not keep a strong reference to the new object.
  94     */
  95     AccessibleShape (
  96         const AccessibleShapeInfo& rShapeInfo,
  97         const AccessibleShapeTreeInfo& rShapeTreeInfo);
  98
  99     /** The destructor releases its children manager and text engine if
 100         still existent.  These are responsible to send appropriate events.
 101     */
 102     virtual ~AccessibleShape (void);
 103
 104     /** Initialize a new shape.  See the documentation of the constructor
 105         for the reason of this method's existence.
 106     */
 107     virtual void Init (void);
 108
 109     /** Compare two accessible shapes using object identity
 110         @param rShape
 111             This is the second operand.
 112         @return
 113             Returns true if both shapes are the same object.
 114     */
 115     virtual bool operator== (const AccessibleShape& rShape);
 116
 117     /** Set the specified state.  If the state is <const>FOCUSED</const>
 118         then, additionally to the inherited functionality, the focus
 119         listeners registered with the XAccessibleComponent
 120         interface are called (if that state really changes).
 121
 122         @param aState
 123             The state to turn on.
 124
 125         @return
 126             The returned flag indicates whether the specified state has been
 127             changed (<TRUE/>), i.e. it has formerly not been set.
 128     */
 129     virtual sal_Bool SetState (sal_Int16 aState);
 130
 131     /** Reset the specified state.  If the state is <const>FOCUSED</const>
 132         then, additionally to the inherited functionality, the focus
 133         listeners registered with the XAccessibleComponent
 134         interface are called (if that state really changes).
 135
 136         @param aState
 137             The state to turn off.
 138
 139         @return
 140             The returned flag indicates whether the specified state has been
 141             changed (<TRUE/>), i.e. it has formerly been set.
 142     */
 143     virtual sal_Bool ResetState (sal_Int16 aState);
 144
 145     /** Return the state of the specified state.  Take the
 146         <const>FOCUSED</const> state from the accessible edit engine.
 147
 148         @param aState
 149             The state for which to return its value.
 150         @return
 151             A value of <TRUE/> indicates that the state is set.  A <FALSE/>
 152             value indicates an unset state or the inability to access the
 153             entity that manages the state set.
 154
 155     */
 156     sal_Bool GetState (sal_Int16 aState);
 157
 158
 159     //=====  XAccessibleContext  ==============================================
 160
 161     /// Return the number of currently visible children.
 162     virtual sal_Int32 SAL_CALL
 163         getAccessibleChildCount (void)
 164         throw (::com::sun::star::uno::RuntimeException);
 165
 166     /** Return the specified child.
 167         @param nIndex
 168             Index of the requested child.
 169         @return
 170             Reference of the requested child which is the accessible object
 171             of a visible shape.
 172         @raises IndexOutOfBoundsException
 173             Throws an exception if the index is not valid.
 174     */
 175     virtual ::com::sun::star::uno::Reference<
 176             ::com::sun::star::accessibility::XAccessible> SAL_CALL
 177         getAccessibleChild (sal_Int32 nIndex)
 178         throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException);
 179
 180
 181     /// Return the set of current states.
 182     virtual ::com::sun::star::uno::Reference<
 183             ::com::sun::star::accessibility::XAccessibleStateSet> SAL_CALL
 184         getAccessibleStateSet (void)
 185         throw (::com::sun::star::uno::RuntimeException);
 186
 187     /// Return this objects index among the parents children.
 188     virtual sal_Int32 SAL_CALL
 189         getAccessibleIndexInParent (void)
 190         throw (::com::sun::star::uno::RuntimeException);
 191
 192     //=====  XAccessibleComponent  ============================================
 193
 194     virtual ::com::sun::star::uno::Reference<
 195         ::com::sun::star::accessibility::XAccessible > SAL_CALL
 196         getAccessibleAtPoint (const ::com::sun::star::awt::Point& aPoint)
 197         throw (::com::sun::star::uno::RuntimeException);
 198
 199     virtual ::com::sun::star::awt::Rectangle SAL_CALL getBounds (void)
 200         throw (::com::sun::star::uno::RuntimeException);
 201
 202     virtual ::com::sun::star::awt::Point SAL_CALL getLocation (void)
 203         throw (::com::sun::star::uno::RuntimeException);
 204
 205     virtual ::com::sun::star::awt::Point SAL_CALL getLocationOnScreen (void)
 206         throw (::com::sun::star::uno::RuntimeException);
 207
 208     virtual ::com::sun::star::awt::Size SAL_CALL getSize (void)
 209         throw (::com::sun::star::uno::RuntimeException);
 210
 211     virtual sal_Int32 SAL_CALL getForeground (void)
 212         throw (::com::sun::star::uno::RuntimeException);
 213
 214     virtual sal_Int32 SAL_CALL getBackground (void)
 215         throw (::com::sun::star::uno::RuntimeException);
 216
 217     //=====  XAccessibleEventBroadcaster  =====================================
 218
 219     /** This call is forwarded to a) the base class and b) to the
 220         accessible edit engine if it is present.
 221
 222         @param rxListener
 223             This listener is informed about accessibility events.
 224     */
 225     virtual void SAL_CALL
 226         addAccessibleEventListener (
 227             const ::com::sun::star::uno::Reference<
 228             ::com::sun::star::accessibility::XAccessibleEventListener >& rxListener)
 229         throw (::com::sun::star::uno::RuntimeException);
 230
 231     /** This call is forwarded to a) the base class and b) to the
 232         accessible edit engine if it is present.
 233
 234         @param rxListener
 235             This listener will not be informed about accessibility events
 236             anymore.
 237     */
 238     virtual void SAL_CALL
 239         removeAccessibleEventListener (
 240             const ::com::sun::star::uno::Reference<
 241             ::com::sun::star::accessibility::XAccessibleEventListener >& rxListener)
 242         throw (::com::sun::star::uno::RuntimeException);
 243
 244
 245     //=====  XInterface  ======================================================
 246
 247     virtual com::sun::star::uno::Any SAL_CALL
 248         queryInterface (const com::sun::star::uno::Type & rType)
 249         throw (::com::sun::star::uno::RuntimeException);
 250
 251     virtual void SAL_CALL
 252         acquire (void)
 253         throw ();
 254
 255     virtual void SAL_CALL
 256         release (void)
 257         throw ();
 258
 259
 260     //=====  XServiceInfo  ====================================================
 261
 262     /** Returns an identifier for the implementation of this object.
 263     */
 264     virtual OUString SAL_CALL
 265         getImplementationName (void)
 266         throw (::com::sun::star::uno::RuntimeException);
 267
 268     virtual ::com::sun::star::uno::Sequence< OUString> SAL_CALL
 269         getSupportedServiceNames (void)
 270         throw (::com::sun::star::uno::RuntimeException);
 271
 272     //=====  XTypeProvider  ===================================================
 273
 274     virtual ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Type> SAL_CALL
 275         getTypes (void)
 276         throw (::com::sun::star::uno::RuntimeException);
 277
 278     //=====  IAccessibleViewForwarderListener  ================================
 279     virtual void ViewForwarderChanged (ChangeType aChangeType,
 280         const IAccessibleViewForwarder* pViewForwarder);
 281
 282     //=====  lang::XEventListener  ============================================
 283
 284     /** Listen for disposing events of the model.  The accessible shape
 285         remains functional when this happens.
 286     */
 287     virtual void SAL_CALL
 288         disposing (const ::com::sun::star::lang::EventObject& Source)
 289         throw (::com::sun::star::uno::RuntimeException);
 290
 291     //=====  document::XEventListener  ========================================
 292
 293     virtual void SAL_CALL
 294         notifyEvent (const ::com::sun::star::document::EventObject& rEventObject)
 295         throw (::com::sun::star::uno::RuntimeException);
 296
 297
 298     //===== XUnoTunnel ========================================================
 299
 300     static const ::com::sun::star::uno::Sequence< sal_Int8 >&   getUnoTunnelImplementationId() throw();
 301     static AccessibleShape*                                     getImplementation( const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxIFace ) throw();
 302     sal_Int64                                                   SAL_CALL getSomething( const ::com::sun::star::uno::Sequence< sal_Int8 >& _rIdentifier ) throw(::com::sun::star::uno::RuntimeException);
 303
 304     //===== Misc ========================================================
 305
 306     ::com::sun::star::uno::Reference< ::com::sun::star::drawing::XShape >
 307         GetXShape();
 308
 309     /** set the index _nIndex at the accessible shape
 310         @param  _nIndex
 311             The new index in parent.
 312     */
 313     inline void setIndexInParent(sal_Int32 _nIndex) { m_nIndexInParent = _nIndex; }
 314
 315 protected:
 316     /// Children manager. May be empty if there are no children.
 317     ChildrenManager* mpChildrenManager;
 318
 319     /// Reference to the actual shape.
 320     ::com::sun::star::uno::Reference<
 321         ::com::sun::star::drawing::XShape> mxShape;
 322
 323     /** Bundle of information passed to all shapes in a document tree.
 324     */
 325     AccessibleShapeTreeInfo maShapeTreeInfo;
 326
 327     /** Index that is appended to the object's name to disambiguate between
 328         different names with the otherwise same name.
 329     */
 330     long mnIndex;
 331
 332     /** the index in parent.
 333     */
 334     sal_Int32 m_nIndexInParent;
 335
 336     /** The accessible text engine.  May be NULL if it can not be created.
 337     */
 338     AccessibleTextHelper* mpText;
 339
 340     /** This object can be used to modify the child list of our parent.
 341     */
 342     IAccessibleParent* mpParent;
 343
 344     /** This object can be removed when we have an extra interface to ask if the shape is selected
 345     */
 346     SdrObject* m_pShape;
 347
 348     /** This method is called from the component helper base class while
 349         disposing.
 350     */
 351     virtual void SAL_CALL disposing (void);
 352
 353     /** Create a base name string that contains the accessible name.
 354     */
 355     virtual OUString
 356         CreateAccessibleBaseName (void)
 357         throw (::com::sun::star::uno::RuntimeException);
 358
 359     /** Create a unique name string that contains the accessible name.  The
 360         name consists of the base name and the index.
 361     */
 362     virtual OUString
 363         CreateAccessibleName (void)
 364         throw (::com::sun::star::uno::RuntimeException);
 365
 366     /// Create a description string that contains the accessible description.
 367     virtual OUString
 368         CreateAccessibleDescription (void)
 369         throw (::com::sun::star::uno::RuntimeException);
 370
 371     /** Update the <const>OPAQUE</const> and <const>SELECTED</const> state.
 372     */
 373     virtual void UpdateStates (void);
 374
 375 private:
 376     /** Don't use the default constructor.  Use the public constructor that
 377         takes the original shape and the parent as arguments instead.
 378     */
 379     SVX_DLLPRIVATE explicit AccessibleShape (void);
 380     /// Don't use the copy constructor.  Is there any use for it?
 381     SVX_DLLPRIVATE explicit AccessibleShape (const AccessibleShape&);
 382     /// Don't use the assignment operator.  Do we need this?
 383     SVX_DLLPRIVATE AccessibleShape& operator= (const AccessibleShape&);
 384
 385     /** Call this method when the title, name, or description of the mxShape
 386         member (may) have been changed.
 387         This method adapts the name and description members of the
 388         AccessibleContextBase base class.
 389     */
 390     void UpdateNameAndDescription (void);
 391 };
 392
 393 } // end of namespace accessibility
 394
 395 #endif
 396
 397 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */