<state>
A description of an instance hierarchy that can be applied and removed at runtime.

JavaScript: lz.state
extends <node> » lz.Eventable »

A state is an object that holds its children and attributes for creation or application at a later time — when the state's apply method is called. In addition to representing visual state by adding and removing children from a view, states are often used to control constraints which are applied and removed at different times during the run of an application.

For the most part, the declarative style used in OpenLaszlo applications represents an initial state for the application. All modification to application state can be made using the script API's, but it is often convenient to declaratively describe a bit of application state which may be selectively applied or removed at runtime. The <state> tag is provided for this purpose.

Everything within a <state> tag acts as if it were written inside the parent when the state is applied. States can contain attributes, methods, and other nodes.

When a state is removed, any children or constraints created when the state was applied are then removed, but attributes that were set by the application of the state are not restored.

Example 19. Using states to represent the min/max state of a window.

<canvas>
   <window id="demo" title="state demo" width="400" height="300">
     <attribute name="maximized" value="true"/>

     <state name="big" applied="${demo.maximized}">
       <animatorgroup duration="1000" process="simultaneous">
         <animator attribute="width" to="400"/>
         <animator attribute="height" to="300"/>
         <animator attribute="x" to="100"/>
         <animator attribute="y" to="100"/>
       </animatorgroup>
     </state>

     <state name="little" applied="${! demo.maximized}">
       <animatorgroup duration="1000" process="simultaneous">
         <animator attribute="width" to="170"/>
         <animator attribute="height" to="100"/>
         <animator attribute="x" to="0"/>
         <animator attribute="y" to="0"/>
       </animatorgroup>
     </state>

     <button text="Toggle" placement="title_area" align="right" height="16">
       <handler name="onclick">
         demo.setAttribute('maximized', (! demo.maximized));
       </handler>
     </button>

     <text name="display" align="center" valign="middle" width="120" multiline="true"/>

     <handler name="onapplied" reference="big">
       demo.display.format("big.applied = %s\nlittle.applied = %s",
                           demo.big.applied, demo.little.applied);
     </handler>
   </window>
 </canvas>

By default, states are not applied. It is often convenient to assign this attribute as a constraint in the tag. For example: <state name="mystate" applied="${parent.opened}" will apply the state when parent.opened is true.

Note that for any script that is in the tag, the parent is the tag that encloses the script. Any method that is declared within the state can only be called after the state is applied, and upon application this will refer to the view that encloses the state, rather than the state itself.

Attributes

Name (CSS property) Type (tag) Type (js) Default Category
applied boolean Boolean false read/write
  Whether or not the state is applied. setAttribute('applied', true) will apply the state. setAttribute('applied', false) will remove the state.
pooling boolean Boolean false read/write
  If true, the state will merely hide any views it has created when it is removed (not applied), instead of destroying them.

Methods

apply()
state.apply();
Applies the state to the state's parent. If the state is already applied, has no effect. This is the programmatic equivalent of setAttribute('applied', true).

remove()
state.remove();
Removes the constraints and views made when the state was applied. This method does not restore the previous values of any attributes that were changed by the state. This is the programmatic equivalent of setAttribute('applied', false).

Methods inherited from lz.Eventable

destroy, setAttribute

Events

Name Description
onapply Sent before a state is applied. The event argument is the state that is being applied.
onremove Sent before a state is removed. The event argument is the state that is being removed.

Events inherited from <node>

onconstruct, ondata, oninit

Events inherited from lz.Eventable

ondestroy