Class Documentation
If |
1.0 |
ID_IF |
Unspecified |
Command |
May 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2001. All rights reserved. |
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.
|
|