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