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