From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001
From: Daniel Baumann There are two configurations of resources:
+
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. +
Requests for configuration changes are handled in a two step process: +
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.
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.
+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.
+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.
The configuration controller sends the following events: +
The ConfigurationChangeEvent::ResourceId member is set to the requested + resource. The ResourceObject member is not + set.
The ResourceId member is set to the requested + resource. The ResourceObject member is not + set.
The requested configuration is available in the + ConfigurationChangeEvent::Configuration member. The + ResourceId and ResourceObject members + are not set.
The requested configuration is + available in the ConfigurationChangeEvent::Configuration member. + The ResourceId and ResourceObject members are not set.
The ResourceId and ResourceObject + members are set to the XResourceId and object reference of + the activated resource.
The ResourceId and ResourceObject + members are set to XResourceId and object reference of the + deactivated resource.
The request is processed asynchronously. Notifications about + configuration changes are sent after this call returns.
+ @param xResourceId + The resource whose activation is requested. + @param eMode +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.
+When eMode is ADD then the resource is requested + without further changes.
+ */ + void requestResourceActivation ( + [in] XResourceId xResourceId, + [in] ResourceActivationMode eMode); + + /** Request the deactivation of a resource. +The request is processed asynchronously. Notifications about + configuration changes are sent after this call returns.
+Requesting the deactivation + of a resource that is not active is not an error.
+ @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. +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.
+Recursive lock() calls are recognized: the + configuration controller is locked while lock() was + called more often than unlock().
+ */ + void lock (); + + /** Unlock the processing of configuration change requests. +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.
+ */ + void unlock (); + + /** Explicitly request an update of the current configuration. +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.
+ */ + void update (); + + /** Return a copy of the requested configuration. +Modifications to the returned configuration have no effect on the + drawing framework.
+ */ + XConfiguration getRequestedConfiguration (); + + /** Return a copy of the current configuration. +Modifications to the returned configuration have no effect on the + drawing framework.
+ */ + XConfiguration getCurrentConfiguration (); + + /** Replace the requested configuration with the given configuration and + schedule an update of the current configuration. +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.
+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.
+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.
+ @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: */ -- cgit v1.2.3