1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
/* -*- 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 <com/sun/star/drawing/framework/ConfigurationChangeEvent.idl>
#include <com/sun/star/drawing/framework/XConfigurationControllerBroadcaster.idl>
#include <com/sun/star/drawing/framework/XConfigurationControllerRequestQueue.idl>
#include <com/sun/star/drawing/framework/XResourceFactoryManager.idl>
#include <com/sun/star/drawing/framework/ResourceActivationMode.idl>
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.
<p>There are two configurations of resources:<ul>
<li>The current configuration contains the set of currently active
resources.</li>
<li>The requested configuration describes what the current configuration
should be. The requested configuration is changed usually by calling
<member>requestResourceActivation()</member> and
<member>requestResourceDeactivation()</member>.</li>
</ul></p>
<p>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.
<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 calling
<member>requestResourceActivation()</member> or
<member>requestResourceDeactivation()</member> results in one or more
function objects, that each implement the
<type>XConfigurationChangeRequest</type> 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
<type>XConfigurationChangeListener</type> 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.</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>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.</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 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.</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, not when the
<member>requestResourceActivation()</member> call is made.</p>
<p>The <member scope="ConfigurationChangeEvent">ResourceId</member> member is set to the requested
resource. The <member>ResourceObject</member> member is not
set.</p></li>
<li><const>ResourceDeactivationRequested</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 starts.</p>
<p>The requested configuration is available in the <member
scope="ConfigurationChangeEvent">Configuration</member> member. The
<member>ResourceId</member> and <member>ResourceObject</member> members
are not set.</p></li>
<li><const>ConfigurationUpdateEnd</const> is sent after the update of
the current configuration ends.</p>
<p>The requested configuration is
available in the <member scope="ConfigurationChangeEvent"
>Configuration</member> member. The <member>ResourceId</member> and
<member>ResourceObject</member> members are not set.</p></li>
<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>XResourceId</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>XResourceId</type> and object reference of the
deactivated resource.</p></li>
</ul></p>
*/
interface XConfigurationController
{
interface XConfigurationControllerRequestQueue;
interface XConfigurationControllerBroadcaster;
interface XResourceFactoryManager;
/** 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);
/** 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.
<p>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.</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 change 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>Modifications to the returned configuration have no effect on the
drawing framework.</p>
*/
XConfiguration getRequestedConfiguration ();
/** Return a copy of the current configuration.
<p>Modifications to the returned configuration have no effect on the
drawing framework.</p>
*/
XConfiguration getCurrentConfiguration ();
/** Replace the requested configuration with the given configuration and
schedule an update of the current configuration.
<p>Together with the <member>getCurrentConfiguration()</member> and
<member>getRequestedConfiguration()</member> methods this
allows the saving and restoring of configurations. However, the
given configuration can have other origins then these methods.</p>
<p>The given configuration is transformed into a list of 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.</p>
<p>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.</p>
@param xConfiguration
This typically is a configuration that was obtained with an
earlier <member>getRequestedConfiguration()</member> call.
*/
void restoreConfiguration ([in] XConfiguration xConfiguration);
};
}; }; }; }; }; // ::com::sun::star::drawing::framework
#endif
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
