package votorola.s.gwt.stage; // Copyright 2012, Michael Allan.  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Votorola Software"), to deal in the Votorola Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Votorola Software, and to permit persons to whom the Votorola Software is furnished to do so, subject to the following conditions: The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Votorola Software. THE VOTOROLA SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE VOTOROLA SOFTWARE OR THE USE OR OTHER DEALINGS IN THE VOTOROLA SOFTWARE.

import votorola.a.web.gwt.GWTConfig;


/** An initializer of theatre state.  Initializers must ordinarily {@linkplain
  * Stage#addInitializer(TheatreInitializer) register with the stage}.  The {@linkplain
  * votorola.a.web.gwt.GWTConfig gwt.js} configuration script is implicitly registered, as
  * some of the <a
  * href='../../../../votorola/a/web/gwt/class-use/GWTInitCallback.html'>configuration
  * methods</a> exposed to it are restricted to initializers.  Each registered initializer
  * (plus <code>gwt.js</code>) receives a call to either <strong>A</strong>
  * <code>initFrom</code> and then <code>initFromComplete</code>, or <strong>B</strong>
  * <code>initTo</code> and then <code>initToComplete</code>, but never both A and B.
  *
  *     @see <a href='Stage.html#persistPage'>Persistence of state in a single page</a>
  */
public @GWTConfig interface TheatreInitializer
{


   // - T h e a t r e - I n i t i a l i z e r --------------------------------------------


    /** Here the prop or other component initializes its own properties by reference to a
      * previously initialized stage.  This method is called on page load after the state
      * of the stage has been restored via <a href='Stage.html#persistPage'>single-page
      * persistence</a>.  Writing to the stage is permitted here, though ordinarily only
      * page authors will do this and only in cases where a stage property needs to be
      * re-initialized owing to a change in the environment, such as a structual change to
      * the page.
      *
      * <p>The equivalent JavaScript callback is the global function
      * <code>voGWTConfig.s_gwt_stage_Stage_initFrom</code>.  It may be defined in the
      * {@linkplain votorola.a.web.gwt.GWTConfig gwt.js} configuration script, for
      * example.</p>
      *
      *     @param rPending whether the referrer (if any) remains to be resolved.  If this
      *       flag is true, then initialization will eventually complete at {@linkplain
      *       #initUltimately(Stage,TheatrePage) initUltimately}; otherwise it will
      *       complete earlier at {@linkplain #initFromComplete(Stage,boolean)
      *       initFromComplete}.
      */
    public void initFrom( Stage s, boolean rPending );



    /** Signals that <code>initFrom</code> was called for all props and that immediate
      * initialization of the stage is complete and the associated events have fired.
      * Referrer resolution may yet follow depending on the value of
      * <code>rPending</code>.  This method is called only when the state is initialized
      * by restoration, i.e. in those cases where <code>initFrom</code> is called.
      *
      * <p>The equivalent JavaScript callback is the global function
      * <code>voGWTConfig.s_gwt_stage_Stage_initFromComplete</code>.  It may be defined in
      * the {@linkplain votorola.a.web.gwt.GWTConfig gwt.js} configuration script, for
      * example.</p>
      *
      *     @param rPending true if initialization will eventually complete at {@linkplain
      *       #initUltimately(Stage,TheatrePage) initUltimately}; false if this is the end
      *       of it.
      */
    public void initFromComplete( Stage s, boolean rPending );



    /** Here the prop or other component initializes the properties of the stage.  This
      * method is called on page load when a new page is created from scratch and the
      * referrer (if any) cannot immediately be resolved.  Referrer resolution will be
      * signaled by a subsequent call to {@linkplain #initUltimately(Stage,TheatrePage)
      * initUltimately}.
      *
      * <p>The equivalent JavaScript callback is the global function
      * <code>voGWTConfig.s_gwt_stage_Stage_initTo</code>.  It may be defined in the
      * {@linkplain votorola.a.web.gwt.GWTConfig gwt.js} configuration script, for
      * example.</p>
      */
    public void initTo( Stage s );



    /** Here the prop or other component initializes the properties of the stage.  This
      * method is called on page load when a new page is created from scratch and the
      * referrer (if any) can immediately be resolved.  Referrer resolution enables <a
      * href='Stage.html#persistCrossPage' target='_top'>cross-page persistence</a>.  As a
      * general rule, a prop may transfer state from the referrer to the stage if it also
      * provides the user with both control over that state <em>and</em> the ability to
      * restore it.  Thus the user might transit a link from one page (referrer) in which
      * a difference is shown, for example, to a new page (destination) where the same
      * difference is automatically selected by a prop that makes use of the
      * <code>r</code> parameter.  The prop will also provide a means of selecting other
      * differences and of re-selecting the original one, such that the user need never
      * navigate back and re-transit the link for this purpose.
      *
      * <p>A prop ought generally to avoid transferring a given property from a referrer
      * when it already has a non-default value on the destination, whether set by the
      * scene or by another prop.  By the same token, an initializer that sets a default
      * value for a property, such as {@linkplain Stage#setDefaultActorName(String) actor
      * name}, will typically null the ordinary value to ensure that the default is
      * immediately exhibited.  It is recommended however that defaults be set earlier,
      * e.g. during module initialization.</p>
      *
      * <p>The equivalent JavaScript callback is the global function
      * <code>voGWTConfig.s_gwt_stage_Stage_initTo</code>.  It may be defined in the
      * {@linkplain votorola.a.web.gwt.GWTConfig gwt.js} configuration script, for
      * example.</p>
      *
      *     @param r the theatre page that linked to this page (referrer), or null if
      *       there was none.
      */
    public void initTo( Stage s, TheatrePage r );



    /** Signals that <code>initTo</code> was called for all props and that immediate
      * initialization of the stage is complete and the associated events have fired.
      * Referrer resolution may yet follow depending on the value of
      * <code>rPending</code>.  This method is called only when the state is initialized
      * from scratch, i.e. in those cases where <code>initTo</code> is called.
      *
      * <p>The equivalent JavaScript callback is the global function
      * <code>voGWTConfig.s_gwt_stage_Stage_initToComplete</code>.  It may be defined in
      * the {@linkplain votorola.a.web.gwt.GWTConfig gwt.js} configuration script, for
      * example.</p>
      *
      *     @param rPending true if initialization will eventually complete at {@linkplain
      *       #initUltimately(Stage,TheatrePage) initUltimately}; false if this is the end
      *       of it.
      */
    public void initToComplete( Stage s, boolean rPending );



    /** Signals that deferred resolution of the referrer is now complete.  This method is
      * called last of all, and only if <code>rPending</code> was asserted in one of the
      * previous initialization calls.  Resolution is never deferred longer than {@value
      * votorola.s.gwt.stage.ReferrerRelayer#MAX_REFERRER_RESOLUTION_MS} milliseconds.
      *
      * <p>The equivalent JavaScript callback is the global function
      * <code>voGWTConfig.s_gwt_stage_Stage_initUltimately</code>.  It may be defined in
      * the {@linkplain votorola.a.web.gwt.GWTConfig gwt.js} configuration script, for
      * example.</p>
      *
      *     @param r the theatre page that linked to this page (referrer), or null if
      *       there was none.  The prop may transfer state from the referrer as noted for
      *       {@link #initTo(Stage,TheatrePage) initTo}(stage,referrer), but with the
      *       further stipulation that any state changes by the user subsequent to the
      *       completion of immediate initialization ought to be honoured and not
      *       overidden.
      */
    public void initUltimately( Stage s, TheatrePage r );


}