diff options
Diffstat (limited to 'offapi/com/sun/star/drawing/framework/XConfigurationController.idl')
| -rw-r--r-- | offapi/com/sun/star/drawing/framework/XConfigurationController.idl | 255 |
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: */ |