diff options
Diffstat (limited to 'offapi/com/sun/star/drawing/framework/XConfigurationController.idl')
| -rw-r--r-- | offapi/com/sun/star/drawing/framework/XConfigurationController.idl | 272 |
1 files changed, 272 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 000000000000..9d7630318368 --- /dev/null +++ b/offapi/com/sun/star/drawing/framework/XConfigurationController.idl @@ -0,0 +1,272 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_drawing_framework_XConfigurationController_idl__ +#define __com_sun_star_drawing_framework_XConfigurationController_idl__ + +#ifndef __com_sun_star_drawing_framework_ConfigurationChangeEvent_idl__ +#include <com/sun/star/drawing/framework/ConfigurationChangeEvent.idl> +#endif +#ifndef __com_sun_star_drawing_framework_XConfigurationControllerBroadcaster_idl__ +#include <com/sun/star/drawing/framework/XConfigurationControllerBroadcaster.idl> +#endif +#ifndef __com_sun_star_drawing_framework_XConfigurationControllerRequestQueue_idl__ +#include <com/sun/star/drawing/framework/XConfigurationControllerRequestQueue.idl> +#endif +#ifndef __com_sun_star_drawing_framework_XResourceFactoryManager_idl__ +#include <com/sun/star/drawing/framework/XResourceFactoryManager.idl> +#endif +#ifndef __com_sun_star_drawing_framework_ResourceActivationMode_idl__ +#include <com/sun/star/drawing/framework/ResourceActivationMode.idl> +#endif + +module com { module sun { module star { module drawing { module framework { + +published interface XConfigurationChangeListener; +published interface XConfigurationChangeRequest; +published interface XResourceId; +published 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 + <member>requestResourceActivation()</member> and + <member>requestResourceDeactivation()</member>.</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 fullfilled. + <ol> + <li>when the last pending request for configuration changes has been + processed,</li> + <li>when the <member>update()</member> 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 + <member>requestResourceActivation()</member> or + <member>requestResourceDeactivation()</member> results in one or more + function objects, that each implement the + <type>XConfigurationChangeRequest</type> 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 + <type>XConfigurationChangeListener</type> 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 anavailable 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><const>ResourceActivationRequested</const> 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 + <member>requestResourceActivation()</member> call is made.</p> + <p>The <member scope="ConfigurationChangeEvent">ResourceId</member> member is set to the requested + resource. The <member>ResourceObject</member> member is not + set.</p></li> + <li><const>ResourceDeactivationRequested</const> 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 <member>requestResourceDeactivation()</member> is called.</p> + <p>The <member>ResourceId</member> member is set to the requested + resource. The <member>ResourceObject</member> member is not + set.</p></li> + <li><const>ConfigurationUpdateStart</const> is sent before the update of + the current configuration starts.</p> + <p>The requested configuration is available in the <member + scope="ConfigurationChangeEvent">Configuration</member> member. The + <member>ResourceId</member> and <member>ResourceObject</member> members + are not set.</p></li> + <li><const>ConfigurationUpdateEnd</const> is sent after the update of + the current configuration ends.</p> + <p>The requested configuration is + available in the <member scope="ConfigurationChangeEvent" + >Configuration</member> member. The <member>ResourceId</member> and + <member>ResourceObject</member> members are not set.</p></li> + <li><const>ResourceActivation</const> is sent when a resource is + activated, i.e. when a new object of a resource is created (or taken + from a cash).</p> + <p>The <member>ResourceId</member> and <member>ResourceObject</member> + members are set to the <type>XResourceId</type> and object reference of + the activated resource.</p></li> + <li><const>ResourceDeactivation</const> 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 <member>ResourceId</member> and <member>ResourceObject</member> + members are set to <type>XResourceId</type> and object reference of the + deactivated resource.</p></li> + </ul></p> +*/ +published 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 <const>REPLACE</const> then, before adding the + resource activation to the request queue, similar resources + linked to the same anchor are removed. This makes it easer 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 <const>ADD</const> 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 <member>lock()</member> calls are recognized: the + configuration controller is locked while <member>lock()</member> was + called more often than <member>unlock()</member>.</p> + */ + void lock (); + + /** Unlock the processing of configuration change requests. + <p>When <member>unlock()</member> is called as many times as + <member>lock()</member> 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 <member>getCurrentConfiguration()</member> and + <member>getRequestedConfiguration()</member> 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 of change + requests so that the resulting reqeusted 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 configuratio 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 <member>getRequestedConfiguration()</member> call. + */ + void restoreConfiguration ([in] XConfiguration xConfiguration); +}; + +}; }; }; }; }; // ::com::sun::star::drawing::framework + +#endif |