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