1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 28 29 #ifndef _SVX_ACCESSIBILITY_ACCESSIBLE_SHAPE_HXX 30 #define _SVX_ACCESSIBILITY_ACCESSIBLE_SHAPE_HXX 31 32 #include <editeng/AccessibleContextBase.hxx> 33 #include <editeng/AccessibleComponentBase.hxx> 34 #include <svx/IAccessibleViewForwarderListener.hxx> 35 #include <com/sun/star/document/XEventListener.hpp> 36 #include <com/sun/star/accessibility/XAccessible.hpp> 37 #include <com/sun/star/accessibility/XAccessibleExtendedComponent.hpp> 38 #include <com/sun/star/accessibility/AccessibleRole.hpp> 39 #include <com/sun/star/drawing/XShape.hpp> 40 #include <com/sun/star/lang/XEventListener.hpp> 41 #include <com/sun/star/lang/XUnoTunnel.hpp> 42 #include <svx/AccessibleTextHelper.hxx> 43 #include "svx/svxdllapi.h" 44 #include "ChildrenManager.hxx" 45 46 class SdrObject; 47 48 namespace accessibility { 49 50 class AccessibleShapeInfo; 51 class AccessibleShapeTreeInfo; 52 class IAccessibleParent; 53 54 /** This base class provides a base implementation for all shapes. For more 55 detailed documentation about the methods refer to the descriptions of 56 the implemented interfaces. These are, among others, 57 <type>XAccessible</type>, <type>XAccessibleContext</type>, 58 <type>XAccessibleComponent</type> and 59 <type>XAccessibleExtendedComponent</type>. 60 61 <p>The children of a shape can stem from two sources which, in case of 62 SVX and SD shapes, are mutually exclusive. This implementation, 63 however, handles both simultaniously to cope with future extensions or 64 shapes from other projects. 65 <ul> 66 <li>If this shape is a group shape, i.e. a 67 <type>SvxShapeGroup</type> or a <type>Svx3DSceneObject</type>, it 68 can have nested shapes.</li> 69 <li>If this shape is a descendant from <type>SvxShapeText</type> 70 then the text paragraphs are its children.</li> 71 </ul> 72 </p> 73 74 <p>Accessible shapes do not listen for disposing() calls of the UNO 75 shapes they make accessible. This is the task of their owner, usually a 76 container, who can then call dispose() at the accessible object.</p> 77 */ 78 class SVX_DLLPUBLIC AccessibleShape 79 : public AccessibleContextBase, 80 public AccessibleComponentBase, 81 public IAccessibleViewForwarderListener, 82 public ::com::sun::star::document::XEventListener, 83 public ::com::sun::star::lang::XUnoTunnel 84 { 85 public: 86 //===== internal ======================================================== 87 88 /** Create a new accessible object that makes the given shape accessible. 89 @param rShapeInfo 90 This object contains all information specific to the new 91 accessible shape. That are e.g. the shape to be made accessible 92 and the accessible object that will become the parent of the new 93 object. 94 @param rShapeTreeInfo 95 Bundel of information passed to this shape and all of its desendants. 96 @attention 97 Always call the <member>init</member> method after creating a 98 new accessible shape. This is one way to overcome the potential 99 problem of registering the new object with e.g. event 100 broadcasters. That would delete the new object if a broadcaster 101 would not keep a strong reference to the new object. 102 */ 103 AccessibleShape ( 104 const AccessibleShapeInfo& rShapeInfo, 105 const AccessibleShapeTreeInfo& rShapeTreeInfo); 106 107 /** The destructor releases its children manager and text engine if 108 still existent. These are responsible to send appropriate events. 109 */ 110 virtual ~AccessibleShape (void); 111 112 /** Initialize a new shape. See the documentation of the constructor 113 for the reason of this method's existence. 114 */ 115 virtual void Init (void); 116 117 /** Compare two accessible shapes using object identity 118 @param rShape 119 This is the second operand. 120 @return 121 Returns true if both shapes are the same object. 122 */ 123 virtual bool operator== (const AccessibleShape& rShape); 124 125 /** Set the specified state. If the state is <const>FOCUSED</const> 126 then, additionally to the inherited functionality, the focus 127 listeners registered with the <type>XAccessibleComponent</type> 128 interface are called (if that state really changes). 129 130 @param aState 131 The state to turn on. 132 133 @return 134 The returned flag indicates whether the specified state has been 135 changed (<TRUE/>), i.e. it has formerly not been set. 136 */ 137 virtual sal_Bool SetState (sal_Int16 aState); 138 139 /** Reset the specified state. If the state is <const>FOCUSED</const> 140 then, additionally to the inherited functionality, the focus 141 listeners registered with the <type>XAccessibleComponent</type> 142 interface are called (if that state really changes). 143 144 @param aState 145 The state to turn off. 146 147 @return 148 The returned flag indicates whether the specified state has been 149 changed (<TRUE/>), i.e. it has formerly been set. 150 */ 151 virtual sal_Bool ResetState (sal_Int16 aState); 152 153 /** Return the state of the specified state. Take the 154 <const>FOCUSED</const> state from the accessible edit engine. 155 156 @param aState 157 The state for which to return its value. 158 @return 159 A value of <TRUE/> indicates that the state is set. A <FALSE/> 160 value indicates an unset state or the inability to access the 161 entity that manages the state set. 162 163 */ 164 sal_Bool GetState (sal_Int16 aState); 165 166 167 //===== XAccessibleContext ============================================== 168 169 /// Return the number of currently visible children. 170 virtual sal_Int32 SAL_CALL 171 getAccessibleChildCount (void) 172 throw (::com::sun::star::uno::RuntimeException); 173 174 /** Return the specified child. 175 @param nIndex 176 Index of the requested child. 177 @return 178 Reference of the requested child which is the accessible object 179 of a visible shape. 180 @raises IndexOutOfBoundsException 181 Throws an exception if the index is not valid. 182 */ 183 virtual ::com::sun::star::uno::Reference< 184 ::com::sun::star::accessibility::XAccessible> SAL_CALL 185 getAccessibleChild (sal_Int32 nIndex) 186 throw (::com::sun::star::lang::IndexOutOfBoundsException, ::com::sun::star::uno::RuntimeException); 187 188 189 /// Return the set of current states. 190 virtual ::com::sun::star::uno::Reference< 191 ::com::sun::star::accessibility::XAccessibleStateSet> SAL_CALL 192 getAccessibleStateSet (void) 193 throw (::com::sun::star::uno::RuntimeException); 194 195 /// Return this objects index among the parents children. 196 virtual sal_Int32 SAL_CALL 197 getAccessibleIndexInParent (void) 198 throw (::com::sun::star::uno::RuntimeException); 199 200 //===== XAccessibleComponent ============================================ 201 202 virtual ::com::sun::star::uno::Reference< 203 ::com::sun::star::accessibility::XAccessible > SAL_CALL 204 getAccessibleAtPoint (const ::com::sun::star::awt::Point& aPoint) 205 throw (::com::sun::star::uno::RuntimeException); 206 207 virtual ::com::sun::star::awt::Rectangle SAL_CALL getBounds (void) 208 throw (::com::sun::star::uno::RuntimeException); 209 210 virtual ::com::sun::star::awt::Point SAL_CALL getLocation (void) 211 throw (::com::sun::star::uno::RuntimeException); 212 213 virtual ::com::sun::star::awt::Point SAL_CALL getLocationOnScreen (void) 214 throw (::com::sun::star::uno::RuntimeException); 215 216 virtual ::com::sun::star::awt::Size SAL_CALL getSize (void) 217 throw (::com::sun::star::uno::RuntimeException); 218 219 virtual sal_Int32 SAL_CALL getForeground (void) 220 throw (::com::sun::star::uno::RuntimeException); 221 222 virtual sal_Int32 SAL_CALL getBackground (void) 223 throw (::com::sun::star::uno::RuntimeException); 224 225 226 227 //===== XComponent ======================================================== 228 229 using WeakComponentImplHelperBase::addEventListener; 230 using WeakComponentImplHelperBase::removeEventListener; 231 232 //===== XAccessibleEventBroadcaster ===================================== 233 234 /** This call is forwarded to a) the base class and b) to the 235 accessible edit engine if it is present. 236 237 @param rxListener 238 This listener is informed about accessibility events. 239 */ 240 virtual void SAL_CALL 241 addEventListener ( 242 const ::com::sun::star::uno::Reference< 243 ::com::sun::star::accessibility::XAccessibleEventListener >& rxListener) 244 throw (::com::sun::star::uno::RuntimeException); 245 246 /** This call is forwarded to a) the base class and b) to the 247 accessible edit engine if it is present. 248 249 @param rxListener 250 This listener will not be informed about accessibility events 251 anymore. 252 */ 253 virtual void SAL_CALL 254 removeEventListener ( 255 const ::com::sun::star::uno::Reference< 256 ::com::sun::star::accessibility::XAccessibleEventListener >& rxListener) 257 throw (::com::sun::star::uno::RuntimeException); 258 259 260 //===== XInterface ====================================================== 261 262 virtual com::sun::star::uno::Any SAL_CALL 263 queryInterface (const com::sun::star::uno::Type & rType) 264 throw (::com::sun::star::uno::RuntimeException); 265 266 virtual void SAL_CALL 267 acquire (void) 268 throw (); 269 270 virtual void SAL_CALL 271 release (void) 272 throw (); 273 274 275 //===== XServiceInfo ==================================================== 276 277 /** Returns an identifier for the implementation of this object. 278 */ 279 virtual ::rtl::OUString SAL_CALL 280 getImplementationName (void) 281 throw (::com::sun::star::uno::RuntimeException); 282 283 virtual ::com::sun::star::uno::Sequence< ::rtl::OUString> SAL_CALL 284 getSupportedServiceNames (void) 285 throw (::com::sun::star::uno::RuntimeException); 286 287 //===== XTypeProvider =================================================== 288 289 virtual ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Type> SAL_CALL 290 getTypes (void) 291 throw (::com::sun::star::uno::RuntimeException); 292 293 //===== IAccessibleViewForwarderListener ================================ 294 virtual void ViewForwarderChanged (ChangeType aChangeType, 295 const IAccessibleViewForwarder* pViewForwarder); 296 297 //===== lang::XEventListener ============================================ 298 299 /** Listen for disposing events of the model. The accessible shape 300 remains functional when this happens. 301 */ 302 virtual void SAL_CALL 303 disposing (const ::com::sun::star::lang::EventObject& Source) 304 throw (::com::sun::star::uno::RuntimeException); 305 306 //===== document::XEventListener ======================================== 307 308 virtual void SAL_CALL 309 notifyEvent (const ::com::sun::star::document::EventObject& rEventObject) 310 throw (::com::sun::star::uno::RuntimeException); 311 312 313 //===== XUnoTunnel ======================================================== 314 315 static const ::com::sun::star::uno::Sequence< sal_Int8 >& getUnoTunnelImplementationId() throw(); 316 static AccessibleShape* getImplementation( const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxIFace ) throw(); 317 sal_Int64 SAL_CALL getSomething( const ::com::sun::star::uno::Sequence< sal_Int8 >& _rIdentifier ) throw(::com::sun::star::uno::RuntimeException); 318 319 //===== Misc ======================================================== 320 321 ::com::sun::star::uno::Reference< ::com::sun::star::drawing::XShape > 322 GetXShape(); 323 324 /** set the index _nIndex at the accessible shape 325 @param _nIndex 326 The new index in parent. 327 */ 328 inline void setIndexInParent(sal_Int32 _nIndex) { m_nIndexInParent = _nIndex; } 329 330 protected: 331 /// Children manager. May be empty if there are no children. 332 ChildrenManager* mpChildrenManager; 333 334 /// Reference to the actual shape. 335 ::com::sun::star::uno::Reference< 336 ::com::sun::star::drawing::XShape> mxShape; 337 338 /** Bundle of information passed to all shapes in a document tree. 339 */ 340 AccessibleShapeTreeInfo maShapeTreeInfo; 341 342 /** Index that is appended to the object's name to disambiguate between 343 different names with the otherwise same name. 344 */ 345 long mnIndex; 346 347 /** the index in parent. 348 */ 349 sal_Int32 m_nIndexInParent; 350 351 /** The accessible text engine. May be NULL if it can not be created. 352 */ 353 AccessibleTextHelper* mpText; 354 355 /** This object can be used to modify the child list of our parent. 356 */ 357 IAccessibleParent* mpParent; 358 359 /** This object can be removed when we have an extra interface to ask if the shape is selected 360 */ 361 SdrObject* m_pShape; 362 363 /** This method is called from the component helper base class while 364 disposing. 365 */ 366 virtual void SAL_CALL disposing (void); 367 368 /** Create a base name string that contains the accessible name. 369 */ 370 virtual ::rtl::OUString 371 CreateAccessibleBaseName (void) 372 throw (::com::sun::star::uno::RuntimeException); 373 374 /** Create a unique name string that contains the accessible name. The 375 name consists of the base name and the index. 376 */ 377 virtual ::rtl::OUString 378 CreateAccessibleName (void) 379 throw (::com::sun::star::uno::RuntimeException); 380 381 /// Create a description string that contains the accessible description. 382 virtual ::rtl::OUString 383 CreateAccessibleDescription (void) 384 throw (::com::sun::star::uno::RuntimeException); 385 386 /** Update the <const>OPAQUE</const> and <const>SELECTED</const> state. 387 */ 388 virtual void UpdateStates (void); 389 390 private: 391 /** Don't use the default constructor. Use the public constructor that 392 takes the original shape and the parent as arguments instead. 393 */ 394 SVX_DLLPRIVATE explicit AccessibleShape (void); 395 /// Don't use the copy constructor. Is there any use for it? 396 SVX_DLLPRIVATE explicit AccessibleShape (const AccessibleShape&); 397 /// Don't use the assignment operator. Do we need this? 398 SVX_DLLPRIVATE AccessibleShape& operator= (const AccessibleShape&); 399 400 /** Call this method when the title, name, or description of the mxShape 401 member (may) have been changed. 402 This method adapts the name and description members of the 403 AccessibleContextBase base class. 404 */ 405 void UpdateNameAndDescription (void); 406 }; 407 408 } // end of namespace accessibility 409 410 #endif 411