Advanced Dialog Manager usage

3 Eloquence Graphical User Interface

Advanced Dialog Manager usage

Overview

In some cases it is necessary to use some not standard functions, to implement certain tasks. The following specials perhaps can help you to manage it.

Accessing Dialog Manager Variables

Dialog Manager variables may be set using the DLG SET and retrieved using the DLG GET statement. The dialog name, the variable name and the .value attribute must be specified.

Example:

   dialog YourDialog
   ...
   variable string StrVal;
   variable integer IntVal;

You may access these variables from Eloquence using the following statements:

   DLG GET "YourDialog.StrVal!value",A$

This will retrieve the value of the Dialog Manager variable StrVal into the Eloquence variable A$.

   DLG SET "YourDialog.IntVal!value",123

This will set the Dialog Manager variable IntVal to the constant value 123.

NOTE: You should use the exclamation mark ('!') to delimit variable path and attribute because
native Dialog Manager attributes are accessed. Please refer to Accessing Dialog Manager Objects later in this chapter.

NOTE: Please refer to the ISA Dialog Manager documentation for details.

Dialog Manager Records

Eloquence supports access to Dialog Manager record objects.

Dialog manager record objects are the equivalent of structures in C language and may be defined globally to the dialog or locally to any object.

This is an efficient method to exchange multiple data with Dialog Manager at once. Using the Eloquence XPACK and XUNPACK statements, you may link Eloquence variables to Dialog Manager record members.

Dialog Manager record members may either be defined as shadow objects, such that each access to a record member will affect the associated object attribute, or they may contain data which may be used in Dialog Manager rules or functions.

The DLG SET and DLG GET statement mappings of the dialog driver have been enhanced to support Dialog Manager record objects.

The DLG SET Statement

The DLG SET statement may be used to transfer a buffer, packed by the XPACK statement, into equivalent record members of a Dialog Manager record object.

   DLG SET "Record.@",Buf$

NOTE: The .@ attribute must be specified.

Example:

   window CusWin
   {
      ...
      child record CusRec
      {
         string Cus_no shadows CusWin.Cus_number.content;
         string Cus_name shadows CusWin.Cus_name.content;
         boolean Cus_flag shadows CusWin.active;
         ...
      }
   }

   Cus_no$="1234"
   Cus_name$="Customer Name"
   Cus_flag=1
   XPACK Buf$ FROM Cus_no$,Cus_name$,Cus_flag
   DLG SET "CusWin.CusRec.@",Buf$

This will transfer the Eloquence variables Cus_no$, Cus_name$ and Cus_flag into the Dialog Manager record object CusWin.CusRec.

The DLG GET Statement

The DLG GET statement may be used to transfer the contents of a Dialog Manager record object into Eloquence program variables.

If a .@ attribute is specified, all record members are transferred. If a member name is specified, only the given record member is transferred:

   DLG GET "Record.@",Buf$

This transfers all members of Record into Buf$.

   DLG GET "Record.Array",Buf$

This transfers all elements of Record member Array into Buf$.

   DLG GET "Record.Array[1]",Buf$

This transfers the first element of Record member Array into Buf$.

Example:

   DLG GET "CusWin.CusRec.@",Buf$
   XUNPACK Buf$

This will transfer all members of the Dialog Manager record object CusWin.CusRec into equivalent Eloquence program variables.

   DLG GET "CusWin.CusRec.Cus_flag",Buf$
   XUNPACK Buf$

This will transfer the field CusWin.CusRec.Cus_flag into the Eloquence program variable Cus_flag.

Programming Considerations

In order to use Dialog Manager record objects, the following considerations should be followed:

The Dialog Manager does not support floating point variables.
All record member names must be valid Eloquence variable names.
The Dialog Manager record members must have the appropriate type. You may use the Dialog Manager boolean, integer and string data types.
The Dialog Manager record members and Eloquence program variables should have an equivalent type.
While it is possible to transfer Eloquence numeric variables into Dialog Manager string record members, the opposite is not possible.

However, there is a workaround implemented into Eloquence which allows to overcome this limitation:

A Dialog Manager record member with a trailing 'N' (uppercase) appended to its name is considered numeric, regardless of its real data type. The corresponding Eloquence variable name does not include the trailing 'N'. This way, numeric data can be transferred from any Dialog Manager record member data type into Eloquence numeric variables.

Example:

window MyWin
{
child record MyRec
{
string Num_strN "123";
}
}

INTEGER Num_str
DLG GET "MyWin.MyRec.@",Buf$
XUNPACK Buf$

This will transfer the numeric value 123 from the Dialog Manager record member MyWin.MyRec.Num_strN (string data type) into the Eloquence variable Num_str (INTEGER data type).

NOTE: If such Dialog Manager record members contain non-numeric text, 0 (zero) is transferred into the corresponding Eloquence variables.

Dialog Manager Rules and Functions

Eloquence provides two statements which enable you to call Dialog Manager rules and functions.

Rules

Dialog Manager rules are implemented using the Dialog Manager script language and are stored in the dialog file. This makes it possible to provide a task-oriented interface to dialogs without having to care about the bits and pieces.

By writing your own rules you actually extend the dialog server functionality. The DLG CALL RULE statement allows you to trigger such extensions:

DLG CALL RULE "Rule","Object" [(arg,arg ...)] [,Retvar[$]] [;Err]

Example:

   window MyWindow
   {
      ...
      child image MyImage
      {
         ...
         .text "Image Name";
         .picture Default;
      }
      ...
   }
   ...
   rule void LoadGif( string Gif input, string Name input )
   {
      this.picture := Gif;
      this.text := Name;
   }


   DLG CALL RULE "LoadGif","MyImage"("sample.gif","Sample Image")

This will trigger the LoadGif() rule. The object which the rule is applied to (this) is MyImage, the GIF image to be loaded is sample.gif and the image title is set to "Sample Image".

The DLG CALL RULE statement is mapped to a DM_CallRule() Dialog Manager function call.

If a return variable is present, the value returned by the rule will be assigned to it. If no return variable is specified, the return value will be ignored.

If the error return variable is present, no runtime error is returned, but the error variable is set with the error number.

NOTE: In the example above, the GIF file will be read from the local system (where the dialog server is executed). If you are using the network dialog server on the PC platform, this file is expected on the PC. This behavior is subject to change in a subsequent release.

Functions

Dialog Manager functions are implemented in C language and are linked to the dialog server executable. The functions are bound to the Dialog Manager using the DM_BindFunctions() Dialog Manager function. In order to use such functions they must be declared in the dialog file.

By writing your own functions you actually extend the dialog server functionality. The DLG CALL FUNCTION statement allows you to trigger such extensions:

DLG CALL FUNCTION "Function" [(arg,arg ...)] [,Retvar[$]] [;Err]

Example:

   function boolean EqHelpViewFile(string input);

   DLG CALL FUNCTION "HelpViewFile"("sample.txt")

This will trigger the HelpViewFile() function. The file to be viewed is sample.txt.

The DLG CALL FUNCTION statement is mapped to a DM_CallFunction() Dialog Manager function call. The maximum number of arguments is 8.

If a return variable is present, the value returned by the rule will be assigned to it. If no return variable is specified, the return value will be ignored.

If the error return variable is present, no runtime error is returned, but the error variable is set with the error number. If no dialog server is active, an error 1004 is returned.

NOTE: Please refer to section Customizing the Dialog Server prior in this chapter for details about extending the dialog server.

Programming Notes

This section covers solutions to common problems concerning Dialog Manager programming issues.

Avoiding Edit Text Exit Rule

Problem: on EDITTEXT deselect is triggered at PUSHBUTTON select.

If a pushbutton or image button is selected, this will involve a focus change which will trigger an EDITTEXT deselect rule. As a result, it is required to select the pushbutton twice.

This behavior can also result in a situation where a "Cancel" pushbutton would be unusable if an EDITTEXT deselect rule performs a field validation and re-sets the focus on itself again.

This problem can be solved in the following manner:

Initialize an integer variable in your pushbutton object or in the object model or default. Do this in every object (model, default) that should have "Cancel" pushbutton characteristics, e.g.:

model pushbutton Cancel_btn
{
...
integer EqRuleOverride := 1;
}

Change the object (model, default) rule that normally is triggered on EDITTEXT deselect.

If this rule is e.g.:

on EDITTEXT deselect
{
if this.EqRule then
EqExitEventLoop(this, this.EqRule);
endif
}

Change this rule to:

on EDITTEXT deselect
{
variable integer RuleOverride := 0;
if (typeof(this.window.focus.EqRuleOverride)=integer) then
RuleOverride := this.window.focus.EqRuleOverride;
endif
if RuleOverride=0 then
if this.EqRule then
EqExitEventLoop(this, this.EqRule);
endif
endif
}

The basic idea is to obtain the newly focused object (this.window.focus which might be the "Cancel" pushbutton object) and check if this object has an EqRuleOverride attribute. If this is true and EqRuleOverride is set the EqExitEventLoop() function will not be triggered and the EDITTEXT deselect rule will not perform any action.

Setting the Focus to Microsoft Windows Radio Button Object

Previously, a DLG SET "Radiobutton.focus",1 statement always activated the chosen radiobutton when applied with the Microsoft Windows network dialog server. This behavior sometimes had side effects if a rule was associated with the activation of this radiobutton and the radiobutton had not previously been selected.

The current implementation sets the focus to the currently selected radiobutton within the same group whenever a DLG SET statement is used as shown above. Since the focused radiobutton has been selected previously, any activation rule will not be triggered.

To achieve the former behavior, you can access the native Dialog Manager attribute, e.g. DLG SET "Radiobutton!focus",1

Eloquence Dialog Manual - 19 DEC 2002