:: com :: sun :: star :: drawing :: framework ::
|
unpublished |
interface XConfigurationController |
|
|
- Base Interfaces
XConfigurationController
┣ XConfigurationControllerRequestQueue
┗ XConfigurationControllerBroadcaster
-
|
- Description
- The configuration controller is responsible for the synchronization of
other controllers for the management of resources like panes, views,
tool bars, and command groups.
There are two configurations of resources:
- The current configuration describes the state of resources as
it is.
- The requested configuration describes how it should be. The
requested configuration is changed usually by calling
requestResourceActivation() and
requestResourceDeactivation() . Other sub controllers
may offer other methods for requesting configuration changes.
When the two differ then the current configuration is updated eventually
to reflect the requested one
- when the last pending request for configuration changes has been
processed,
- when the update() method is called.
- when the configuration manager it is unlocked after formerly being
locked.
Requests for configuration changes are handled in a two step process:
- First the requested configuration is updated iteratively: Every
request that is being made by e.g. calling
requestResourceActivation() or
requestResourceDeactivation() results in one or more
function objects, that each implement the
XConfigurationChangeRequest interface, being inserted
into a queue. The request objects in the queue are processed 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. Listeners may decide to add more request
objects 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.
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.
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 frame 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.
The configuration controller sends the following events:
- 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 that is created when for
example requestResourceActivation() is called.
The ResourceId member is set to the requested
resource. The ResourceObject member is not not
set.
- ResourceDeactivationRequest 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.
The ResourceId member is set to the requested
resource. The ResourceObject member is not
set.
- ConfigurationUpdateStart is sent before the update of
the current configuration is started.
The requested configuration is available in the ConfigurationChangeEvent::Configuration member. The
ResourceId and ResourceObject members
are not set.
- ConfigurationUpdateEnd is sent before the update of
the current configuration is started.
The requested configuration is
available in the ConfigurationChangeEvent::Configuration member. The ResourceId and
ResourceObject members are not set.
The sub controllers that manage individual resources (like
XPaneController , XViewController ,
::XToolbarController , and XCommandController )
send the following events:
- ResourceActivation is sent when a resource is
activated, i.e. when a new object of a resource is created (or taken
from a cash).
The ResourceId and ResourceObject
members are set to the ResourceId and object reference of
the activated resource.
- 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.
The ResourceId and ResourceObject
members are set to ResourceId and object reference of the
deactivated resource.
|
Methods' Details |
requestResourceActivation
- Description
- Request the activation of a resource.
The request is processed asynchronously. Notifications about
configuration changes are sent after this call returns.
- Parameter xResourceId
- The resource whose activation is requested.
- Parameter 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 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.
When eMode is ADD then the resource is requested
without further changes.
|
|
requestResourceDeactivation
void |
requestResourceDeactivation( |
[in] XResourceId |
xResourceId ); |
- Description
- 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.
- Parameter xResourceId
- The resource whose deactivation is requested.
|
|
lock
- Description
- Lock the processing of configuration change requests.
This is only necessary when more than one change request is being
made. 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() .
|
|
unlock
- Description
- Unlock the processing of configuration changes 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.
|
|
update
- Description
- 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.
|
|
getConfiguration
- Description
- Return a copy of the requested configuration.
The returned requested configuration reflects the current
configuration (more or less, there may be requested but anavailable
resources) after the last update() call and when no further
change requests have been made.
|
|
restoreConfiguration
- Description
- Replace the requested configuraion with the given configuration and
update the current configuration accordingly.
Together with the this
allows the saving and restoring of configurations.
The given configuration is treated like a bunch of change
requests made by calling the
requestResourceActivation() and
requestResourceDeactivation() methods.
Requested configuration changes are notified so that listeners can react.
- Parameter xConfiguration
- This typically is a configuration that was obtained with an
earlier getConfiguration() call.
|
|
Copyright © 2003 Sun Microsystems, Inc.