summaryrefslogtreecommitdiffstats
path: root/include/svx/ChildrenManager.hxx
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--include/svx/ChildrenManager.hxx214
1 files changed, 214 insertions, 0 deletions
diff --git a/include/svx/ChildrenManager.hxx b/include/svx/ChildrenManager.hxx
new file mode 100644
index 000000000..0498b43fd
--- /dev/null
+++ b/include/svx/ChildrenManager.hxx
@@ -0,0 +1,214 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed
+ * with this work for additional information regarding copyright
+ * ownership. The ASF licenses this file to you under the Apache
+ * License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+#ifndef INCLUDED_SVX_CHILDRENMANAGER_HXX
+#define INCLUDED_SVX_CHILDRENMANAGER_HXX
+
+#include <sal/config.h>
+
+#include <com/sun/star/uno/Reference.hxx>
+#include <rtl/ref.hxx>
+#include <svx/svxdllapi.h>
+#include <tools/long.hxx>
+
+namespace com::sun::star
+{
+namespace accessibility
+{
+class XAccessible;
+}
+namespace drawing
+{
+class XShape;
+}
+namespace drawing
+{
+class XShapes;
+}
+}
+
+namespace accessibility
+{
+class AccessibleContextBase;
+class AccessibleShapeTreeInfo;
+class ChildrenManagerImpl;
+
+/** The AccessibleChildrenManager class acts as a cache of the
+ accessible objects of the currently visible shapes of a draw page and as
+ a factory to create the corresponding accessible object for a given
+ shape.
+
+ <p>There are two sources of shapes. The first is a list of UNO shapes.
+ It is passes to the constructor and can be re-set with a call to
+ <member>SetShapeList</member>. Accessibility objects which represent
+ these shapes are constructed usually on demand. The second source is a
+ set of single AccessibleShape objects added by calls to
+ <member>AddAccessibleShape</member>. These are not modified by this
+ class. They are only copied into the list of visible shapes depending
+ on their visibility. The later list can be cleared by calling
+ <member>ClearAccessibleShapeList</member>. The actual set of children
+ accessible through the <member>GetChildrenCount</member> and
+ <member>GetChild</member> methods are the accessible objects that lie
+ completely or partially inside the visible area obtained from the view
+ forwarder in the shape tree info.</p>
+
+ <p>A children manager registers itself at the broadcaster passed to its
+ constructor and transforms/forwards the received events to the listeners
+ of the also given context base. The transformation process includes
+ interpreting a document::XEventListener, the change from
+ XShape references to the associated XAccessible reference, and the
+ creation of an XAccessibleEventObject. The event object is then passed
+ to the <method>fireEvent</method> method of the context and from there
+ forwarded to all listeners.</p>
+
+ <p>Note that some of the data given to the constructor is passed to the
+ accessible shape objects created by that child manager which in turn
+ pass these data to their child managers. The data is thus propagated
+ down a tree of child managers/accessible shape objects from a top level
+ class that is usually a document/model. This is the way to give all
+ accessible objects access to data normally known only to the top level
+ owner of the shapes.</p>
+*/
+class SVX_DLLPUBLIC ChildrenManager final
+{
+public:
+ /** Create a children manager, which manages the children of the given
+ parent. The parent is used for creating accessible objects. The
+ list of shapes for which to create those objects is not derived from
+ the parent and has to be provided separately by calling one of the
+ update methods.
+ @param rxParent
+ The parent of the accessible objects which will be created
+ on demand at some point of time in the future.
+ @param rxShapeList
+ List of UNO shapes to manage.
+ @param rShapeTreeInfo
+ Bundle of information passed down the shape tree.
+ @param rContext
+ An accessible context object that is called for firing events
+ for new and deleted children, i.e. that holds a list of
+ listeners to be informed.
+ */
+ ChildrenManager(const css::uno::Reference<css::accessibility::XAccessible>& rxParent,
+ const css::uno::Reference<css::drawing::XShapes>& rxShapeList,
+ const AccessibleShapeTreeInfo& rShapeTreeInfo, AccessibleContextBase& rContext);
+
+ /** If there still are managed children these are marked as DEFUNC and
+ released.
+ */
+ ~ChildrenManager();
+
+ /** Return the number of currently visible accessible children.
+ @return
+ If there are no children a 0 is returned.
+ */
+ tools::Long GetChildCount() const noexcept;
+
+ /** Return the requested accessible child or throw and
+ IndexOutOfBoundsException if the given index is invalid.
+ @param nIndex
+ Index of the requested child. Call getChildCount for obtaining
+ the number of children.
+ @return
+ In case of a valid index this method returns a reference to the
+ requested accessible child. This reference is empty if it has
+ not been possible to create the accessible object of the
+ corresponding shape.
+ @throws
+ Throws an IndexOutOfBoundsException if the index is not valid.
+ */
+ css::uno::Reference<css::accessibility::XAccessible> GetChild(tools::Long nIndex);
+ /// @throws css::lang::IndexOutOfBoundsException
+ /// @throws css::uno::RuntimeException
+ css::uno::Reference<css::drawing::XShape> GetChildShape(tools::Long nIndex);
+
+ /** Update the child manager. Take care of a modified set of children
+ and modified visible area. This method can optimize the update
+ process with respect separate updates of a modified children list
+ and visible area.
+ @param bCreateNewObjectsOnDemand
+ If </true> then accessible objects associated with the visible
+ shapes are created only when asked for. No event is sent on
+ creation. If </false> then the accessible objects are created
+ before this method returns and events are sent to inform the
+ listeners of the new object.
+ */
+ void Update(bool bCreateNewObjectsOnDemand = true);
+
+ /** Replace the list of UNO shapes by the specified list.
+ @param xShapeList
+ The new list of shapes.
+ */
+ void SetShapeList(const css::uno::Reference<css::drawing::XShapes>& xShapeList);
+
+ /** Add an accessible shape. The difference to the UNO shapes in the
+ list passed to the constructor the specified object does not have to
+ be created by the shape factory. This gives the caller full control
+ over object creation.
+
+ @param shape must be non-null
+ */
+ void AddAccessibleShape(css::uno::Reference<css::accessibility::XAccessible> const& shape);
+
+ /** Clear the list of accessible shapes which have been added by
+ previous calls to <member>AddAccessibleShape</member>.
+ */
+ void ClearAccessibleShapeList();
+
+ /** Take a new event shape tree info. Call this method to inform the
+ children manager of a change of the info bundle.
+ @param rShapeTreeInfo
+ The new info that replaces the current one.
+ */
+ void SetInfo(AccessibleShapeTreeInfo const& rShapeTreeInfo);
+
+ /** Update the SELECTED and FOCUSED states of all visible children
+ according to the given selection. This includes setting
+ <em>and</em> resetting the states.
+ */
+ void UpdateSelection();
+
+ /** Return whether one of the shapes managed by this object has
+ currently the focus.
+ @return
+ Returns <true/> when there is a shape that has the focus and
+ <false/> when there is no such shape.
+ */
+ bool HasFocus() const;
+
+ /** When there is a shape that currently has the focus,
+ i.e. <member>HasFocus()</member> returns <true/> then remove the
+ focus from that shape. Otherwise nothing changes.
+ */
+ void RemoveFocus();
+
+ void ViewForwarderChanged();
+
+private:
+ rtl::Reference<ChildrenManagerImpl> mpImpl;
+
+ ChildrenManager(const ChildrenManager&) = delete;
+ ChildrenManager& operator=(const ChildrenManager&) = delete;
+};
+
+} // end of namespace accessibility
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */