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 <sal/config.h>
  24
  25 #include <com/sun/star/uno/Reference.hxx>
  26 #include <rtl/ref.hxx>
  27 #include <svx/svxdllapi.h>
  28
  29 namespace com { namespace sun { namespace star {
  30      namespace accessibility { class XAccessible; }
  31      namespace drawing { class XShape; }
  32      namespace drawing { class XShapes; }
  33 } } }
  34
  35 namespace accessibility {
  36
  37 class AccessibleContextBase;
  38 class AccessibleShapeTreeInfo;
  39 class ChildrenManagerImpl;
  40
  41 /** The AccessibleChildrenManager class acts as a cache of the
  42     accessible objects of the currently visible shapes of a draw page and as
  43     a factory to create the corresponding accessible object for a given
  44     shape.
  45
  46     <p>There are two sources of shapes.  The first is a list of UNO shapes.
  47     It is passes to the constructor and can be re-set with a call to
  48     <member>SetShapeList</member>.  Accessibility objects which represent
  49     these shapes are constructed usually on demand.  The second source is a
  50     set of single AccessibleShape objects added by calls to
  51     <member>AddAccessibleShape</member>.  These are not modified by this
  52     class.  They are only copied into the list of visible shapes depending
  53     on their visibility.  The later list can be cleared by calling
  54     <member>ClearAccessibleShapeList</member>.  The actual set of children
  55     accessible through the <member>GetChildrenCount</member> and
  56     <member>GetChild</member> methods are the accessible objects that lie
  57     completely or partially inside the visible area obtained from the view
  58     forwarder in the shape tree info.</p>
  59
  60     <p>A children manager registers itself at the broadcaster passed to its
  61     constructor and transforms/forwards the received events to the listeners
  62     of the also given context base.  The transformation process includes
  63     interpreting a document::XEventListener, the change from
  64     XShape references to the associated XAccessible reference, and the
  65     creation of an XAccessibleEventObject.  The event object is then passed
  66     to the <method>fireEvent</method> method of the context and from there
  67     forwarded to all listeners.</p>
  68
  69     <p>Note that some of the data given to the constructor is passed to the
  70     accessible shape objects created by that child manager which in turn
  71     pass these data to their child managers.  The data is thus propagated
  72     down a tree of child managers/accessible shape objects from a top level
  73     class that is usually a document/model.  This is the way to give all
  74     accessible objects access to data normally known only to the top level
  75     owner of the shapes.</p>
  76 */
  77 class SVX_DLLPUBLIC ChildrenManager final
  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 css::uno::Reference<
  98             css::accessibility::XAccessible>& rxParent,
  99         const css::uno::Reference<
 100             css::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     ~ChildrenManager();
 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() 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         @throws
 126             Throws an IndexOutOfBoundsException if the index is not valid.
 127     */
 128     css::uno::Reference<
 129             css::accessibility::XAccessible>
 130         GetChild (long nIndex);
 131         /// @throws css::uno::RuntimeException
 132         css::uno::Reference< css::accessibility::XAccessible> GetChild (const css::uno::Reference< css::drawing::XShape>& xShape);
 133         /// @throws css::lang::IndexOutOfBoundsException
 134         /// @throws css::uno::RuntimeException
 135         css::uno::Reference< css::drawing::XShape> GetChildShape (long nIndex);
 136
 137     /** Update the child manager.  Take care of a modified set of children
 138         and modified visible area.  This method can optimize the update
 139         process with respect separate updates of a modified children list
 140         and visible area.
 141         @param bCreateNewObjectsOnDemand
 142             If </true> then accessible objects associated with the visible
 143             shapes are created only when asked for.  No event is sent on
 144             creation.  If </false> then the accessible objects are created
 145             before this method returns and events are sent to inform the
 146             listeners of the new object.
 147     */
 148     void Update (bool bCreateNewObjectsOnDemand = true);
 149
 150     /** Replace the list of UNO shapes by the specified list.
 151         @param xShapeList
 152             The new list of shapes.
 153     */
 154     void SetShapeList (const css::uno::Reference<
 155         css::drawing::XShapes>& xShapeList);
 156
 157     /** Add an accessible shape.  The difference to the UNO shapes in the
 158         list passed to the constructor the specified object does not have to
 159         be created by the shape factory.  This gives the caller full control
 160         over object creation.
 161
 162         @param shape must be non-null
 163     */
 164     void AddAccessibleShape (css::uno::Reference<css::accessibility::XAccessible> const & shape);
 165
 166     /** Clear the list of accessible shapes which have been added by
 167         previous calls to <member>AddAccessibleShape</member>.
 168     */
 169     void ClearAccessibleShapeList();
 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 const & 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();
 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();
 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();
 197
 198     void ViewForwarderChanged();
 199
 200 private:
 201     rtl::Reference<ChildrenManagerImpl> mpImpl;
 202
 203     ChildrenManager (const ChildrenManager&) = delete;
 204     ChildrenManager& operator= (const ChildrenManager&) = delete;
 205 };
 206
 207 } // end of namespace accessibility
 208
 209 #endif
 210
 211 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */