[UP]
Data types
 Data types (O'Caml)
 Data types (Perl)
    
The representation of the data types in Perl

In the Perl environment, the dialog data types are represented as Perl classes:

  • UI::Variable::String is the class representing the string type

  • UI::Variable::Enum is the class representing the type of declared enumerators

  • UI::Variable::DynEnum is the class representing the type dynamic-enumerator

  • UI::Variable::Dialog is the class representing the dialog type

  • UI::Variable::Alist is the class representing associative lists

Before you can access these classes, you must load them: 

use UI::Variable;

- loads all classes at once.

In the following explanations, the objects of these classes are called "value containers", as they serve as containers for a low-level representation of values[1].

The interfaces of the value containers

UI::Variable::String

A string container can be created by 

    my $s_container = new UI::Variable::String("The string");

The string of such a container can be read by calling 

    my $s = $s_container->value;    # returns "The String"

Note that it is normally not necessary to use string containers as there are special access methods for string variables (string_variable and set_string_variable).

UI::Variable::Enum

A container for a declared enumerator can be formed by 

    my $e_container = new UI::Variable::Enum("x1","x2",...);

where x1,x2,... are the internal items of the enumerator. If necessary, it is possible to add a new internal item to an already existing container: 

    $e_container->add("x3");

The list of internal items of an enumerator can be read by 

    my @items = $e_container->value;  # returns ("x1","x2","x3")

The number of items: 

    my $n = $e_container->length;

To iterate over the items of a container, apply this method: 

    $e_container->iter( sub { my $item = shift; .... } )

UI::Variable::DynEnum

A dynamic enumerator consisting of the internal items x1, x2, .. and the corresponding external values y1, y2, ... can be formed by: 

    my $d_container = new UI::Variable::DynEnum(["x1","y1"],["x2","y2"],...);

There is also a method to add another pair: 

    $d_container->add("x3","y3");

The list of pairs can be requested by calling: 

    my @pairs = $d_container->value;

In this example, @pairs is equal to the list 

    (["x1","y1"],["x2","y2"],["x3","y3"])

The number of pairs: 

    my $n = $d_container->length;

To iterate over the items of a container, apply this method: 

    $d_container->iter( sub { my ($x,$y) = @_; .... } )

Here, $x is the interal and $y the external value of the current pair that is being visited during the iteration.

UI::Variable::Dialog

An UI::Dialog instance $dlgobj can be put into a value container by 

    my $o_container = new UI::Variable::Dialog($dlgobj);

To get the dialog back, do 

    my $dlgobj = $o_container->value;

UI::Variable::Alist

An associative list of values is handled like a dynamic enumerator. An alist container consisting of the keys i1,i2,... and the corresponding values v1,v2,... can be created by 

    my $a_container = new UI::Variable::Alist( ["i1",$v1], ["i2",$v2], ... );

Here, i1, i2, etc must be strings, and $v1, $v2, etc must be value containers (UI::Variable::String, or -::Enum, or -::DynEnum, or -::Object). It is possible to add another key/value mapping: 

    $a_container->add("i3",$v3);

The list of pairs can be requested by calling: 

    my @pairs = $a_container->value;

In this example, @pairs is equal to the list 

    (["i1",$v1],["i2",$v2],["i3",$v3])

The number of pairs: 

    my $n = $a_container->length;

To iterate over the items of a container, apply this method: 

    $a_container->iter( sub { my ($i,$v) = @_; .... } )

Here, $i is the index (key) and $v the corresponding value of the current pair that is being visited during the iteration.

Getting values of variables

Let $ui be the UI::Dialog in the following examples. In order to get a variable of arbitrary type one can invoke the variable method: 

    my $v = $ui->variable("name");

This method returns a value container, i.e. one object of the classes UI::Variable::String, -::Enum, -::DynEnum, -::Dialog, or -::Alist. For instance, if the object is a string, the scalar value of the string can be obtained by: 

    my $s = $ui->variable("name")->value;

For convenience, the types string and enumerator are supported specially. To read a string scalar, one can alternatively invoke: 

    my $s = $ui->string_variable("name");

Enumerator values can be accessed by calling: 

    my @e = $ui->enum_variable("name");

@e will be the list of internal items.

Setting values of variables

The method set_variable changes the value of a variable. You must pass the name of the variable and the value container $v to the method: 

    $ui->set_variable("name", $v);

For example, to set the value of a string variable to "happy", the following statement can be executed: 

    $ui->set_variable("name", new UI::Variable::String("happy"));

For convenience, there is a "shortcut method" for strings: 

    $ui->set_string_variable("name", "happy");

Resetting values of variables

The following method sets the value of a variable back to its initial value - either the default specified in the ui:variable element, or the null value of the type: 

    $ui->unset_variable("name");

The dot notation

As a more convenient method to access variables of inner dialogs, it is possible to refer to variables by the dot notation. For example, if there is a dialog variable d, and the string variable s is defined in the dialog that is currently the value of d, you can get the string contents of s by this expression: 

my $s = $ui->string_variable("d.s");

This is a shorthand notation for: 

my $d = $ui->variable("d")->value();
die "Dialog is empty!" if (!defined($d));
my $s = $d->string_variable("s");

See the section about Dot notation (v1.v2) for details.

[1]
The containers contain methods to map the contained values to the corresponding O'Caml value, and to map O'Caml values back. Actually, the O'Caml values are the low-level representation from the view of the Perl bindings.