Events (Perl)

[UP]
Events

Events (Perl)

The representation of events in Perl

Events are represented as arrays whose components contain the properties of the events.

Button event: A button event for the button $n is represented as
```
( "BUTTON", $n )
```
Indexed button event: A button event for the button $n with index $i is represented as
```
( "INDEXED_BUTTON", $n, $i )
```
Imagebutton event: An imagebutton event for the button $n is represented as
```
( "IMAGE_BUTTON", $n, $x, $y )
```
The coordinate ($x,$y) is the position of the click relative to the image.
Indexed imagebutton event: An imagebutton event for the button $n with index $i is represented as
```
( "INDEXED_IMAGE_BUTTON", $n, $i, $x, $y )
```
The coordinate ($x,$y) is the position of the click relative to the image.
Hyperlink event: A hyperlink event for the anchor $n is represented as
```
( "BUTTON", $n )
```
The representations for hyperlinks and for buttons are intentionally the same.
Indexed hyperlink event: A hyperlink event for the anchor $n with index $i is represented as
```
( "INDEXED_BUTTON", $n, $i )
```
The representations for hyperlinks and for buttons are intentionally the same.
Popup request: A popup request is represented as
```
( "POPUP_REQUEST", $s )
```
Note that the current page is changed to the page popping up while the popup request is processed. - For the meaning of the parameter $s see the explanations in the O'Caml API.
Null event: The null event is represented as
```
( "NO_EVENT" )
```

Note that the first component is always the type of the event and that the second component is always the name of the event (if any). This constraint will even hold if the list of possible events will be extended in the future.

Handling events

The handle method of the current dialog object is called when the event has been triggered. The method event can be used to find out the last event, e.g.

  sub handle {
      my ($self) = shift;
      my @e = $self->event;

      my $e_name = $e[1];    # the second component is the name

      if ($e_name eq 'this_button') {
          ...
      } elsif ($e_name eq 'that_button') {
          ...
      } elsif ($e_name eq 'clicked_icon') {
          my $x = $e[2];
          my $y = $e[3];
          ...
      } else {
          # It is recommended to do nothing as default case
      };

      return undef;       # Important!
  }

The value returned by the handle method determines the action performed after the event has been processed. An undefined value means to display the same page again. Note that you must include a return undef statement as last statement of the method; otherwise the value that happens to be at the top of the value stack is returned. Alternatively, another page can be set by returning the name of the page as string (return 'other_page'). Last but not least it is also possible to change completely to a different dialog instance by returning the reference to the dialog. Example:

  sub handle {
      my ($self) = shift;
      my @e = $self->event;

      my $e_name = $e[1];    # the second component is the name

      if ($e_name eq 'this_button') {
          $self->set_string_variable("xy", "wow");
          return undef;
      } elsif ($e_name eq 'that_button') {
          $self->set_string_variable("xy", "boo");
          return "another_page";
      } elsif ($e_name eq 'clicked_icon') {
          my $next_dlg = UI::Universe::create("other_dialog");
          return $next_dlg;
      } else {
          # It is recommended to do nothing as default case
      };

      return undef;       # Important!
  }