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