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 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_Int64 nChildIndex ) override;
 134
 135     virtual sal_Bool SAL_CALL isAccessibleChildSelected(
 136         sal_Int64 nChildIndex ) override;
 137
 138     virtual void SAL_CALL clearAccessibleSelection(  ) override;
 139
 140     virtual void SAL_CALL selectAllAccessibleChildren(  ) override;
 141
 142     virtual sal_Int64 SAL_CALL getSelectedAccessibleChildCount(  ) override;
 143
 144     virtual css::uno::Reference< css::accessibility::XAccessible > SAL_CALL getSelectedAccessibleChild(
 145         sal_Int64 nSelectedChildIndex ) override;
 146
 147     virtual void SAL_CALL deselectAccessibleChild(
 148         sal_Int64 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_Int64 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_Int64 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_Int64 aState);
 208
 209
 210     //=====  XAccessibleContext  ==============================================
 211
 212     /// Return the number of currently visible children.
 213     virtual sal_Int64 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_Int64 nIndex) override;
 228
 229
 230     /// Return the set of current states.
 231     virtual sal_Int64 SAL_CALL
 232         getAccessibleStateSet() override;
 233
 234     /// Return this objects index among the parents children.
 235     virtual sal_Int64 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         noexcept override;
 290
 291     virtual void SAL_CALL
 292         release()
 293         noexcept 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     /** Listen for disposing events of the model.  The accessible shape
 315         remains functional when this happens.
 316     */
 317     void disposing (const css::lang::EventObject& Source);
 318
 319     //=====  document::XShapeEventListener  ========================================
 320
 321     virtual void SAL_CALL
 322         notifyShapeEvent (const css::document::EventObject& rEventObject) override;
 323
 324
 325     //===== XUnoTunnel ========================================================
 326
 327     UNO3_GETIMPLEMENTATION_DECL(AccessibleShape)
 328
 329     //===== XAccessibleHypertext ========================================================
 330     virtual sal_Int32 SAL_CALL getHyperLinkCount() override;
 331     virtual css::uno::Reference< css::accessibility::XAccessibleHyperlink >
 332         SAL_CALL getHyperLink( sal_Int32 nLinkIndex ) override;
 333     virtual sal_Int32 SAL_CALL getHyperLinkIndex( sal_Int32 nCharIndex ) override;
 334     //=====  XAccessibleText  ==================================================
 335         virtual sal_Int32 SAL_CALL getCaretPosition(  ) override;
 336         virtual sal_Bool SAL_CALL setCaretPosition( sal_Int32 nIndex ) override;
 337         virtual sal_Unicode SAL_CALL getCharacter( sal_Int32 nIndex ) override;//Shen Zhen Jie changed sal_Unicode to sal_uInt32; change back to sal_Unicode
 338         virtual css::uno::Sequence< css::beans::PropertyValue > SAL_CALL getCharacterAttributes( sal_Int32 nIndex, const css::uno::Sequence< OUString >& aRequestedAttributes ) override;
 339         virtual css::awt::Rectangle SAL_CALL getCharacterBounds( sal_Int32 nIndex ) override;
 340         virtual sal_Int32 SAL_CALL getCharacterCount(  ) override;
 341         virtual sal_Int32 SAL_CALL getIndexAtPoint( const css::awt::Point& aPoint ) override;
 342         virtual OUString SAL_CALL getSelectedText(  ) override;
 343         virtual sal_Int32 SAL_CALL getSelectionStart(  ) override;
 344         virtual sal_Int32 SAL_CALL getSelectionEnd(  ) override;
 345         virtual sal_Bool SAL_CALL setSelection( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) override;
 346         virtual OUString SAL_CALL getText(  ) override;
 347         virtual OUString SAL_CALL getTextRange( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) override;
 348         virtual css::accessibility::TextSegment SAL_CALL getTextAtIndex( sal_Int32 nIndex, sal_Int16 aTextType ) override;
 349         virtual css::accessibility::TextSegment SAL_CALL getTextBeforeIndex( sal_Int32 nIndex, sal_Int16 aTextType ) override;
 350         virtual css::accessibility::TextSegment SAL_CALL getTextBehindIndex( sal_Int32 nIndex, sal_Int16 aTextType ) override;
 351         virtual sal_Bool SAL_CALL copyText( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) override;
 352         virtual sal_Bool SAL_CALL scrollSubstringTo( sal_Int32 nStartIndex, sal_Int32 nEndIndex, css::accessibility::AccessibleScrollType aScrollType) 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() const;
 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: */