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