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