LibreOffice LibreOffice 25.2 SDK API Reference

Exported Interfaces | Public Member Functions | List of all members
XConfigurationController Interface Reference

The configuration controller is responsible for the management of the set of active resources. More...

`import"XConfigurationController.idl";`

Inheritance diagram for XConfigurationController:

## Exported Interfaces
interface | XConfigurationControllerRequestQueue
interface | XConfigurationControllerBroadcaster
interface | XResourceFactoryManager

## Public Member Functions
void | requestResourceActivation ([in] XResourceId xResourceId, [in] ResourceActivationMode eMode)
| Request the activation of a resource. More...
void | requestResourceDeactivation ([in] XResourceId xResourceId)
| Request the deactivation of a resource. More...
XResource | getResource ([in] XResourceId xResourceId)
| Return the active resource specified by the given resource id. More...
void | lock ()
| Lock the processing of configuration change requests. More...
void | unlock ()
| Unlock the processing of configuration change requests. More...
void | update ()
| Explicitly request an update of the current configuration. More...
XConfiguration | getRequestedConfiguration ()
| Return a copy of the requested configuration. More...
XConfiguration | getCurrentConfiguration ()
| Return a copy of the current configuration. More...
void | restoreConfiguration ([in] XConfiguration xConfiguration)
| Replace the requested configuration with the given configuration and schedule an update of the current configuration. More...
Public Member Functions inherited from XConfigurationControllerRequestQueue
boolean | hasPendingRequests ()
| Return whether there are pending requests for configuration changes. More...
void | postChangeRequest ([in] XConfigurationChangeRequest xRequest)
| Add a request for a configuration change to the request queue. More...
Public Member Functions inherited from XConfigurationControllerBroadcaster
void | addConfigurationChangeListener ([in] XConfigurationChangeListener xListener, [in] string sEventType, [in] any aUserData)
| Add a new listener for configuration changes. More...
void | removeConfigurationChangeListener ([in] XConfigurationChangeListener xListener)
| Remove a listener for configuration changes. More...
void | notifyEvent ([in] ConfigurationChangeEvent aEvent)
| With this method other objects can send events to all the registered listeners. More...
Public Member Functions inherited from XResourceFactoryManager
void | addResourceFactory ([in] string sResourceURL, [in] XResourceFactory xResourceFactory)
| Register a new resource factory for the given URL. More...
void | removeResourceFactoryForURL ([in] string sResourceURL)
| Remove a resource factory for one type of resource. More...
void | removeResourceFactoryForReference ([in] XResourceFactory xResourceFactory)
| Remove a resource factory for all resource types it has been registered for. More...
XResourceFactory | getResourceFactory ([in] string sResourceURL)
| Return the resource factory that was previously registered for the given resource type. More...

## Detailed Description

The configuration controller is responsible for the management of the set of active resources.

There are two configurations of resources:

- The current configuration contains the set of currently active resources.
- The requested configuration describes what the current configuration should be. The requested configuration is changed usually by calling requestResourceActivation() and requestResourceDeactivation().

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.

1. when the last pending request for configuration changes has been processed,
2. when the update() method is called.
3. when the configuration manager it is unlocked after formerly being locked.

Requests for configuration changes are handled in a two step process:

1. 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.

   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.

2. 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:

- 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.

  The ConfigurationChangeEvent::ResourceId member is set to the requested resource. The ResourceObject member is not set.

- 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.

  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 starts.

  The requested configuration is available in the ConfigurationChangeEvent::Configuration member. The ResourceId and ResourceObject members are not set.

- ConfigurationUpdateEnd is sent after the update of the current configuration ends.

  The requested configuration is available in the ConfigurationChangeEvent::Configuration member. The ResourceId and ResourceObject members are not set.

- ResourceActivation is sent when a resource is activated, i.e. when a new object of a resource is created (or taken from a cache).

  The ResourceId and ResourceObject members are set to the XResourceId 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 XResourceId and object reference of the deactivated resource.

## Exported Interfaces

## ◆ XConfigurationControllerBroadcaster

interface XConfigurationControllerBroadcaster

## ◆ XConfigurationControllerRequestQueue

interface XConfigurationControllerRequestQueue

## ◆ XResourceFactoryManager

interface XResourceFactoryManager

## Member Function Documentation

## ◆ getCurrentConfiguration()

XConfiguration getCurrentConfiguration | ( |  | ) |

Return a copy of the current configuration.

Modifications to the returned configuration have no effect on the drawing framework.

## ◆ getRequestedConfiguration()

XConfiguration getRequestedConfiguration | ( |  | ) |

Return a copy of the requested configuration.

Modifications to the returned configuration have no effect on the drawing framework.

## ◆ getResource()

XResource getResource | ( | [in] XResourceId | xResourceId | ) |

Return the active resource specified by the given resource id.

Parameters

  xResourceId | A valid resource id. This should, but does not have to be, the resource id of an active resource.

Returns
  When the given resource id specifies an active resource then that resource is returned. Otherwise an empty reference is returned.

## ◆ lock()

void lock | ( |  | ) |

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().

## ◆ requestResourceActivation()

void requestResourceActivation | ( | [in] XResourceId | xResourceId,
|  | [in] ResourceActivationMode | eMode
| ) |  |

Request the activation of a resource.

The request is processed asynchronously. Notifications about configuration changes are sent after this call returns.

Parameters

  xResourceId | The resource whose activation is requested.
  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.

## ◆ requestResourceDeactivation()

void requestResourceDeactivation | ( | [in] XResourceId | xResourceId | ) |

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.

Parameters

  xResourceId | The resource whose deactivation is requested.

## ◆ restoreConfiguration()

void restoreConfiguration | ( | [in] XConfiguration | xConfiguration | ) |

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.

Parameters

  xConfiguration | This typically is a configuration that was obtained with an earlier getRequestedConfiguration() call.

## ◆ unlock()

void unlock | ( |  | ) |

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.

## ◆ update()

void update | ( |  | ) |

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.

The documentation for this interface was generated from the following file:

- com/sun/star/drawing/framework/XConfigurationController.idl