You should follow accepted style guides like CUA89 (MS Windows and OSF Motif) or CUA92 (OS/2) instead of inventing your own. Don't invent your own rules if you can avoid it!
If you try to emulate your FORMs and softkey environment with Dialog Manager, your program will probably be slow and difficult to handle.
Dialogs are different than FORMs. Within a dialog environment, the program must be aware, that the user may jump on the dialog simply by using the mouse or keyboard accelerators. So it should be up to the user to operate their way, instead of requiring a fixed sequence of entries.
Functions keys should only be used to accelerate access to selected functions.
Usage of function keys f1 .. f4 should be avoided, because they have a fixed meaning:
While access to Eloquence dialog resources are fast, this may be different, when a dialog server is used. For example each request to a dialog server running on top of MS Windows requires transmission of request and results on the network which may cause a substantial delay.
So it's highly recommended to keep those transactions at a bare minimum. Use local capabilities of the dialog server when possible.
This is especially important in the context of the client/server model as imposed by the Eloquence dialog server implementation. Each system should process locally as much information as possible to avoid time consuming client/server transactions.
For example it makes sence to validate user input by the dialog server
(by a format function) instead of returning to Eloquence for
each editable object.
As a (positive) side effect, this should also help you to reduce the
extend of your Eloquence code to the essential parts.
Please refer to Eloquence A.05.00 release notes and ISA Dialog Manager documentation for further reference.
A mechanism has been implemented to access arbitrary Dialog Manager
objects and attributes from Eloquence.
Whenever an exclamation mark ('!') is used to delimit object path
and attribute, or if Eloquence does not know how to map the
particular object type, all arguments are passed to Dialog Manager.
This makes it possible to access all Dialog Manager objects without beeing limited by Eloquence. However, only attribute types, which are either convertable to a string or an integer may be used.
Consider the following dialog resource file:
window YourWindow
{
...
child edittext Numeric
{
...
The DLG SET statement below will set the field format of edittext
object Numeric.
DLG SET "YourWindow.Numeric!format","%8'3,02sf/1"If Dialog Manager object names have unique object names, it's sufficient to specify only the object name instead of the full object path. Under this condition, the statement below is equivalent to example above:
DLG SET "Numeric!format","%8'3,02sf/1"Dialog Manager objects may be anonymous. You don't have to assign an object name, unless you intend to access the object.
Please refer to Eloquence A.05.01 release notes and ISA Dialog Manager documentation for further reference.
For example:
dialog YourDialog
...
model statictext YellowText
{
.fgc ColBlack;
.bgc ColYellow;
.width 10;
.text "YellowText";
}
...
child YellowText Yt1
{
.xleft 30;
.width 15;
.ytop 0;
}
This defines the model "YellowText". It is derived from the
statictext object default, but defines it's own attribute default
values. Models may also define new attributes for Dialog Manager objects and may have default rules associated with them.
Example below will define the Model "MyMenuItem" which has been derived from the default menuitem object. MyMenuItem defines an attribute EqRule and a rule causing return from DLG DO statement to Eloquence when an instance of the MyMenuItem is selected and it has a nonzero EqRule value:
model menuitem MyMenuItem
{
.text "MyMenuItem";
integer EqRule := 0;
}
...
child menubox
{
.title "&File";
child MyMenuItem About
{
.text "&About";
.EqRule := 1;
}
child MyMenuItem Exit
{
.text "&Exit";
.EqRule := 2;
}
...
on MyMenuItem select
{
if this.EqRule then
EqExitEventLoop(this, this.EqRule);
endif
}
Please refer to ISA Dialog Manager documentation for further reference.
For 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 Eloquence variable A$.
DLG SET "YourDialog.IntVal!value",123This will set the Dialog Manager variable IntVal to 123.
Please note, that you have to use the exclamation mark ('!') to
delimit variable path and attribute, because native Dialog Manager
objects are accessed.
Please refer to ISA Dialog Manager documentation for further reference.
Dialog manager record objects are the equivalent of C structs and may be defined global to the dialog or local 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 by Dialog Manager rules or functions.
For example:
window YourWindow
{
...
child record Rec
{
integer Ival shadows Sb.curvalue;
boolean Bval shadows ChkBox.active;
string Name shadows Name.content;
string Array[5];
}
In the example resource definition above, the variables Ival, Bval,
Name and Array are defined as members of the record Rec.
Array is a string array with 5 elements.
All other variables are associated with object attributes.
You may access this record from within Eloquence using the
statements below:
DLG GET "YourWindow.Rec.@", Buf$ XUNPACK Buf$This will retrieve the value of all member variables of the specified record into the corresponding Eloquence variables.
XPACK Buf$ FROM Ival,Bval,Name$ DLG SET "YourWindow.rec.@", Buf$This will set the corresponding member variables of record Rec from Eloquence variables. Please refer to Eloquence A.05.01 release notes and ISA Dialog Manager documentation for further reference.
Rules are implemented using the Dialog Manager script language and are stored in the dialog resource file. This makes it possible to provide a task oriented interface to dialog without having to care about the bits and pieces.
Functions in this context are C functions linked to dialog server.
The funtion must be bound to the dialog server
(using DM_BindCallBacks()) and declared in the dialog file.
This makes it possible, to call your own dialog server extensions.
Calling a Dialog Manager rule
For example:
window YourWindow
{
...
child image Image
{
...
.text "Image Name";
.picture Default;
}
...
rule void LoadGif (string Gif input, string Name input)
{
this.picture := Gif;
this.text := Name;
}
The DLG CALL RULE statement below will call the rule LoadGif as
defined above with the "this" object "Image".
DLG CALL RULE "LoadGif","Image"("Sample.gif","Sample GIF Image")
(Please note: Loading a gif image dynamically may not be possible in
current Dialog Manager release on MS Windows.)
The dialog server on Motif does call the /usr/vue/bin/helpview program passing the specified help volume and topic:
DLG SET ".driver","motif"
DLG CALL FUNCTION "EqCallHelp"("Help4Help","_HOMETOPIC")
The dialog server on MS Windows does call the WINHELP utility with
the specified help file and keyword.
DLG SET ".driver","@pc"
DLG CALL FUNCTION "EqCallHelp"("notepad.hlp","Index")
Both examples show how to use dialog server functionality from
Eloquence to provide a task oriented interface to the dialog instead
having to deal with all the details from you Eloquence program.
Please refer to Eloquence A.05.01 release notes and ISA Dialog Manager documentation for further reference.
As implemented now, the following prerequisites must be met: