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