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