Branch libreoffice-5-0-4
[LibreOffice.git] / include / svx / AccessibleShape.hxx
blobd32baf2a8c6b50df1f76eacf81a261655429a846
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
21 #ifndef INCLUDED_SVX_ACCESSIBLESHAPE_HXX
22 #define INCLUDED_SVX_ACCESSIBLESHAPE_HXX
24 #include <editeng/AccessibleContextBase.hxx>
25 #include <editeng/AccessibleComponentBase.hxx>
26 #include <svx/IAccessibleViewForwarderListener.hxx>
27 #include <com/sun/star/document/XEventListener.hpp>
28 #include <com/sun/star/accessibility/XAccessible.hpp>
29 #include <com/sun/star/accessibility/XAccessibleExtendedComponent.hpp>
30 #include <com/sun/star/accessibility/AccessibleRole.hpp>
31 #include <com/sun/star/accessibility/XAccessibleSelection.hpp>
32 #include <com/sun/star/accessibility/XAccessibleText.hpp>
33 #include <com/sun/star/accessibility/XAccessibleExtendedAttributes.hpp>
34 #include <com/sun/star/accessibility/XAccessibleGroupPosition.hpp>
35 #include <com/sun/star/accessibility/XAccessibleHyperlink.hpp>
36 #include <com/sun/star/accessibility/XAccessibleHypertext.hpp>
37 #include <com/sun/star/drawing/XShape.hpp>
38 #include <com/sun/star/lang/XEventListener.hpp>
39 #include <com/sun/star/lang/XUnoTunnel.hpp>
40 #include <svx/AccessibleTextHelper.hxx>
41 #include <svx/svxdllapi.h>
42 #include <svx/ChildrenManager.hxx>
44 class SdrObject;
46 namespace accessibility {
48 class AccessibleShapeInfo;
49 class AccessibleShapeTreeInfo;
50 class IAccessibleParent;
52 /** This base class provides a base implementation for all shapes. For more
53 detailed documentation about the methods refer to the descriptions of
54 the implemented interfaces. These are, among others,
55 XAccessible, <type>XAccessibleContext</type>,
56 XAccessibleComponent and
57 XAccessibleExtendedComponent.
59 <p>The children of a shape can stem from two sources which, in case of
60 SVX and SD shapes, are mutually exclusive. This implementation,
61 however, handles both simultaniously to cope with future extensions or
62 shapes from other projects.
63 <ul>
64 <li>If this shape is a group shape, i.e. a
65 SvxShapeGroup or a <type>Svx3DSceneObject</type>, it
66 can have nested shapes.</li>
67 <li>If this shape is a descendant from SvxShapeText
68 then the text paragraphs are its children.</li>
69 </ul>
70 </p>
72 <p>Accessible shapes do not listen for disposing() calls of the UNO
73 shapes they make accessible. This is the task of their owner, usually a
74 container, who can then call dispose() at the accessible object.</p>
76 class SVX_DLLPUBLIC AccessibleShape
77 : public AccessibleContextBase,
78 public AccessibleComponentBase,
79 public ::com::sun::star::accessibility::XAccessibleSelection,
80 public ::com::sun::star::accessibility::XAccessibleExtendedAttributes,
81 public ::com::sun::star::accessibility::XAccessibleGroupPosition,
82 public com::sun::star::accessibility::XAccessibleHypertext,
83 public IAccessibleViewForwarderListener,
84 public ::com::sun::star::document::XEventListener,
85 public ::com::sun::star::lang::XUnoTunnel
87 public:
88 //===== internal ========================================================
90 /** Create a new accessible object that makes the given shape accessible.
91 @param rShapeInfo
92 This object contains all information specific to the new
93 accessible shape. That are e.g. the shape to be made accessible
94 and the accessible object that will become the parent of the new
95 object.
96 @param rShapeTreeInfo
97 Bundel of information passed to this shape and all of its desendants.
98 @attention
99 Always call the <member>init</member> method after creating a
100 new accessible shape. This is one way to overcome the potential
101 problem of registering the new object with e.g. event
102 broadcasters. That would delete the new object if a broadcaster
103 would not keep a strong reference to the new object.
105 AccessibleShape (
106 const AccessibleShapeInfo& rShapeInfo,
107 const AccessibleShapeTreeInfo& rShapeTreeInfo);
108 //Solution: Overwrite the object's current name.
109 virtual OUString SAL_CALL getAccessibleName() throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
110 virtual OUString SAL_CALL getAccessibleDescription() throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
111 virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleRelationSet> SAL_CALL getAccessibleRelationSet() throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
112 //===== XAccessibleSelection ============================================
114 virtual void SAL_CALL selectAccessibleChild(
115 sal_Int32 nChildIndex )
116 throw ( ::com::sun::star::lang::IndexOutOfBoundsException,
117 ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
119 virtual sal_Bool SAL_CALL isAccessibleChildSelected(
120 sal_Int32 nChildIndex )
121 throw ( ::com::sun::star::lang::IndexOutOfBoundsException,
122 ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
124 virtual void SAL_CALL clearAccessibleSelection( )
125 throw ( ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
127 virtual void SAL_CALL selectAllAccessibleChildren( )
128 throw ( ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
130 virtual sal_Int32 SAL_CALL getSelectedAccessibleChildCount( )
131 throw ( ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
133 virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible > SAL_CALL getSelectedAccessibleChild(
134 sal_Int32 nSelectedChildIndex )
135 throw ( ::com::sun::star::lang::IndexOutOfBoundsException,
136 ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
138 virtual void SAL_CALL deselectAccessibleChild(
139 sal_Int32 nSelectedChildIndex )
140 throw ( ::com::sun::star::lang::IndexOutOfBoundsException,
141 ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
143 // ====== XAccessibleExtendedAttributes =====================================
144 virtual ::com::sun::star::uno::Any SAL_CALL getExtendedAttributes()
145 throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE ;
146 /// Return this object's role.
147 virtual sal_Int16 SAL_CALL getAccessibleRole() throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
148 //===== XAccessibleGroupPosition =========================================
149 virtual ::com::sun::star::uno::Sequence< sal_Int32 > SAL_CALL
150 getGroupPosition( const ::com::sun::star::uno::Any& rAny )
151 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
152 virtual OUString SAL_CALL getObjectLink( const ::com::sun::star::uno::Any& accoject )
153 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
154 /** The destructor releases its children manager and text engine if
155 still existent. These are responsible to send appropriate events.
157 virtual ~AccessibleShape();
159 /** Initialize a new shape. See the documentation of the constructor
160 for the reason of this method's existence.
162 virtual void Init();
164 /** Compare two accessible shapes using object identity
165 @param rShape
166 This is the second operand.
167 @return
168 Returns true if both shapes are the same object.
170 bool operator== (const AccessibleShape& rShape);
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).
177 @param aState
178 The state to turn on.
180 @return
181 The returned flag indicates whether the specified state has been
182 changed (<TRUE/>), i.e. it has formerly not been set.
184 virtual bool SetState (sal_Int16 aState) SAL_OVERRIDE;
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).
191 @param aState
192 The state to turn off.
194 @return
195 The returned flag indicates whether the specified state has been
196 changed (<TRUE/>), i.e. it has formerly been set.
198 virtual bool ResetState (sal_Int16 aState) SAL_OVERRIDE;
200 /** Return the state of the specified state. Take the
201 <const>FOCUSED</const> state from the accessible edit engine.
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.
211 bool GetState (sal_Int16 aState);
214 //===== XAccessibleContext ==============================================
216 /// Return the number of currently visible children.
217 virtual sal_Int32 SAL_CALL
218 getAccessibleChildCount()
219 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
221 /** Return the specified child.
222 @param nIndex
223 Index of the requested child.
224 @return
225 Reference of the requested child which is the accessible object
226 of a visible shape.
227 @raises IndexOutOfBoundsException
228 Throws an exception if the index is not valid.
230 virtual ::com::sun::star::uno::Reference<
231 ::com::sun::star::accessibility::XAccessible> SAL_CALL
232 getAccessibleChild (sal_Int32 nIndex)
233 throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
236 /// Return the set of current states.
237 virtual ::com::sun::star::uno::Reference<
238 ::com::sun::star::accessibility::XAccessibleStateSet> SAL_CALL
239 getAccessibleStateSet()
240 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
242 /// Return this objects index among the parents children.
243 virtual sal_Int32 SAL_CALL
244 getAccessibleIndexInParent()
245 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
247 //===== XAccessibleComponent ============================================
249 virtual ::com::sun::star::uno::Reference<
250 ::com::sun::star::accessibility::XAccessible > SAL_CALL
251 getAccessibleAtPoint (const ::com::sun::star::awt::Point& aPoint)
252 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
254 virtual ::com::sun::star::awt::Rectangle SAL_CALL getBounds()
255 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
257 virtual ::com::sun::star::awt::Point SAL_CALL getLocation()
258 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
260 virtual ::com::sun::star::awt::Point SAL_CALL getLocationOnScreen()
261 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
263 virtual ::com::sun::star::awt::Size SAL_CALL getSize()
264 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
266 virtual sal_Int32 SAL_CALL getForeground()
267 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
269 virtual sal_Int32 SAL_CALL getBackground()
270 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
272 //===== XAccessibleEventBroadcaster =====================================
274 /** This call is forwarded to a) the base class and b) to the
275 accessible edit engine if it is present.
277 @param rxListener
278 This listener is informed about accessibility events.
280 virtual void SAL_CALL
281 addAccessibleEventListener (
282 const ::com::sun::star::uno::Reference<
283 ::com::sun::star::accessibility::XAccessibleEventListener >& rxListener)
284 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
286 /** This call is forwarded to a) the base class and b) to the
287 accessible edit engine if it is present.
289 @param rxListener
290 This listener will not be informed about accessibility events
291 anymore.
293 virtual void SAL_CALL
294 removeAccessibleEventListener (
295 const ::com::sun::star::uno::Reference<
296 ::com::sun::star::accessibility::XAccessibleEventListener >& rxListener)
297 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
300 //===== XInterface ======================================================
302 virtual com::sun::star::uno::Any SAL_CALL
303 queryInterface (const com::sun::star::uno::Type & rType)
304 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
306 virtual void SAL_CALL
307 acquire()
308 throw () SAL_OVERRIDE;
310 virtual void SAL_CALL
311 release()
312 throw () SAL_OVERRIDE;
315 //===== XServiceInfo ====================================================
317 /** Returns an identifier for the implementation of this object.
319 virtual OUString SAL_CALL
320 getImplementationName()
321 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
323 virtual ::com::sun::star::uno::Sequence< OUString> SAL_CALL
324 getSupportedServiceNames()
325 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
327 //===== XTypeProvider ===================================================
329 virtual ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Type> SAL_CALL
330 getTypes()
331 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
333 //===== IAccessibleViewForwarderListener ================================
334 virtual void ViewForwarderChanged (ChangeType aChangeType,
335 const IAccessibleViewForwarder* pViewForwarder) SAL_OVERRIDE;
337 //===== lang::XEventListener ============================================
339 /** Listen for disposing events of the model. The accessible shape
340 remains functional when this happens.
342 virtual void SAL_CALL
343 disposing (const ::com::sun::star::lang::EventObject& Source)
344 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
346 //===== document::XEventListener ========================================
348 virtual void SAL_CALL
349 notifyEvent (const ::com::sun::star::document::EventObject& rEventObject)
350 throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
353 //===== XUnoTunnel ========================================================
355 static const ::com::sun::star::uno::Sequence< sal_Int8 >& getUnoTunnelImplementationId() throw();
356 static AccessibleShape* getImplementation( const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxIFace ) throw();
357 sal_Int64 SAL_CALL getSomething( const ::com::sun::star::uno::Sequence< sal_Int8 >& _rIdentifier ) throw(::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
359 //===== XAccessibleHypertext ========================================================
360 virtual sal_Int32 SAL_CALL getHyperLinkCount() throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
361 virtual ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessibleHyperlink >
362 SAL_CALL getHyperLink( sal_Int32 nLinkIndex )
363 throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
364 virtual sal_Int32 SAL_CALL getHyperLinkIndex( sal_Int32 nCharIndex )
365 throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
366 //===== XAccesibleText ==================================================
367 virtual sal_Int32 SAL_CALL getCaretPosition( ) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
368 virtual sal_Bool SAL_CALL setCaretPosition( sal_Int32 nIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
369 virtual sal_Unicode SAL_CALL getCharacter( sal_Int32 nIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;//Shen Zhen Jie changed sal_Unicode to sal_uInt32; change back to sal_Unicode
370 virtual ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue > SAL_CALL getCharacterAttributes( sal_Int32 nIndex, const ::com::sun::star::uno::Sequence< OUString >& aRequestedAttributes ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
371 virtual ::com::sun::star::awt::Rectangle SAL_CALL getCharacterBounds( sal_Int32 nIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
372 virtual sal_Int32 SAL_CALL getCharacterCount( ) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
373 virtual sal_Int32 SAL_CALL getIndexAtPoint( const ::com::sun::star::awt::Point& aPoint ) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
374 virtual OUString SAL_CALL getSelectedText( ) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
375 virtual sal_Int32 SAL_CALL getSelectionStart( ) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
376 virtual sal_Int32 SAL_CALL getSelectionEnd( ) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
377 virtual sal_Bool SAL_CALL setSelection( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
378 virtual OUString SAL_CALL getText( ) throw (::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
379 virtual OUString SAL_CALL getTextRange( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
380 virtual ::com::sun::star::accessibility::TextSegment SAL_CALL getTextAtIndex( sal_Int32 nIndex, sal_Int16 aTextType ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
381 virtual ::com::sun::star::accessibility::TextSegment SAL_CALL getTextBeforeIndex( sal_Int32 nIndex, sal_Int16 aTextType ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
382 virtual ::com::sun::star::accessibility::TextSegment SAL_CALL getTextBehindIndex( sal_Int32 nIndex, sal_Int16 aTextType ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
383 virtual sal_Bool SAL_CALL copyText( sal_Int32 nStartIndex, sal_Int32 nEndIndex ) throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException, std::exception) SAL_OVERRIDE;
385 //===== Misc ========================================================
387 ::com::sun::star::uno::Reference< ::com::sun::star::drawing::XShape >
388 GetXShape() { return mxShape; }
390 /** set the index _nIndex at the accessible shape
391 @param _nIndex
392 The new index in parent.
394 inline void setIndexInParent(sal_Int32 _nIndex) { m_nIndexInParent = _nIndex; }
396 protected:
397 /// Children manager. May be empty if there are no children.
398 ChildrenManager* mpChildrenManager;
400 /// Reference to the actual shape.
401 ::com::sun::star::uno::Reference<
402 ::com::sun::star::drawing::XShape> mxShape;
404 /** Bundle of information passed to all shapes in a document tree.
406 AccessibleShapeTreeInfo maShapeTreeInfo;
408 /** Index that is appended to the object's name to disambiguate between
409 different names with the otherwise same name.
411 long mnIndex;
413 /** the index in parent.
415 sal_Int32 m_nIndexInParent;
417 /** The accessible text engine. May be NULL if it can not be created.
419 AccessibleTextHelper* mpText;
421 /** This object can be used to modify the child list of our parent.
423 IAccessibleParent* mpParent;
425 /** This object can be removed when we have an extra interface to ask if the shape is selected
427 SdrObject* m_pShape;
429 /** This method is called from the component helper base class while
430 disposing.
432 virtual void SAL_CALL disposing() SAL_OVERRIDE;
434 /** Create a base name string that contains the accessible name.
436 virtual OUString
437 CreateAccessibleBaseName()
438 throw (::com::sun::star::uno::RuntimeException);
440 /** Create a unique name string that contains the accessible name. The
441 name consists of the base name and the index.
443 virtual OUString
444 CreateAccessibleName()
445 throw (::com::sun::star::uno::RuntimeException) SAL_OVERRIDE;
447 /// Create a description string that contains the accessible description.
448 virtual OUString
449 CreateAccessibleDescription()
450 throw (::com::sun::star::uno::RuntimeException) SAL_OVERRIDE;
451 OUString
452 GetFullAccessibleName(AccessibleShape *shape)
453 throw (::com::sun::star::uno::RuntimeException);
454 virtual OUString GetStyle();
455 void UpdateDocumentAllSelState(::com::sun::star::uno::Reference<
456 ::com::sun::star::accessibility::XAccessibleStateSet > &xStateSet);
457 /** Update the <const>OPAQUE</const> and <const>SELECTED</const> state.
459 void UpdateStates();
461 private:
462 AccessibleShape (const AccessibleShape&) SAL_DELETED_FUNCTION;
463 AccessibleShape& operator= (const AccessibleShape&) SAL_DELETED_FUNCTION;
464 //Old accessible name
465 OUString aAccName;
467 /** Call this method when the title, name, or description of the mxShape
468 member (may) have been changed.
469 This method adapts the name and description members of the
470 AccessibleContextBase base class.
472 void UpdateNameAndDescription();
475 } // end of namespace accessibility
477 #endif
479 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */