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 #ifndef _SVX_ACCESSIBILITY_CHILDREN_MANAGER_HXX 25 #define _SVX_ACCESSIBILITY_CHILDREN_MANAGER_HXX 26 27 #include <svx/IAccessibleViewForwarderListener.hxx> 28 #include <svx/AccessibleShapeTreeInfo.hxx> 29 #include <com/sun/star/drawing/XShape.hpp> 30 #include <com/sun/star/drawing/XShapes.hpp> 31 #include <memory> 32 #include "svx/svxdllapi.h" 33 34 namespace accessibility { 35 36 class AccessibleContextBase; 37 class AccessibleShape; 38 class ChildrenManagerImpl; 39 40 /** The <type>AccessibleChildrenManager</type> class acts as a cache of the 41 accessible objects of the currently visible shapes of a draw page and as 42 a factory to create the corresponding accessible object for a given 43 shape. 44 45 <p>There are two sources of shapes. The first is a list of UNO shapes. 46 It is passes to the constructor and can be re-set with a call to 47 <member>SetShapeList</member>. Accessibility objects which represent 48 these shapes are constructed usually on demand. The second source is a 49 set of single <type>AccessibleShape</type> objects added by calls to 50 <member>AddAccessibleShape</member>. These are not modified by this 51 class. They are only copied into the list of visible shapes depending 52 on their visibility. The later list can be cleared by calling 53 <member>ClearAccessibleShapeList</member>. The actual set of children 54 accessible through the <member>GetChildrenCount</member> and 55 <member>GetChild</member> methods are the accessible objects that lie 56 completely or partially inside the visible area obtained from the view 57 forwarder in the shape tree info.</p> 58 59 <p>A children manager registers itself at the broadcaster passed to its 60 constructor and transforms/forwards the received events to the listeners 61 of the also given context base. The transformation process includes 62 interpreting a <type>document::XEventListener</type>, the change from 63 XShape references to the associated XAccessible reference, and the 64 creation of an XAccessibleEventObject. The event object is then passed 65 to the <method>fireEvent</method> method of the context and from there 66 forwarded to all listeners.</p> 67 68 <p>Note that some of the data given to the constructor is passed to the 69 accessible shape objects created by that child manager which in turn 70 pass these data to their child managers. The data is thus propagated 71 down a tree of child managers/accessible shape objects from a top level 72 class that is usually a document/model. This is the way to give all 73 accessible objects access to data normally known only to the top level 74 owner of the shapes.</p> 75 */ 76 class SVX_DLLPUBLIC ChildrenManager 77 : public IAccessibleViewForwarderListener 78 { 79 public: 80 /** Create a children manager, which manages the children of the given 81 parent. The parent is used for creating accessible objects. The 82 list of shapes for which to create those objects is not derived from 83 the parent and has to be provided separately by calling one of the 84 update methods. 85 @param rxParent 86 The parent of the accessible objects which will be created 87 on demand at some point of time in the future. 88 @param rxShapeList 89 List of UNO shapes to manage. 90 @param rShapeTreeInfo 91 Bundel of information passed down the shape tree. 92 @param rContext 93 An accessible context object that is called for fireing events 94 for new and deleted children, i.e. that holds a list of 95 listeners to be informed. 96 */ 97 ChildrenManager (const ::com::sun::star::uno::Reference< 98 ::com::sun::star::accessibility::XAccessible>& rxParent, 99 const ::com::sun::star::uno::Reference< 100 ::com::sun::star::drawing::XShapes>& rxShapeList, 101 const AccessibleShapeTreeInfo& rShapeTreeInfo, 102 AccessibleContextBase& rContext); 103 104 /** If there still are managed children these are marked as DEFUNC and 105 released. 106 */ 107 virtual ~ChildrenManager (void); 108 109 /** Return the number of currently visible accessible children. 110 @return 111 If there are no children a 0 is returned. 112 */ 113 long GetChildCount (void) const throw (); 114 115 /** Return the requested accessible child or throw and 116 IndexOutOfBoundsException if the given index is invalid. 117 @param nIndex 118 Index of the requested child. Call getChildCount for obtaining 119 the number of children. 120 @return 121 In case of a valid index this method returns a reference to the 122 requested accessible child. This reference is empty if it has 123 not been possible to create the accessible object of the 124 corresponding shape. 125 @raises 126 Throws an IndexOutOfBoundsException if the index is not valid. 127 */ 128 ::com::sun::star::uno::Reference< 129 ::com::sun::star::accessibility::XAccessible> 130 GetChild (long nIndex) 131 throw (::com::sun::star::uno::RuntimeException, 132 ::com::sun::star::lang::IndexOutOfBoundsException); 133 ::com::sun::star::uno::Reference< ::com::sun::star::accessibility::XAccessible> GetChild (const ::com::sun::star::uno::Reference< ::com::sun::star::drawing::XShape>& xShape) throw (::com::sun::star::uno::RuntimeException); 134 ::com::sun::star::uno::Reference< ::com::sun::star::drawing::XShape> GetChildShape (long nIndex) throw (::com::sun::star::uno::RuntimeException); 135 136 /** Update the child manager. Take care of a modified set of children 137 and modified visible area. This method can optimize the update 138 process with respect separate updates of a modified children list 139 and visible area. 140 @param bCreateNewObjectsOnDemand 141 If </true> then accessible objects associated with the visible 142 shapes are created only when asked for. No event is sent on 143 creation. If </false> then the accessible objects are created 144 before this method returns and events are sent to inform the 145 listeners of the new object. 146 */ 147 void Update (bool bCreateNewObjectsOnDemand = true); 148 149 /** Replace the list of UNO shapes by the specified list. 150 @param xShapeList 151 The new list of shapes. 152 */ 153 void SetShapeList (const ::com::sun::star::uno::Reference< 154 ::com::sun::star::drawing::XShapes>& xShapeList); 155 156 /** Add an accessible shape. The difference to the UNO shapes in the 157 list passed to the constructor the specified object does not have to 158 be created by the shape factory. This gives the caller full control 159 over object creation. 160 161 @param pShape 162 This class <em>does</em> take ownership of the argument. 163 */ 164 void AddAccessibleShape (std::auto_ptr<AccessibleShape> pShape); 165 166 /** Clear the list of accessible shapes which have been added by 167 previous calls to <member>AddAccessibleShape</member>. 168 */ 169 void ClearAccessibleShapeList (void); 170 171 /** Take a new event shape tree info. Call this method to inform the 172 children manager of a change of the info bundle. 173 @param rShapeTreeInfo 174 The new info that replaces the current one. 175 */ 176 void SetInfo (AccessibleShapeTreeInfo& rShapeTreeInfo); 177 178 /** Update the SELECTED and FOCUSED states of all visible children 179 according to the given selection. This includes setting 180 <em>and</em> resetting the states. 181 */ 182 void UpdateSelection (void); 183 184 /** Return whether one of the shapes managed by this object has 185 currently the focus. 186 @return 187 Returns <true/> when there is a shape that has the focus and 188 <false/> when there is no such shape. 189 */ 190 bool HasFocus (void); 191 192 /** When there is a shape that currently has the focus, 193 i.e. <member>HasFocus()</member> returns <true/> then remove the 194 focus from that shape. Otherwise nothing changes. 195 */ 196 void RemoveFocus (void); 197 198 //===== IAccessibleViewForwarderListener ================================ 199 virtual void ViewForwarderChanged (ChangeType aChangeType, 200 const IAccessibleViewForwarder* pViewForwarder); 201 202 protected: 203 ChildrenManagerImpl* mpImpl; 204 205 private: 206 // Don't use the copy constructor or the assignment operator. They are 207 // not implemented (and are not intended to be). 208 SVX_DLLPRIVATE ChildrenManager (const ChildrenManager&); 209 SVX_DLLPRIVATE ChildrenManager& operator= (const ChildrenManager&); 210 }; 211 212 } // end of namespace accessibility 213 214 #endif 215