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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XConfigurationController.idl,v $
  10  * $Revision: 1.4 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_drawing_framework_XConfigurationController_idl__
  32 #define __com_sun_star_drawing_framework_XConfigurationController_idl__
  33
  34 #ifndef __com_sun_star_drawing_framework_ConfigurationChangeEvent_idl__
  35 #include <com/sun/star/drawing/framework/ConfigurationChangeEvent.idl>
  36 #endif
  37 #ifndef __com_sun_star_drawing_framework_XConfigurationControllerBroadcaster_idl__
  38 #include <com/sun/star/drawing/framework/XConfigurationControllerBroadcaster.idl>
  39 #endif
  40 #ifndef __com_sun_star_drawing_framework_XConfigurationControllerRequestQueue_idl__
  41 #include <com/sun/star/drawing/framework/XConfigurationControllerRequestQueue.idl>
  42 #endif
  43 #ifndef __com_sun_star_drawing_framework_XResourceFactoryManager_idl__
  44 #include <com/sun/star/drawing/framework/XResourceFactoryManager.idl>
  45 #endif
  46 #ifndef __com_sun_star_drawing_framework_ResourceActivationMode_idl__
  47 #include <com/sun/star/drawing/framework/ResourceActivationMode.idl>
  48 #endif
  49
  50 module com { module sun { module star { module drawing { module framework {
  51
  52 interface XConfigurationChangeListener;
  53 interface XConfigurationChangeRequest;
  54 interface XResourceId;
  55 interface XResource;
  56
  57 /** The configuration controller is responsible for the management of the
  58     set of active resources.
  59
  60     <p>There are two configurations of resources:<ul>
  61     <li>The current configuration contains the set of currently active
  62     resources.</li>
  63     <li>The requested configuration describes what the current configuration
  64     should be.  The requested configuration is changed usually by calling
  65     <member>requestResourceActivation()</member> and
  66     <member>requestResourceDeactivation()</member>.</li>
  67     </ul></p>
  68
  69     <p>When the two configurations differ then the current configuration is
  70     updated eventually to reflect the requested configuration.  An update
  71     takes place when the following three conditions are fullfilled.
  72     <ol>
  73     <li>when the last pending request for configuration changes has been
  74     processed,</li>
  75     <li>when the <member>update()</member> method is called.</li>
  76     <li>when the configuration manager it is unlocked after formerly being
  77     locked.</li>
  78     </ol></p>
  79
  80     <p>Requests for configuration changes are handled in a two step process:
  81     <ol>
  82     <li>First the requested configuration is updated iteratively: Every
  83     request that is being made by calling
  84     <member>requestResourceActivation()</member> or
  85     <member>requestResourceDeactivation()</member> results in one or more
  86     function objects, that each implement the
  87     <type>XConfigurationChangeRequest</type> interface.  These are inserted
  88     into a queue.  The request objects in the queue are processed
  89     asynchronously one at a time in the order in which they are inserted.
  90     Only when one request object is processed a change to the requested
  91     configuration is made.  These changes are broadcasted to registered
  92     <type>XConfigurationChangeListener</type> objects.  Listeners may
  93     decide to make requests that then are added to the queue.  For example
  94     when the view in the center pane is replaced by another view, some
  95     listeners may want to turn some side panes on or off, or show other
  96     views in the side panes.</p>
  97     <p>This process goes on until the queue of request objects becomes
  98     empty.  Until this point only the requested configuration has been
  99     modified.  No resources have been activated or deactivated.</p></li>
 100
 101     <li><p>The second update step activates or deactivates resources so that
 102     the current configuration (the one that comprises the actually active
 103     resources) reflects the requested configuration.</p>
 104     <p>The order in which resources are activated or deactivated depends on
 105     the dependency between the resources.  For example a view depends on the
 106     pane it is displayed in.  Resources that other resources depend on are
 107     activated first and deactivated last.  The order is undefined for
 108     unrelated resources.</p>
 109     <p>Note that the second update step may not be able to activate (or even to
 110     deactivate) all the requested resources.  Either because they are
 111     temporarily or permanently unavailable.  For example, during the
 112     start-up of a new Impress application the side panes are displayed
 113     with a visible delay because they are not provided sooner by the
 114     underlying framework.  Such anavailable resources are not forgotten but
 115     remain in the requested configuration.  Every time the configuration
 116     controller updates its current configuration these resources are
 117     requested once more.</li></ol></p>
 118
 119     <p>The configuration controller sends the following events:
 120     <ul>
 121     <li><const>ResourceActivationRequested</const> is sent when the
 122     activation of a resource has been requested and the resource is not yet
 123     active in the requested configuration.  The event is sent when the
 124     configuration change request is executed, not when the
 125     <member>requestResourceActivation()</member> call is made.</p>
 126     <p>The <member scope="ConfigurationChangeEvent">ResourceId</member> member is set to the requested
 127     resource.  The <member>ResourceObject</member> member is not
 128     set.</p></li>
 129     <li><const>ResourceDeactivationRequested</const> is sent when the
 130     deactivation of a resource has been requested and the resource is active
 131     in the requested configuration.  The event is sent when the
 132     configuration change request is executed that is created when for
 133     example <member>requestResourceDeactivation()</member> is called.</p>
 134     <p>The <member>ResourceId</member> member is set to the requested
 135     resource.  The <member>ResourceObject</member> member is not
 136     set.</p></li>
 137     <li><const>ConfigurationUpdateStart</const> is sent before the update of
 138     the current configuration starts.</p>
 139     <p>The requested configuration is available in the <member
 140     scope="ConfigurationChangeEvent">Configuration</member> member.  The
 141     <member>ResourceId</member> and <member>ResourceObject</member> members
 142     are not set.</p></li>
 143     <li><const>ConfigurationUpdateEnd</const> is sent after the update of
 144     the current configuration ends.</p>
 145     <p>The requested configuration is
 146     available in the <member scope="ConfigurationChangeEvent"
 147     >Configuration</member> member.  The <member>ResourceId</member> and
 148     <member>ResourceObject</member> members are not set.</p></li>
 149     <li><const>ResourceActivation</const> is sent when a resource is
 150     activated, i.e. when a new object of a resource is created (or taken
 151     from a cash).</p>
 152     <p>The <member>ResourceId</member> and <member>ResourceObject</member>
 153     members are set to the <type>XResourceId</type> and object reference of
 154     the activated resource.</p></li>
 155     <li><const>ResourceDeactivation</const> is sent when a resource is
 156     deactivated, i.e. when an object that previously was part of the
 157     configuration is removed from the configuration.</p>
 158     <p>The <member>ResourceId</member> and <member>ResourceObject</member>
 159     members are set to <type>XResourceId</type> and object reference of the
 160     deactivated resource.</p></li>
 161     </ul></p>
 162 */
 163 interface XConfigurationController
 164 {
 165     interface XConfigurationControllerRequestQueue;
 166     interface XConfigurationControllerBroadcaster;
 167     interface XResourceFactoryManager;
 168
 169     /** Request the activation of a resource.
 170         <p>The request is processed asynchronously.  Notifications about
 171         configuration changes are sent after this call returns.</p>
 172         @param xResourceId
 173             The resource whose activation is requested.
 174         @param eMode
 175             <p>When eMode is <const>REPLACE</const> then, before adding the
 176             resource activation to the request queue, similar resources
 177             linked to the same anchor are removed.  This makes it easer to
 178             switch between resources whose activation is mutually exclusive.
 179             For example, there can only be one view per pane, so before
 180             activating a new view the old one has to be deactivated.</p>
 181             <p>When eMode is <const>ADD</const> then the resource is requested
 182             without further changes.</p>
 183     */
 184     void requestResourceActivation (
 185         [in] XResourceId xResourceId,
 186         [in] ResourceActivationMode eMode);
 187
 188     /** Request the deactivation of a resource.
 189         <p>The request is processed asynchronously.  Notifications about
 190         configuration changes are sent after this call returns.</p>
 191         <p>Requesting the deactivation
 192         of a resource that is not active is not an error.</p>
 193         @param xResourceId
 194             The resource whose deactivation is requested.
 195     */
 196     void requestResourceDeactivation (
 197         [in] XResourceId xResourceId);
 198
 199
 200     /** Return the active resource specified by the given resource id.
 201         @param xResourceId
 202             A valid resource id.  This should, but does not have to be, the
 203             resource id of an active resource.
 204         @return
 205             When the given resource id specifies an active resource then
 206             that resource is returned.  Otherwise an empty reference is
 207             returned.
 208     */
 209     XResource getResource (
 210         [in] XResourceId xResourceId);
 211
 212     /** Lock the processing of configuration change requests.
 213         <p>This is only necessary when more than one change request is being
 214         made in a row.  It prevents an update being made (with all the visible UI
 215         changes) before all change requests are being made.</p>
 216         <p>Recursive <member>lock()</member> calls are recognized: the
 217         configuration controller is locked while <member>lock()</member> was
 218         called more often than <member>unlock()</member>.</p>
 219     */
 220     void lock ();
 221
 222     /** Unlock the processing of configuration change requests.
 223         <p>When <member>unlock()</member> is called as many times as
 224         <member>lock()</member> and the queue of configuration change
 225         requests is not empty the configuration controller continues the
 226         processing of the change requests.  An update of the current
 227         configuration will eventually being made.</p>
 228     */
 229     void unlock ();
 230
 231     /** Explicitly request an update of the current configuration.
 232         <p>Call it when a resource is activated or deactivated
 233         without the control and knowledge of the drawing framework.  Calling
 234         this method (from outside the drawing framework) should hardly every
 235         be necessary.</p>
 236     */
 237     void update ();
 238
 239     /** Return a copy of the requested configuration.
 240         <p>Modifications to the returned configuration have no effect on the
 241         drawing framework.</p>
 242     */
 243     XConfiguration getRequestedConfiguration ();
 244
 245     /** Return a copy of the current configuration.
 246         <p>Modifications to the returned configuration have no effect on the
 247         drawing framework.</p>
 248     */
 249     XConfiguration getCurrentConfiguration ();
 250
 251     /** Replace the requested configuration with the given configuration and
 252         schedule an update of the current configuration.
 253         <p>Together with the <member>getCurrentConfiguration()</member> and
 254         <member>getRequestedConfiguration()</member> methods this
 255         allows the saving and restoring of configurations.  However, the
 256         given configuration can have other origins then these methods.</p>
 257         <p>The given configuration is transformed into a list of of change
 258         requests so that the resulting reqeusted configuration equals the
 259         given configuration.  This has the advantage that not only the
 260         resource activations and deactivations but all configuration
 261         changes are properly broadcasted.</p>
 262         <p>Note that because of the configuration change notifications
 263         listeners can make more configuratio change requests, so that the
 264         resulting requested configuration can be different from the given
 265         configuration.</p>
 266         @param xConfiguration
 267             This typically is a configuration that was obtained with an
 268             earlier <member>getRequestedConfiguration()</member> call.
 269     */
 270     void restoreConfiguration ([in] XConfiguration xConfiguration);
 271 };
 272
 273 }; }; }; }; }; // ::com::sun::star::drawing::framework
 274
 275 #endif