From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:06:44 +0200 Subject: Adding upstream version 4:7.4.7. Signed-off-by: Daniel Baumann --- .../drawing/framework/XConfigurationController.idl | 255 +++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 offapi/com/sun/star/drawing/framework/XConfigurationController.idl (limited to 'offapi/com/sun/star/drawing/framework/XConfigurationController.idl') 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 000000000..eaac2123b --- /dev/null +++ b/offapi/com/sun/star/drawing/framework/XConfigurationController.idl @@ -0,0 +1,255 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * 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 . + */ + +#ifndef __com_sun_star_drawing_framework_XConfigurationController_idl__ +#define __com_sun_star_drawing_framework_XConfigurationController_idl__ + +#include +#include +#include +#include +#include + +module com { module sun { module star { module drawing { module framework { + +interface XConfigurationChangeListener; +interface XConfigurationChangeRequest; +interface XResourceId; +interface XResource; + +/** 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. +
  2. when the update() method is called.
    3. +
  3. when the configuration manager it is unlocked after formerly being + locked.
    4. +

+ +

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

  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.

    • +

+*/ +interface XConfigurationController +{ + interface XConfigurationControllerRequestQueue; + interface XConfigurationControllerBroadcaster; + interface XResourceFactoryManager; + + /** Request the activation of a 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