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