| /************************************************************** |
| * |
| * 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 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the 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 |