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/lang/IndexOutOfBoundsException.hpp>
  26 #include <com/sun/star/uno/Reference.hxx>
  27 #include <com/sun/star/uno/RuntimeException.hpp>
  28 #include <rtl/ref.hxx>
  29 #include <svx/IAccessibleViewForwarderListener.hxx>
  30 #include <svx/svxdllapi.h>
  31
  32 namespace com { namespace sun { namespace star {
  33      namespace accessibility { class XAccessible; }
  34      namespace drawing { class XShape; }
  35      namespace drawing { class XShapes; }
  36 } } }
  37
  38 namespace accessibility {
  39
  40 class AccessibleContextBase;
  41 class AccessibleShapeTreeInfo;
  42 class ChildrenManagerImpl;
  43 class IAccessibleViewForwarder;
  44
  45 /** The AccessibleChildrenManager class acts as a cache of the
  46     accessible objects of the currently visible shapes of a draw page and as
  47     a factory to create the corresponding accessible object for a given
  48     shape.
  49
  50     <p>There are two sources of shapes.  The first is a list of UNO shapes.
  51     It is passes to the constructor and can be re-set with a call to
  52     <member>SetShapeList</member>.  Accessibility objects which represent
  53     these shapes are constructed usually on demand.  The second source is a
  54     set of single AccessibleShape objects added by calls to
  55     <member>AddAccessibleShape</member>.  These are not modified by this
  56     class.  They are only copied into the list of visible shapes depending
  57     on their visibility.  The later list can be cleared by calling
  58     <member>ClearAccessibleShapeList</member>.  The actual set of children
  59     accessible through the <member>GetChildrenCount</member> and
  60     <member>GetChild</member> methods are the accessible objects that lie
  61     completely or partially inside the visible area obtained from the view
  62     forwarder in the shape tree info.</p>
  63
  64     <p>A children manager registers itself at the broadcaster passed to its
  65     constructor and transforms/forwards the received events to the listeners
  66     of the also given context base.  The transformation process includes
  67     interpreting a document::XEventListener, the change from
  68     XShape references to the associated XAccessible reference, and the
  69     creation of an XAccessibleEventObject.  The event object is then passed
  70     to the <method>fireEvent</method> method of the context and from there
  71     forwarded to all listeners.</p>
  72
  73     <p>Note that some of the data given to the constructor is passed to the
  74     accessible shape objects created by that child manager which in turn
  75     pass these data to their child managers.  The data is thus propagated
  76     down a tree of child managers/accessible shape objects from a top level
  77     class that is usually a document/model.  This is the way to give all
  78     accessible objects access to data normally known only to the top level
  79     owner of the shapes.</p>
  80 */
  81 class SVX_DLLPUBLIC ChildrenManager final
  82 {
  83 public:
  84     /** Create a children manager, which manages the children of the given
  85         parent.  The parent is used for creating accessible objects.  The
  86         list of shapes for which to create those objects is not derived from
  87         the parent and has to be provided separately by calling one of the
  88         update methods.
  89         @param rxParent
  90             The parent of the accessible objects which will be created
  91             on demand at some point of time in the future.
  92         @param rxShapeList
  93             List of UNO shapes to manage.
  94         @param rShapeTreeInfo
  95             Bundel of information passed down the shape tree.
  96         @param rContext
  97             An accessible context object that is called for fireing events
  98             for new and deleted children, i.e. that holds a list of
  99             listeners to be informed.
 100     */
 101     ChildrenManager (const css::uno::Reference<
 102             css::accessibility::XAccessible>& rxParent,
 103         const css::uno::Reference<
 104             css::drawing::XShapes>& rxShapeList,
 105         const AccessibleShapeTreeInfo& rShapeTreeInfo,
 106         AccessibleContextBase& rContext);
 107
 108     /** If there still are managed children these are marked as DEFUNC and
 109         released.
 110     */
 111     ~ChildrenManager();
 112
 113     /** Return the number of currently visible accessible children.
 114         @return
 115             If there are no children a 0 is returned.
 116     */
 117     long GetChildCount() const throw ();
 118
 119     /** Return the requested accessible child or throw and
 120         IndexOutOfBoundsException if the given index is invalid.
 121         @param nIndex
 122             Index of the requested child.  Call getChildCount for obtaining
 123             the number of children.
 124         @return
 125             In case of a valid index this method returns a reference to the
 126             requested accessible child.  This reference is empty if it has
 127             not been possible to create the accessible object of the
 128             corresponding shape.
 129         @throws
 130             Throws an IndexOutOfBoundsException if the index is not valid.
 131     */
 132     css::uno::Reference<
 133             css::accessibility::XAccessible>
 134         GetChild (long nIndex);
 135         /// @throws css::uno::RuntimeException
 136         css::uno::Reference< css::accessibility::XAccessible> GetChild (const css::uno::Reference< css::drawing::XShape>& xShape);
 137         /// @throws css::lang::IndexOutOfBoundsException
 138         /// @throws css::uno::RuntimeException
 139         css::uno::Reference< css::drawing::XShape> GetChildShape (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<
 159         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 (css::uno::Reference<css::accessibility::XAccessible> 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& 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();
 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: */