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