<html> <head> <title>Interface XConfigurationController</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" type="text/css" href="../../../../../idl.css"> </head> <body> <div id="adc-idlref"> <a name="_top_"> </a><table class="navimain" border="0" cellpadding="3"> <tr> <td class="navimain"><a href="../../module-ix.html" class="navimain">Overview</a></td> <td class="navimain"><a href="module-ix.html" class="navimain">Module</a></td> <td class="navimain"><a href="XConfigurationController-xref.html" class="navimain">Use</a></td> <td class="navimainnone">Devguide</td> <td class="navimain"><a href="../../../../../index-files/index-1.html" class="navimain">Index</a></td> </tr> </table> <table class="navisub" border="0" cellpadding="0"> <tr> <td class="navisub"><a href="#MethodsSummary" class="navisub">Methods' Summary</a></td> <td class="navisub"><a href="#MethodsDetails" class="navisub">Methods' Details</a></td> <td class="navisub">Attributes' Summary</td> <td class="navisub">Attributes' Details</td> </tr> </table> <hr> <table border="0" width="100%" cellpadding="5" cellspacing="3" class="title-table" style="margin-bottom:6pt;"> <tr> <td><p class="namechain"><a href="../../../../../module-ix.html" class="namechain">::</a> <a href="../../../../module-ix.html" class="namechain">com</a> :: <a href="../../../module-ix.html" class="namechain">sun</a> :: <a href="../../module-ix.html" class="namechain">star</a> :: <a href="../module-ix.html" class="namechain">drawing</a> :: <a href="module-ix.html" class="namechain">framework</a> :: </p> </td> </tr> <tr> <td class="title"><table class="title-table" width="99%"> <tr> <td width="25%" class="title2">unpublished </td> <td width="50%" class="title">interface XConfigurationController</td> <td width="*"/></tr> </table> </td> </tr> <tr> <td><dl> <dt><b>Base Interfaces</b></dt> <dd><pre style="font-family:monospace;"><strong>XConfigurationController</strong> ┣ <a href="XConfigurationControllerRequestQueue.html">XConfigurationControllerRequestQueue</a> ┗ <a href="XConfigurationControllerBroadcaster.html">XConfigurationControllerBroadcaster</a> </pre></dd> <dd><a name/><table border="1" width="100%" cellpadding="5" cellspacing="0" class="crosstitle"> <tr> <td class="imsum_left"><a href="XConfigurationControllerRequestQueue.html">XConfigurationControllerRequestQueue</a></td> <td class="imsum_right"><dl> <dt>(referenced interface's summary:)</dt> <dd>The request queue of the configuration controller handles requests for changes to the current configuration. </dd> </dl> </td> </tr> <tr> <td class="imsum_left"><a href="XConfigurationControllerBroadcaster.html">XConfigurationControllerBroadcaster</a></td> <td class="imsum_right"><dl> <dt>(referenced interface's summary:)</dt> <dd>Manage the set of registered event listeners and the event notification for a configuration controller. </dd> </dl> </td> </tr> </table> </dd> </dl> </td> </tr> <tr> <td><dl> <dt><b>Description</b></dt> <dd>The configuration controller is responsible for the synchronization of other controllers for the management of resources like panes, views, tool bars, and command groups. </dd> <dd><p>There are two configurations of resources:<ul> <li>The current configuration describes the state of resources as it is.</li> <li>The requested configuration describes how it should be. The requested configuration is changed usually by calling <a href="XConfigurationController.html#requestResourceActivation()">requestResourceActivation()</a> and <a href="XConfigurationController.html#requestResourceDeactivation()">requestResourceDeactivation()</a>. Other sub controllers may offer other methods for requesting configuration changes.</li> </ul></p> <p>When the two differ then the current configuration is updated eventually to reflect the requested one <ol> <li>when the last pending request for configuration changes has been processed,</li> <li>when the <a href="XConfigurationController.html#update()">update()</a> 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 e.g. calling <a href="XConfigurationController.html#requestResourceActivation()">requestResourceActivation()</a> or <a href="XConfigurationController.html#requestResourceDeactivation()">requestResourceDeactivation()</a> results in one or more function objects, that each implement the <a href="XConfigurationChangeRequest.html">XConfigurationChangeRequest</a> interface, being inserted into a queue. The request objects in the queue are processed 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. Listeners may decide to add more request objects 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>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 frame the side panes are displayed with a visible delay because they are not provided sooner by the underlying framework. Such anavailable 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><b>ResourceActivationRequested</b> 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 that is created when for example <a href="XConfigurationController.html#requestResourceActivation()">requestResourceActivation()</a> is called.</p> <p>The <a href="XConfigurationController.html#ResourceId">ResourceId</a> member is set to the requested resource. The <a href="XConfigurationController.html#ResourceObject">ResourceObject</a> member is not not set.</p></li> <li><b>ResourceDeactivationRequest</b> 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 <a href="XConfigurationController.html#requestResourceDeactivation()">requestResourceDeactivation()</a> is called.</p> <p>The <a href="XConfigurationController.html#ResourceId">ResourceId</a> member is set to the requested resource. The <a href="XConfigurationController.html#ResourceObject">ResourceObject</a> member is not set.</p></li> <li><b>ConfigurationUpdateStart</b> is sent before the update of the current configuration is started.</p> <p>The requested configuration is available in the ConfigurationChangeEvent::Configuration member. The <a href="XConfigurationController.html#ResourceId">ResourceId</a> and <a href="XConfigurationController.html#ResourceObject">ResourceObject</a> members are not set.</p></li> <li><b>ConfigurationUpdateEnd</b> is sent before the update of the current configuration is started.</p> <p>The requested configuration is available in the ConfigurationChangeEvent::Configuration member. The <a href="XConfigurationController.html#ResourceId">ResourceId</a> and <a href="XConfigurationController.html#ResourceObject">ResourceObject</a> members are not set.</p></li> </ul></p> <p>The sub controllers that manage individual resources (like <a href="XPaneController.html">XPaneController</a>, <a href="XViewController.html">XViewController</a>, ::XToolbarController, and <a href="XCommandController.html">XCommandController</a>) send the following events: <ul> <li><b>ResourceActivation</b> 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 <a href="XConfigurationController.html#ResourceId">ResourceId</a> and <a href="XConfigurationController.html#ResourceObject">ResourceObject</a> members are set to the <a href="ResourceId.html">ResourceId</a> and object reference of the activated resource.</p></li> <li><b>ResourceDeactivation</b> 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 <a href="XConfigurationController.html#ResourceId">ResourceId</a> and <a href="XConfigurationController.html#ResourceObject">ResourceObject</a> members are set to <a href="ResourceId.html">ResourceId</a> and object reference of the deactivated resource.</p></li> </ul></p> </dd> </dl> </td> </tr> </table> <hr> <a name="MethodsSummary"/><table border="1" width="100%" cellpadding="5" cellspacing="0" class="subtitle"> <tr> <td class="subtitle" colspan="2">Methods' Summary</td> </tr> <tr> <td class="imsum_left"><a href="#requestResourceActivation">requestResourceActivation</a></td> <td class="imsum_right">Request the activation of a resource. </td> </tr> <tr> <td class="imsum_left"><a href="#requestResourceDeactivation">requestResourceDeactivation</a></td> <td class="imsum_right">Request the deactivation of a resource. </td> </tr> <tr> <td class="imsum_left"><a href="#lock">lock</a></td> <td class="imsum_right">Lock the processing of configuration change requests. </td> </tr> <tr> <td class="imsum_left"><a href="#unlock">unlock</a></td> <td class="imsum_right">Unlock the processing of configuration changes requests. </td> </tr> <tr> <td class="imsum_left"><a href="#update">update</a></td> <td class="imsum_right">Explicitly request an update of the current configuration. </td> </tr> <tr> <td class="imsum_left"><a href="#getConfiguration">getConfiguration</a></td> <td class="imsum_right">Return a copy of the requested configuration. </td> </tr> <tr> <td class="imsum_left"><a href="#restoreConfiguration">restoreConfiguration</a></td> <td class="imsum_right">Replace the requested configuraion with the given configuration and update the current configuration accordingly. </td> </tr> </table> <a name="MethodsDetails"/><table border="1" width="100%" cellpadding="5" cellspacing="0" class="subtitle"> <tr> <td class="subtitle">Methods' Details</td> </tr> <tr> <td class="imdetail"><a name="requestResourceActivation" class="membertitle">requestResourceActivation</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">void</td> </tr> <tr> <td valign="top"><b>requestResourceActivation</b>(</td> <td valign="top">[in] <a href="XResourceId.html">XResourceId</a></td> <td valign="bottom"> xResourceId,</td> </tr> <tr> <td/><td valign="top">[in] <a href="ResourceActivationMode.html">ResourceActivationMode</a></td> <td valign="bottom"> eMode );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>Request the activation of a resource. </dd> <dd><p>The request is processed asynchronously. Notifications about configuration changes are sent after this call returns.</p> </dd> <dt><b>Parameter xResourceId</b></dt> <dd>The resource whose activation is requested. </dd> <dt><b>Parameter eMode</b></dt> <dd><p>When eMode is <b>REPLACE</b> 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 <b>ADD</b> then the resource is requested without further changes.</p> </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="requestResourceDeactivation" class="membertitle">requestResourceDeactivation</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">void</td> </tr> <tr> <td valign="top"><b>requestResourceDeactivation</b>(</td> <td valign="top">[in] <a href="XResourceId.html">XResourceId</a></td> <td valign="bottom"> xResourceId );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>Request the deactivation of a resource. </dd> <dd><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> </dd> <dt><b>Parameter xResourceId</b></dt> <dd>The resource whose deactivation is requested. </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="lock" class="membertitle">lock</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">void</td> </tr> <tr> <td valign="top"><b>lock</b>();</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>Lock the processing of configuration change requests. </dd> <dd><p>This is only necessary when more than one change request is being made. It prevents an update being made (with all the visible UI changes) before all change requests are being made.</p> <p>Recursive <a href="#lock()">lock()</a> calls are recognized: the configuration controller is locked while <a href="#lock()">lock()</a> was called more often than <a href="#unlock()">unlock()</a>.</p> </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="unlock" class="membertitle">unlock</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">void</td> </tr> <tr> <td valign="top"><b>unlock</b>();</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>Unlock the processing of configuration changes requests. </dd> <dd><p>When <a href="#unlock()">unlock()</a> is called as many times as <a href="#lock()">lock()</a> 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> </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="update" class="membertitle">update</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">void</td> </tr> <tr> <td valign="top"><b>update</b>();</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>Explicitly request an update of the current configuration. </dd> <dd><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> </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="getConfiguration" class="membertitle">getConfiguration</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3"><a href="XConfiguration.html">XConfiguration</a></td> </tr> <tr> <td valign="top"><b>getConfiguration</b>();</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>Return a copy of the requested configuration. </dd> <dd><p>The returned requested configuration reflects the current configuration (more or less, there may be requested but anavailable resources) after the last <a href="#update()">update()</a> call and when no further change requests have been made. </dd> </dl> </td> </tr> </table> </td> </tr> <tr> <td class="imdetail"><a name="restoreConfiguration" class="membertitle">restoreConfiguration</a><table border="0" width="96%" cellpadding="5" cellspacing="0" class="table-in-method" bgcolor="#ffffff" align="center"> <tr> <td><table class="table-in-method" border="0"> <tr> <td valign="top" colspan="3">void</td> </tr> <tr> <td valign="top"><b>restoreConfiguration</b>(</td> <td valign="top">[in] <a href="XConfiguration.html">XConfiguration</a></td> <td valign="bottom"> xConfiguration );</td> </tr> </table> <hr> <dl> <dt><b>Description</b></dt> <dd>Replace the requested configuraion with the given configuration and update the current configuration accordingly. </dd> <dd><p>Together with the this allows the saving and restoring of configurations.</p> <p>The given configuration is treated like a bunch of change requests made by calling the <a href="#requestResourceActivation()">requestResourceActivation()</a> and <a href="#requestResourceDeactivation()">requestResourceDeactivation()</a> methods. Requested configuration changes are notified so that listeners can react.</p> </dd> <dt><b>Parameter xConfiguration</b></dt> <dd>This typically is a configuration that was obtained with an earlier <a href="#getConfiguration()">getConfiguration()</a> call. </dd> </dl> </td> </tr> </table> </td> </tr> </table> <a href="#_top_">Top of Page</a><hr size="3"><p class="copyright" align="center">Copyright © 2008 Sun Microsystems, Inc.</p> </div> <!-- id="adc-idlref" --> </body> </html>