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