summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/drawing/framework/XConfigurationController.idl
diff options
context:
space:
mode:
Diffstat (limited to 'offapi/com/sun/star/drawing/framework/XConfigurationController.idl')
-rw-r--r--offapi/com/sun/star/drawing/framework/XConfigurationController.idl255
1 files changed, 255 insertions, 0 deletions
diff --git a/offapi/com/sun/star/drawing/framework/XConfigurationController.idl b/offapi/com/sun/star/drawing/framework/XConfigurationController.idl
new file mode 100644
index 000000000..eaac2123b
--- /dev/null
+++ b/offapi/com/sun/star/drawing/framework/XConfigurationController.idl
@@ -0,0 +1,255 @@
+/* -*- 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 __com_sun_star_drawing_framework_XConfigurationController_idl__
+#define __com_sun_star_drawing_framework_XConfigurationController_idl__
+
+#include <com/sun/star/drawing/framework/ConfigurationChangeEvent.idl>
+#include <com/sun/star/drawing/framework/XConfigurationControllerBroadcaster.idl>
+#include <com/sun/star/drawing/framework/XConfigurationControllerRequestQueue.idl>
+#include <com/sun/star/drawing/framework/XResourceFactoryManager.idl>
+#include <com/sun/star/drawing/framework/ResourceActivationMode.idl>
+
+module com { module sun { module star { module drawing { module framework {
+
+interface XConfigurationChangeListener;
+interface XConfigurationChangeRequest;
+interface XResourceId;
+interface XResource;
+
+/** The configuration controller is responsible for the management of the
+ set of active resources.
+
+ <p>There are two configurations of resources:<ul>
+ <li>The current configuration contains the set of currently active
+ resources.</li>
+ <li>The requested configuration describes what the current configuration
+ should be. The requested configuration is changed usually by calling
+ requestResourceActivation() and
+ requestResourceDeactivation().</li>
+ </ul></p>
+
+ <p>When the two configurations differ then the current configuration is
+ updated eventually to reflect the requested configuration. An update
+ takes place when the following three conditions are fulfilled.
+ <ol>
+ <li>when the last pending request for configuration changes has been
+ processed,</li>
+ <li>when the update() method is called.</li>
+ <li>when the configuration manager it is unlocked after formerly being
+ locked.</li>
+ </ol></p>
+
+ <p>Requests for configuration changes are handled in a two step process:
+ <ol>
+ <li>First the requested configuration is updated iteratively: Every
+ request that is being made by calling
+ requestResourceActivation() or
+ requestResourceDeactivation() results in one or more
+ function objects, that each implement the
+ XConfigurationChangeRequest interface. These are inserted
+ into a queue. The request objects in the queue are processed
+ asynchronously one at a time in the order in which they are inserted.
+ Only when one request object is processed a change to the requested
+ configuration is made. These changes are broadcasted to registered
+ XConfigurationChangeListener objects. Listeners may
+ decide to make requests that then are added to the queue. For example
+ when the view in the center pane is replaced by another view, some
+ listeners may want to turn some side panes on or off, or show other
+ views in the side panes.</p>
+ <p>This process goes on until the queue of request objects becomes
+ empty. Until this point only the requested configuration has been
+ modified. No resources have been activated or deactivated.</p></li>
+
+ <li><p>The second update step activates or deactivates resources so that
+ the current configuration (the one that comprises the actually active
+ resources) reflects the requested configuration.</p>
+ <p>The order in which resources are activated or deactivated depends on
+ the dependency between the resources. For example a view depends on the
+ pane it is displayed in. Resources that other resources depend on are
+ activated first and deactivated last. The order is undefined for
+ unrelated resources.</p>
+ <p>Note that the second update step may not be able to activate (or even to
+ deactivate) all the requested resources. Either because they are
+ temporarily or permanently unavailable. For example, during the
+ start-up of a new Impress application the side panes are displayed
+ with a visible delay because they are not provided sooner by the
+ underlying framework. Such unavailable resources are not forgotten but
+ remain in the requested configuration. Every time the configuration
+ controller updates its current configuration these resources are
+ requested once more.</li></ol></p>
+
+ <p>The configuration controller sends the following events:
+ <ul>
+ <li>ResourceActivationRequested is sent when the
+ activation of a resource has been requested and the resource is not yet
+ active in the requested configuration. The event is sent when the
+ configuration change request is executed, not when the
+ requestResourceActivation() call is made.</p>
+ <p>The ConfigurationChangeEvent::ResourceId member is set to the requested
+ resource. The ResourceObject member is not
+ set.</p></li>
+ <li>ResourceDeactivationRequested is sent when the
+ deactivation of a resource has been requested and the resource is active
+ in the requested configuration. The event is sent when the
+ configuration change request is executed that is created when for
+ example requestResourceDeactivation() is called.</p>
+ <p>The ResourceId member is set to the requested
+ resource. The ResourceObject member is not
+ set.</p></li>
+ <li>ConfigurationUpdateStart is sent before the update of
+ the current configuration starts.</p>
+ <p>The requested configuration is available in the
+ ConfigurationChangeEvent::Configuration member. The
+ ResourceId and ResourceObject members
+ are not set.</p></li>
+ <li>ConfigurationUpdateEnd is sent after the update of
+ the current configuration ends.</p>
+ <p>The requested configuration is
+ available in the ConfigurationChangeEvent::Configuration member.
+ The ResourceId and ResourceObject members are not set.</p></li>
+ <li>ResourceActivation is sent when a resource is
+ activated, i.e. when a new object of a resource is created (or taken
+ from a cache).</p>
+ <p>The ResourceId and ResourceObject
+ members are set to the XResourceId and object reference of
+ the activated resource.</p></li>
+ <li>ResourceDeactivation is sent when a resource is
+ deactivated, i.e. when an object that previously was part of the
+ configuration is removed from the configuration.</p>
+ <p>The ResourceId and ResourceObject
+ members are set to XResourceId and object reference of the
+ deactivated resource.</p></li>
+ </ul></p>
+*/
+interface XConfigurationController
+{
+ interface XConfigurationControllerRequestQueue;
+ interface XConfigurationControllerBroadcaster;
+ interface XResourceFactoryManager;
+
+ /** Request the activation of a resource.
+ <p>The request is processed asynchronously. Notifications about
+ configuration changes are sent after this call returns.</p>
+ @param xResourceId
+ The resource whose activation is requested.
+ @param eMode
+ <p>When eMode is REPLACE then, before adding the
+ resource activation to the request queue, similar resources
+ linked to the same anchor are removed. This makes it easier to
+ switch between resources whose activation is mutually exclusive.
+ For example, there can only be one view per pane, so before
+ activating a new view the old one has to be deactivated.</p>
+ <p>When eMode is ADD then the resource is requested
+ without further changes.</p>
+ */
+ void requestResourceActivation (
+ [in] XResourceId xResourceId,
+ [in] ResourceActivationMode eMode);
+
+ /** Request the deactivation of a resource.
+ <p>The request is processed asynchronously. Notifications about
+ configuration changes are sent after this call returns.</p>
+ <p>Requesting the deactivation
+ of a resource that is not active is not an error.</p>
+ @param xResourceId
+ The resource whose deactivation is requested.
+ */
+ void requestResourceDeactivation (
+ [in] XResourceId xResourceId);
+
+
+ /** Return the active resource specified by the given resource id.
+ @param xResourceId
+ A valid resource id. This should, but does not have to be, the
+ resource id of an active resource.
+ @return
+ When the given resource id specifies an active resource then
+ that resource is returned. Otherwise an empty reference is
+ returned.
+ */
+ XResource getResource (
+ [in] XResourceId xResourceId);
+
+ /** Lock the processing of configuration change requests.
+ <p>This is only necessary when more than one change request is being
+ made in a row. It prevents an update being made (with all the visible UI
+ changes) before all change requests are being made.</p>
+ <p>Recursive lock() calls are recognized: the
+ configuration controller is locked while lock() was
+ called more often than unlock().</p>
+ */
+ void lock ();
+
+ /** Unlock the processing of configuration change requests.
+ <p>When unlock() is called as many times as
+ lock() and the queue of configuration change
+ requests is not empty the configuration controller continues the
+ processing of the change requests. An update of the current
+ configuration will eventually being made.</p>
+ */
+ void unlock ();
+
+ /** Explicitly request an update of the current configuration.
+ <p>Call it when a resource is activated or deactivated
+ without the control and knowledge of the drawing framework. Calling
+ this method (from outside the drawing framework) should hardly every
+ be necessary.</p>
+ */
+ void update ();
+
+ /** Return a copy of the requested configuration.
+ <p>Modifications to the returned configuration have no effect on the
+ drawing framework.</p>
+ */
+ XConfiguration getRequestedConfiguration ();
+
+ /** Return a copy of the current configuration.
+ <p>Modifications to the returned configuration have no effect on the
+ drawing framework.</p>
+ */
+ XConfiguration getCurrentConfiguration ();
+
+ /** Replace the requested configuration with the given configuration and
+ schedule an update of the current configuration.
+ <p>Together with the getCurrentConfiguration() and
+ getRequestedConfiguration() methods this
+ allows the saving and restoring of configurations. However, the
+ given configuration can have other origins then these methods.</p>
+ <p>The given configuration is transformed into a list of change
+ requests so that the resulting requested configuration equals the
+ given configuration. This has the advantage that not only the
+ resource activations and deactivations but all configuration
+ changes are properly broadcasted.</p>
+ <p>Note that because of the configuration change notifications
+ listeners can make more configuration change requests, so that the
+ resulting requested configuration can be different from the given
+ configuration.</p>
+ @param xConfiguration
+ This typically is a configuration that was obtained with an
+ earlier getRequestedConfiguration() call.
+ */
+ void restoreConfiguration ([in] XConfiguration xConfiguration);
+};
+
+}; }; }; }; }; // ::com::sun::star::drawing::framework
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */