INTEGRATION: CWS components1 (1.1.2); FILE ADDED

2007/02/20 09:15:56 af 1.1.2.4: #i68075# Code refactoring.
2007/01/22 12:40:27 af 1.1.2.3: #i68075 Introduction of XResourceId interface.
2006/09/07 13:42:00 af 1.1.2.2: #i68075# Transition from URL to ResourceId.
2006/08/23 08:26:02 af 1.1.2.1: #i68075# Initial revision.

1 files changed, 254 insertions, 0 deletions

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 000000000000..5336eaed393f
--- /dev/null
+++ b/offapi/com/sun/star/drawing/framework/XConfigurationController.idl
@@ -0,0 +1,254 @@
+/*************************************************************************
+ *
+ *  OpenOffice.org - a multi-platform office productivity suite
+ *
+ *  $RCSfile: XConfigurationController.idl,v $
+ *
+ *  $Revision: 1.2 $
+ *
+ *  last change: $Author: rt $ $Date: 2007-04-03 16:44:22 $
+ *
+ *  The Contents of this file are made available subject to
+ *  the terms of GNU Lesser General Public License Version 2.1.
+ *
+ *
+ *    GNU Lesser General Public License Version 2.1
+ *    =============================================
+ *    Copyright 2005 by Sun Microsystems, Inc.
+ *    901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *    This library is free software; you can redistribute it and/or
+ *    modify it under the terms of the GNU Lesser General Public
+ *    License version 2.1, as published by the Free Software Foundation.
+ *
+ *    This library is distributed in the hope that it will be useful,
+ *    but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *    Lesser General Public License for more details.
+ *
+ *    You should have received a copy of the GNU Lesser General Public
+ *    License along with this library; if not, write to the Free Software
+ *    Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *    MA  02111-1307  USA
+ *
+ ************************************************************************/
+
+#ifndef __com_sun_star_drawing_framework_XConfigurationController_idl__
+#define __com_sun_star_drawing_framework_XConfigurationController_idl__
+
+#ifndef __com_sun_star_uno_XInterface_idl__
+#include <com/sun/star/uno/XInterface.idl>
+#endif
+#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_ResourceActivationMode_idl__
+#include <com/sun/star/drawing/framework/ResourceActivationMode.idl>
+#endif
+
+module com { module sun { module star { module drawing { module framework {
+
+interface XConfigurationChangeListener;
+interface XConfigurationChangeRequest;
+
+/** The configuration controller is responsible for the synchronization of
+    other controllers for the management of resources like panes, views,
+    tool bars, and command groups.
+
+    <p>There are two configurations of resources:<ul>
+    <li>The current configuration describes the state of resources as
+    it is.</li>
+    <li>The requested configuration describes how it should be.  The
+    requested configuration is changed usually by calling
+    <member>requestResourceActivation()</member> and
+    <member>requestResourceDeactivation()</member>.  Other sub controllers
+    may offer other methods for requesting configuration changes.</li>
+    </ul></p>
+
+    <p>When the two differ then the current configuration is updated eventually
+    to reflect the requested one
+    <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 e.g. calling
+    <member>requestResourceActivation()</member> or
+    <member>requestResourceDeactivation()</member> results in one or more
+    function objects, that each implement the
+    <type>XConfigurationChangeRequest</type> 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.</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>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.</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 that is created when for
+    example <member>requestResourceActivation()</member> is called.</p>
+    <p>The <member>ResourceId</member> member is set to the requested
+    resource.  The <member>ResourceObject</member> member is not not
+    set.</p></li>
+    <li><const>ResourceDeactivationRequest</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 is started.</p>
+    <p>The requested configuration is available in the <type
+    scope="ConfigurationChangeEvent">Configuration</type> member.  The
+    <member>ResourceId</member> and <member>ResourceObject</member> members
+    are not set.</p></li>
+    <li><const>ConfigurationUpdateEnd</const> is sent before the update of
+    the current configuration is started.</p>
+    <p>The requested configuration is
+    available in the <type scope="ConfigurationChangeEvent"
+    >Configuration</type> member.  The <member>ResourceId</member> and
+    <member>ResourceObject</member> members are not set.</p></li>
+    </ul></p>
+
+    <p>The sub controllers that manage individual resources (like
+    <type>XPaneController</type>, <type>XViewController</type>,
+    <type>XToolbarController</type>, and <type>XCommandController</type>)
+    send the following events:
+    <ul>
+    <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>ResourceId</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>ResourceId</type> and object reference of the
+    deactivated resource.</p></li>
+    </ul></p>
+*/
+interface XConfigurationController
+{
+    interface XConfigurationControllerRequestQueue;
+    interface XConfigurationControllerBroadcaster;
+
+    /** 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);
+
+    /** Lock the processing of configuration change requests.
+        <p>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.</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 changes 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>The returned requested configuration reflects the current
+        configuration (more or less, there may be requested but anavailable
+        resources) after the last <member>update()</member> call and when no further
+        change requests have been made.
+    */
+    XConfiguration getConfiguration ();
+
+    /** Replace the requested configuraion with the given configuration and
+        update the current configuration accordingly.
+        <p>Together with the <member>getConfiguration()<member> method this
+        allows the saving and restoring of configurations.</p>
+        <p>The given configuration is treated like a bunch of change
+        requests made by calling the
+        <member>requestResourceActivation()</member> and
+        <member>requestResourceDeactivation()</member> methods.
+        Requested configuration changes are notified so that listeners can react.</p>
+        @param xConfiguration
+            This typically is a configuration that was obtained with an
+            earlier <member>getConfiguration()</member> call.
+    */
+    void restoreConfiguration ([in] XConfiguration xConfiguration);
+};
+
+}; }; }; }; }; // ::com::sun::star::drawing::framework
+
+#endif