Class Documentation

Name:If
Version:1.0
ID:ID_IF
Status:Unspecified
Category:Command
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2001. All rights reserved.
Short:  Allows conditional statements to be tested in the GUI.



Description

The If class provides a way of making decision statements inside the user interface. It is exceptionally useful for reacting to user events and is often used in buttons, menus and other clickable items that may require a decision to be made. When used in DML scripts, an If object will only be created if it is requested as static. In all other cases the DML interpreter will execute the if statement locally because the creation of an If object in such instances is unnecessary.

Support for else statements is also provided if an opposite reaction is required in case the statement is evaluated as being false. Here are some examples involving the typical use of both objects:

  <onclick>
    <if static statement="[object.x] = 10">
      ...statement is true...
    </if>
  </onclick>
  <if static test="=[object.x]+20" condition="<" compare="=[comp.x]*2">
    ...statement is true...
    <else>
      ...statement is false...
    </else>
  </if>

You will notice that you can use either the Statement field to set the condition statement, or you can break it down into the Test, Condition and Compare fields. In most cases a Statement setting is adequate, but when using calculations you must break the string into parts.

If you require the statement to be tested dynamically - i.e. if the Test and Compare parts need to be constantly re-calculated, use the '$' sign to prevent the early translation of object references. Example:

  <if static test="$=[object.x]+20$" condition="<" compare="$=[comp.x]*2$">

The If class also allows for the testing of object existence. This can be useful if you want to check if an object that you have previously created still exists in the system. Use of this feature is demonstrated as follows:

  <if exists="[myobject]"/>

You may also check for file existence, as demonstrated in this example:

  <if fileexists="athene:documents/readme.txt"/>

When creating an If statement, make sure that the variable types on either side match - i.e. a number should be compared to a number, not a string. If there is a "type mismatch" then the If object will treat the statement as being false.

Actions

The If class supports the following actions:

Activate  Activates an If object.
ClosingTag  If the object is non-static, this action will cause the If object to activate and then self-destruct.

Structure

The If object consists of the following public fields:

Compare  This field reflects the value that you want to make a comparison to.
Condition  Must be set to the condition that you want to use for statement testing.
Exists  Special field that can check for the existence of an object.
Statement  Writing to this field allows you to set the Compare, Condition and Test fields at once.
Static  Set to TRUE to make the object static.
Test  This field reflects the value that you want to be tested.
Field:Compare
Short:This field reflects the value that you want to make a comparison to.
Type:STRING
Status:Read/Write

The value that is being used for comparison must be set in this field. If the compare string starts with a calculation '=' or object reference '[' then the value will be calculated dynamically.


Field:Condition
Short:Must be set to the condition that you want to use for statement testing.
Type:LONG / TABLE
Status:Read/Write

This field specifies the condition that will be used when an If object performs its statement testing. Valid Condition values are:

   Value                  Equivalent Strings
   COND_NOT_EQUAL         !=, <>, NOT
   COND_EQUAL             =, ==, IS
   COND_LESS_THAN         <
   COND_LESS_EQUAL        <=
   COND_GREATER_THAN      >
   COND_GREATER_EQUAL     >=

Field:Exists
Short:Special field that can check for the existence of an object.
Type:OBJECTID
Status:Read/Write

If you need to check for the existence of an object, you can set this field to point to the object that you want to check for. The object should exist at the time of setting this field, thereafter the If object will check for its existence each time that the statement is re-evaluated.


Field:Statement
Short:Writing to this field allows you to set the Compare, Condition and Test fields at once.
Type:STRING
Status:Write

This field provides an easy way to set all three of the required If fields at once. Once set, the statement field is broken down into the relevant parts and then each field is set individually.

Setting this field can fail if the statement is not structured correctly (the required format is "Test Condition Compare", e.g. "10 > 5"). Do not use calculations when setting the field - this will only cause confusion, so set the If fields individually if you need to do this.


Field:Static
Short:Set to TRUE to make the object static.
Type:BOOLEAN
Status:Read/Init

By default, an If object will execute itself and then self-destruct when a closing tag is received. If you would rather that the object stays in the system, set this field to TRUE. If you do this, the only way to get the If object to test the statement is to call the Activate action.


Field:Test
Short:This field reflects the value that you want to be tested.
Type:STRING
Status:Read/Write

The value that is to be tested must be set in this field. If the test string starts with a calculation '=' or object reference '[' then the value will be calculated dynamically.