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