Reference List Menu Library -turn page- Reference List Dialog Library

Contents | Start

The Dialog Library

3. The Dialog Library
3.1
3.2
3.3
3.4
3.5
3.6
3.7
Structure of a Dialog Box
Definition of a Dialog Box
Calling a Dialog Box
Evaluation of a Dialog Box
Menus and Modal Dialog Boxes
Non-Modal Dialog Boxes
Control Library Link
Reference List Dialog Library



This section of the EasyGem Library now deals with the dialog boxes, these little windows that appear on the screen whenever the user is supposed to select or type in something or when the progress of a function (e.g., printing a document) is being reported. The user can comfortably choose between various alternatives using a variety of buttons or input small sections of text.


3.1 Structure of a Dialog Box

Let's start with some practical exercises. We just want to display a small dialog box on the screen. First, we need to initialize EasyGem (using
Easy_Init). Then the main program follows.
In order to be able to work with dialog boxes, we have to define the appearance of the box first. This is done as simply and easily using EasyGem as it is to work with and define menus. Just use the appropriate command to define your dialog box in the program.
Starting with EasyGem version 4.0, you can use two different options for building a dialog box.

1. The commands and functions of the Dialog Library suffice for simple dialog boxes using only standard objects and without any special layout requirements. The dialog box is divided into lines, in which texts and objects of one kind of or another can be defined.

2. The Control Library offers the additional option of defining free controls in dialog boxes. In addition to the standard types, a wide range of additional objects are at your disposal (e.g., icons, sliders, tick marks, time and date displays, etc.), which can also be placed anywhere desired. The Control Library may also be used to define and manage almost all objects available with the Mac. However, programming is a bit more difficult than when using the first method.

This chapter will discuss only the first method, since this is an easier method for beginners. Large sections of the layout and the management are already carried out by EasyGem and do not have to be programmed separately.

The following elements can be placed within the individual lines of a dialog box:

Titles: These will be displayed centered in their own box.

Texts: Well, just some normal text.

Buttons: The mouse can be used to click on buttons. They will then appear inverted. If the user now releases the mouse button while the mouse is still over the object, mostly some function will be executed.

Radio Buttons: You might still be familiar with the buttons that were used to select the frequency bands on older radios (ultra-short-wave, medium-wave, short-wave, etc.). When one was pushed, all others jumped up. Only one button at a time was depressed. Today's software radio buttons were named after these old radio buttons. Only one button is selected at any one time. If a user clicks on another button, only this other button will be selected. One can recognize radio buttons by their little circles located in front of the text, which, in case of a selection, will be filled.

Checkboxes: These are small little squares next to a text. If the mouse is used to click on the square, a little check mark or cross will appear inside of the box. This means that this particular item is then activated or selected. If an already selected checkbox is clicked on again, the check mark will disappear.

Exit Buttons: They correspond to normal buttons but when clicked on, exit the dialog box. Consequently, each dialog box has to contain at least one, otherwise one could not exit the box.
Of course, this does not apply to non-modal dialog boxes with a close box in the header, but we will discuss this in further detail later on.

Input: Here, the user can input text.

Output: Texts that are only known after the dialog box has been defined can be displayed here.

Pop-up Menus:These menus look like normal buttons; however, two small triangles are located at the right side, which show that this button is actually a pop-up menu. If users click on such a button, a menu is displayed at the button location featuring one or several items for selection.

These are the elements you can use to create or define your dialog box.
3.2 Dialog Box Definition

Any definition always starts with the command
Def_Dialog and always ends with End_Dialog. The actual definition, determining the appearance of the box, is located between these two commands:


Def_Dialog R Dialog_Id[,X,Y,W,H],Title$,Type
Make_Dialog Type
 
Make_Dialog Box$,Dialog_Id[,Name$]
Starts definition.

Make_Dialog was implemented to remain compatible with older EasyGem versions. It is best, therefore, to always use Def_Dialog.

You will receive an identification number in Dialog_Id, same as with Def_Menu, which you have to indicate anytime the dialog box is accessed.

Another option is to use
X,Y,W,H to determine the position and size of the dialog box at the same time. However, we do not want to utilize this option at this this time. EasyGem then calculates the size automatically using the contained objects and depicts the dialog box centered on the screen.

Title$ is displayed in the header for movable dialog boxes. The header string is displayed at the uppermost section of the dialog box for non-moveable dialog boxes.

Finally, use
Type to specify the dialog type to be utilized. The following options exist:

Type=0 generates a modal, non-movable dialog box.
Type=1 generates a dialog box as well but one featuring a title bar. You can also switch to other programs while this dialog box is open as well as moving the dialog box on the screen. However, you cannot continue working with your program until the dialog box has been closed.
Type=2
generates a non-modal, movable dialog box. Such a dialog box can remain open at all times and does not have to be closed first in order to continue working with other parts of your program.

The actual definition explained further below follows after Def_Dialog.
The following constitutes the conclusion:


End_Dialog [Box$,]R Dialog_Id    
Concludes definition.

Box$ has no significance, just serves the compatibility with older EasyGem versions, and can always be omitted. Dialog_Id can be omitted as well, because the dialog number has already been returned with Def_Dialog. It is best, therefore, to always use End_Dialog without parameters.

A typical dialog box definition thus looks as follows:

Def_Dialog Dialog1,"Modale Dialogbox",1
 'The definition of the dialog box is listed here.
End_Dialog

Clear_Dialog [Box$,] Dialog_Id  
Delete dialog box.

This command deletes the dialog box with the identification number indicated in Dialog_Id. Again, the term Box$ is possible only for reasons of compatibility and has no significance. You actually need this command only when no other identification numbers are available any more.

Now we are reaching the actual definition phase. Let's start with the titles:

D_Title [Line_No,]Txt$
Define a title bar in the dialog box.

A title will be displayed centered in a small box by itself.
Line_No indicates the line within the dialog box in which the title is supposed to appear (1=at very top, 2=one text line lower, etc.). Txt$ is the text that is supposed to be displayed as the title.
Txt$ will be written in the title bar of the dialog box if Line_No=0 or if this parameter is omitted. Of course, this functions only if the dialog box is equipped with a title bar (moving bar), which means you have to indicate Type=1 or Type=2 in Def_Dialog.
Example:
Def_Dialog Dialog1,"",0
 D_Title 2,"Title"
End_Dialog

This definition fixes the appearance of the dialog box. However, the dialog box does not appear on the screen yet! You can see that the line number for D_Title in our example is set to 2 . This means that the dialog box, which always starts with line 1, has one empty line above the title.
D_Text Line_No,Txt$        
Define a text line in the dialog box.

This call will generate a text line in your dialog box. Line_No is once again that line within the dialog box, in which the text is supposed to appear. Txt$ represents the text itself.


D_Button Line_No,Txt$
Define normal button.
D_Radiobutton Line_No,Txt$  
Define radio button.
D_Checkbox Line_No,Txt$  
Define checkbox.
D_Exitbutton Line_No,Txt$[,Defaultbutton]
Define exit button.

You can define all four different types of buttons using this command. Line_No always indicates the line within the dialog box in which the respective button(s) are supposed to appear.
Txt$ contains information about any other buttons or text, which are also supposed to be present in the line.
Defaultbutton is a parameter that may be used to determine which exit button may also be triggered simply by pressing the Return/Enter key. This button will then be displayed with a thick border. If the dialog box has no closer (Type=0), it has to offer an opportunity to leave it again. Such an exit option can only be provided via the exit buttons. Each dialog box of type 0, therefore, has to have at least one such exit button, otherwise EasyGem will report an error.

The structure of
Txt$ is not quite as simple. An example will best serve to illustrate the use and application of Txt$:

D_Radiobutton 4, "Correct?[Yes][No][Perhaps]"

This line defines three radio buttons in the 4th line of the dialog box with the contents [Yes], [No] and [Perhaps], preceded by the text "Correct?":

Correct?

[Yes]

[No]

[Perhaps]

normal text

1. button

2. button

3. button


This means that a line with buttons may also contain text. Everything located inside of a [square bracket] is a button, everything else is text. Text may also be located in between the square brackets.

If you want to use the parameter
Defaultbutton with D_Exitbutton, which would select one exit button out of many to be selectable by pressing [Return], you have to pass the so-called object number of this button in the procedure D_Exitbutton. The object number may be obtained by simply counting the individual pieces of text and the buttons. Object number 1 in the sample line containing D_Radiobutton is therefore not the button [Yes], but the text "Correct?"! The button [Yes] is object number 2, [No]is object number 3, etc. If there should be blank spaces between the buttons, e.g., in order to increase the distance between the buttons, these do count as text once again and therefore have their own object numbers, which you may not omit when counting!

Example:
We will define a line with the exit buttons
[Delete] and [Cancel], whereby [Cancel] is supposed to be the default button.
D_Exitbutton 7,"Do you wish to: [Delete] or [Cancel] ?",4

The button [Cancel] is here object number 4! The text "Do you wish to: " is object number 1, object 2 is represented by the button [Delete], object 3 is the text " or ", object 4 is the button [Cancel], and object 5 is represented by the text " ?".
D_Empty Line_No  
Define an empty line in dialog box.

This procedure defines an empty text line. Use can use it to group the objects in a dialog box.

Warning: Starting with EasyGem 4.0, the height of a line is no longer constant, but rather depends on the object defined within this line. Each line thus has to be defined and the definitions have to be carried out according to ascending line numbers. If a line is to remain empty, a D_Empty has to be specified for that line.

D_Input Line_No,Txt$,Input_Len[,Flag]
D_Input Line_No,Txt$   
Define an input line.

Line_No indicates once more in which line of the dialog box the input is supposed to start.
Txt$ contains the text to be displayed to the left of the actual input.
Input_Len indicates the maximum length - in characters - of the expression to be inserted.
Flag has no significance any longer and thus may be omitted.
Example:
D_Input 7,"Indicate your printer model: ",6

This line will define an input field in line 7 of the dialog box, which may contain maximally 6 characters.

Starting with version 4.0, EasyGem offers a second input command variation. It has only two parameters, which, however, enables the definition of several input fields per line. For this purpose, a string has to be passed in
Txt$ as you are already familiar with from using D_Button.
Example:
D_Input 7,"Width:[ ] Height:[ ]"
D_Output Line_No,Txt$,Output_Len
Define an output line.

Once again, Line_No indicates the line in which text is supposed to be output.
As in the case of
D_Input,Txt$ is permanently written into the line.
Output_Len indicates the length of the text, which may be displayed in addition. This text may be changed during the execution of the program.

D_Popup Line_No,Txt$,Popup_Id  
Defines a pop-up button.

Line_No indicates once more which line of the dialog box is to be used for the entry.
Txt$ contains the text to be displayed to the left of the pop-up button.
Popup_Id is the identification number of a pop-up menu, which, of course, has to be defined first using the functions of the Menu Library.
Example:
D_Popup 2,"Pop-up Menu:",Popup_Id

EasyGem 4.0 offers some additional procedures and functions, which can be used to influence the appearance of a dialog box.
As depicted by the previous examples, the positions of the individual objects is determined solely by the letters in the definition line. Of course, this information has to be somehow converted into pixels by EasyGem. A fixed pixel width is assumed for each text character and additional space is reserved between the objects and the lines.
This setting can then be queried and changed with the following functions:
D_Setcellwidth Width
Sets the width reserved for each letter.
FN D_Getcellwidth
Queries the set line width.
D_Setspace Width, Height
Sets the space between objects or lines.
D_Getspace R Width, R Height
Queries the spaces.
These procedures and functions are usually not required, because EasyGem positions the objects with the standard settings quite well.
All objects can be selected at first, after a dialog box has been defined. However, sometimes it is desirable to set a few objects as unselectable (disabled) dependent on the respective context, because they otherwise would not serve any practical purpose. There are two procedures for this purpose:
D_Enable Dialog_Id,Line_No,Object_No
Enables object (selectable).
D_Disable Dialog_Id,Line_No,Object_No
Disables object (nonselectable).
These commands function the same way as known to you from the Menu Library. Disabled objects are displayed in gray.


3.3 Calling a Dialog Box

Now we have familiarized ourselves with all commands concerning the definition of a dialog box and can now define any dialog box we desire. But, before we can write an executable program, we need a method to display a dialog box on the screen. The following procedure serves for this purpose:
Easy_Dialog Dialog_Id
Easy_Dialog Box$,Dialog_Id[,R Object_No[,R Line_No]]
Easy_Dialog Dialog_Id,X,Y,R Object_No,R Line_No
Displays the dialog box.

Box$ has no significance and is again only included because of compatibility reasons.
As we know,
Dialog_Id is the identification number, which has been returned to you after End_Dialog.
Object_No is the object number within that line in which the clicked on exit button is located.
Line_No represents the line number in which the clicked on exit button is located. This information is needed only if there are several lines with exit buttons.
X and Y may be used to determine where on the screen the dialog box is supposed to appear. X=0 and Y=0 generate a centered display.
Only after the user has clicked on an exit button or pressed the key [Return], will the command
Easy_Dialog return.

Now, we are able to write our first full functional sample program:
COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"

Easy_Init

'Define Dialogbox.
Def_Dialog Dialog1,"Example",1
 D_Radiobutton 1,"Correct?[Yes][No][Perhaps]"
 D_Empty 2
 D_Exitbutton 3,"                     [ Ok ]",2
End_Dialog

'Display Dialogbox.
Easy_Dialog Dialog1
Easy_Exit
END

A tip for the pros: The procedure Easy_Dialog actually consists out of the following sub-procedures, which may also be called individually, of course:
D_Show [Box$,]Dialog_Id  
D_Show Dialog_Id,X,Y  
Display dialog box.

Displays the dialog box with the identification number Dialog_Id . You can determine where on the screen the dialog box is supposed to be displayed using X and Y. X=0 and Y=0 generate a centered display.

D_Redraw Dialog_Id[,Line_No]
Redraw dialog box.

Redraws the dialog box. Use Line_No to determine that only this one line is redrawn.

D_Edit Dialog_Id[,R Object_No[,R Line_No]]  
Redraw and edit dialog box.
D_Edit_ Dialog_Id[,R Object_No[,R Line_No]]
Edit dialog box.

Both of these procedures allow the user to input information into the dialog box. D_Redraw is first called in the case of the first procedure.


D_Event Dialog_Id,R Object_No[,R Line_No[,R Entry]]
Evaluate an event.

This procedure functions similarly to D_Edit_, the only difference is that it will return immediately, even if an exit button has not been pressed yet. This has the result that you remain in control over the program's flow and execution; however, you also have to make sure that the dialog box disappears again from the screen at the indicated point in time. This is achieved with the following command:
D_Hide Dialog_Id  
Remove dialog box from the screen.

Removes the dialog box from the screen.

In order to control the dialog box from within the program with a higher level of detail, you may use this individual procedures. Were you to call only
Easy_Dialog, the procedure would not return until an exit button has been selected. If, however, one would like to display the current progress of a specific task, e.g., when editing a file, one would initially display the dialog box using only D_Show and then apply D_Redraw to constantly update the box. After the task has been concluded, one could remove the box using D_Hide, or one first calls D_Edit_ to cause the user to click on [OK] or to trigger other activities.
We will supply another example to clarify the procedure. Here, the date and time of day are supposed to be displayed within a dialog box. The time will be updated in intervals of one second.

Example:
COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"

Easy_Init
'Define dialog box.
Def_Dialog Date_Time,"Date and Time",1
 D_Output 1,"Date ",12
 D_Output 2,"Time ",12
 D_Empty 3
 D_Exitbutton 4,"      [Cancel]",2
End_Dialog

'Initialize variables and dialog box.
Tim=TIMER
Dialog_Text$(1,Date_Time)=DATE$
Dialog_Text$(2,Date_Time)=TIME$

'Display dialog box and update in loop.
D_Show Date_Time
REPEAT
 IF TIMER >Tim+200 THEN
  Dialog_Text$(2,Date_Time)=TIME$
  D_Redraw Date_Time,2:'Update only line 2.
  Tim=TIMER
 ENDIF
 'Check if [Cancel] has been pressed.
 D_Event Date_Time,Object_No
 'Additional program code could be listed here.
UNTIL Object_No
D_Hide Date_Time:'Remove dialog box again.
Easy_Exit
END

Note: While the dialog box is visible on the screen, it is of course impossible to continue working in any other windows because we are dealing with a modal dialog box. However, your program is able to perform other activities in the background, e.g., calculations or the creation of a virtual screen, which will be displayed after the dialog box has been exited.



3.4 Evaluation of a Dialog Box

The commands discussed up to this point are suitable for defining and displaying a dialog box on screen. It is, of course, essential to be able to detect which buttons have been clicked on, what text the user has written into the dialog box, etc. You will find out next how to achieve this task .
We have already described with what type of exit button to leave the dialog box when we discussed
Easy_Dialog. In order to make this possible for other buttons and texts as well, two global variable fields are used, which are utilized by EasyGem to store the desired information.

Let's start with the buttons. The following variable field will be used for this task:

Dialog_Button%F(Line_No,Object_No,Dialog_Id)
Determine or set status of button.

You can see that this is a so-called flag field (%F). The field elements can consist of only two conditions: false=(0) or true=(-1). Zero (0) indicates for all buttons a "not selected" status (display on screen: normal), -1 represents "selected" (display on screen: inverted or checked off, respectively, etc.). Line_No indicates the line within the dialog box whose condition or status we want to ascertain, and Object_No is the number of the object within the line (objects are numbered same as described for D_Exitbutton). As you probably noticed, not only does every button have its assigned variable, but every text has one as well. This variable, however, is always zero for any text since a text cannot be selected by clicking on it.

Example:
COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"
COMPILER "OPW 320*200"

Easy_Init
Def_Dialog Dialog1,"Example",1
 D_Radiobutton 1,"Correct?[Yes][No][Perhaps]"
 D_Empty 2
 D_Exitbutton 3,"                     [ OK ]",2
End_Dialog
Dialog_Button%F(1,2,Dialog1)=-1:'Yes is default.
Easy_Dialog Dialog1
M_Show 0:GRAF_PORT 0
IF Dialog_Button%F(1,2,Dialog1) THEN PRINT "Yes has been selected!"
IF Dialog_Button%F(1,3,Dialog1) THEN PRINT "No has been selected!"
IF Dialog_Button%F(1,4,Dialog1) THEN PRINT "Perhaps has been selected!"
REPEAT COMPILER "Event" UNTIL 0
Easy_Exit
END


You can therefore determine if a certain button has actually been clicked on by querying the content of the appropriate variable. This is also applicable in the reverse direction: If you set a button to "select" (unequal zero) before calling Easy_Dialog, this button is then already selected when calling the dialog box. We will provide you with a demo program a few paragraphs below, which illustrates the use of the field Dialog_Button%F for this specific purpose.
In case of a line with radio buttons, of which only one can be selected at any one time, another functions exists, which returns the number of the button directly:

FN Rbutton(Line_No,Dialog_Id)
Determine number of pressed radio button.

Returns the object number of the selected button within a radio button line. Zero (0) is returned if no button is selected.
This functions similarly for texts when using D_Input. Two text fields exist for this purpose. The field with two parameters can be used for input commands with only one input field per line. If you would like to use several input field per line, you have to work with the text field with the additional object number as third parameter:

Dialog_Text$(Line_No[,Object_No],Dialog_Id)
Determine or set text in line Line_No.

This can be used to initialize a text and to query the same text later - as shown in the demo program below.
When using
D_Output, everything appears like that. Nevertheless, it serves no real purpose to query the text again because it cannot be modified by the user anyhow.

Incidentally, if you want to delete all the buttons and texts of any given dialog box, this task can also be performed via a specific command:

Clear_Parameter(Dialog_Id)    
Clear all buttons and texts within a dialog box.

Naturaly Dialog_Id again is the identifikation number of the dialog box.



3.5 Menus and Modal Dialog Boxes

If a modal dialog box is opened, it is recommended first to deactivate all menu items, because users can select only functions within the dialog box in case of a modal dialog box. If your dialog box contains input fields, you should keep the menu functions for cutting, copying, pasting, and deleting active to give users the opportunity to exchange texts in the dialog box using the clipboard.
However, this requires a bit more programming effort. The following example shows the steps:
COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"


Extension_Init
Easy_Init

'Defines Menu.
Def_Menu Menu1,"About this program",Info
 M_Title "File",File1
  M_Entry "Modal Dialog Box",Modal_Dialog1
  M_Line_Entry
  M_Entry "Quit/Q",Quit1
 M_Title "Edit",Edit1
  M_Entry "Cut/X",Cut1
  M_Entry "Copy/C",Copy1
  M_Entry "Paste/V",Paste1
  M_Entry "Clear",Clear1
End_Menu

'Defines Dialog Box.
Def_Dialog Dialog1,"Modal Dialog",1
 D_Input 1,"Input Box 1",10
 D_Input 2,"Input Box 2[        ]Input Box 3[        ]"
 D_Empty 3
 D_Exitbutton 4," [Cancel]                    [ OK ]",4
End_Dialog
Dialog_Text$(1,Dialog1)="Input 1"
Dialog_Text$(2,2,Dialog1)="Input 2"
Dialog_Text$(2,4,Dialog1)="Input 3"

M_Show Menu1
'Main Event Loop.
REPEAT
 Easy_Mesag Entry
 'Check for menu actions and Apple events.
 IF Entry
  THEN
   SELECT Entry
    CASE Modal_Dialog1:Open_Modal_Dialog
    CASE Quit1,CVIL("quit"):Quit_Program
   END_SELECT
 ENDIF
UNTIL 0

DEF PROC Quit_Program
 Easy_Exit
 Extension_Exit
 END
END_PROC
DEF PROC Open_Modal_Dialog
 LOCAL Con,Object_No,Entry,Sel_Start,Sel_End,Scrap$,T$
 M_Disable Menu1,File1:M_Draw:'Deactivates File Menu.
 D_Show Dialog1:'Displays Dialog Box.
 REPEAT
  D_Event Dialog1,Object_No,0,Entry
  IF Entry THEN
   'A menu item has been clicked.
   Con=FN Con_Getkeyfocus(Dialog1)
   IF Con THEN
    'The dialog box has an active text input field.
    SELECT Entry
     CASE Cut1
      Con_Getselect Con,Sel_Start,Sel_End:T$=FN Con_Gettext$(Con)
      T$=FN Con_Gettext$(Con)
      Put_Scrap CVIL("TEXT"),MID$(T$,Sel_Start+1,Sel_End-Sel_Start)
      Con_Settext Con,LEFT$(T$,Sel_Start)+MID$(T$,Sel_End+1)
      Con_Setselect Con,Sel_Start,Sel_Start
     CASE Copy1
      Con_Getselect Con,Sel_Start,Sel_End
      T$=MID$(FN Con_Gettext$(Con),Sel_Start+1,Sel_End-Sel_Start)
      Put_Scrap CVIL("TEXT"),T$
     CASE Paste1
      Con_Getselect Con,Sel_Start,Sel_End
      T$=FN Con_Gettext$(Con)
      Scrap$=FN Get_Scrap$(CVIL("TEXT"))
      Con_Settext Con,LEFT$(T$,Sel_Start)+Scrap$+MID$(T$,Sel_End+1)
      Sel_Start+=LEN(Scrap$)
      Con_Setselect Con,Sel_Start,Sel_Start
     CASE Clear1
      Con_Getselect Con,Sel_Start,Sel_End
      T$=FN Con_Gettext$(Con)
      Con_Settext Con,LEFT$(T$,Sel_Start)+MID$(T$,Sel_End+1)
      Con_Setselect Con,Sel_Start,Sel_Start
    END_SELECT
   ENDIF
  ENDIF
 UNTIL Object_No:'Until an exit button has been clicked.
 D_Hide Dialog1
 M_Enable Menu1,File1:M_Draw:'Reactivate File Menu.
END_PROC

To try out this program, you have to load the EasyGem Library as well as the Extension Library.
Commands from the Control Library, which cannot be explained in detail here, are used for the realization of the functions for cutting, copying, pasting, and deleting of texts. A detailed description can be found in the "Control Library" chapter. 

Note: In case of editable text fields, the keyboard combinations [Cmd]+[X], [Cmd]+[C]and [Cmd]+[V] -- used to cut, copy, and paste -- function even if no edit menu is available.


3.6 Non-Modal Dialog Boxes

Starting with EasyGem 4.0, it is possible to also use non-modal dialog boxes (
Type=2 with Def_Dialog). A non-modal dialog box does not block the execution of your program; this means it may remain open permanently while you are working on other items. This, however, presents a new problem:
A modal dialog box is closed by the user after all changes have been made. After returning from
Easy_Dialog your program can then evaluate the dialog box fields and react accordingly.
Since a non-modal dialog box usually remains open, a different mechanism has to be conceived to react to user actions.
EasyGem offers the option of assigning a so-called action function to each object. This action function is always called when the user has selected the object. For example, for a normal button this is the exact moment when the mouse button is released.

D_Setaction Dialog_Id,Line_No,Object_No,Act_Fun
Setting an action function for the object specified by Dialog_Id,Line_No and Object_No.
The action function has to be defined by yourself. It has to be a long integer type and take three parameters.

DEF FN My_Action(Dialog_Id,Line_No,Object_No)

The parameters of your action function are used to pass the dialog identification number, line number, and object number so that you can unequivocally identify the object clicked on by the user.
In
Act_Fun you then pass the address if this function:

Act_Fun=&FN My_Action(,,)

The following example illustrates the individual steps:
COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"
COMPILER "OPW 320*200"

Easy_Init

'Defines Menu.
Def_Menu Menu1,"About this program",Info
 M_Title "File",File1
  M_Entry "Open Dialog Box 1",Open_Dialog1
  M_Entry "Open Dialog Box 2",Open_Dialog2
  M_Line_Entry
  M_Entry "Quit/Q",Quit1
End_Menu


'Define first dialog box.
Def_Dialog Dialog1,"Planets",2
 D_Radiobutton 1,"[Mercury][Venus][Earth][Mars]"
 D_Checkbox 2,"[Mass][Radius][Atmosphere ]"
 D_Empty 3
 D_Button 4,"                         [Execute]"
End_Dialog

'Define second dialog box.
Def_Dialog Dialog2,"Stars",2
 D_Radiobutton 1,"[Sun][Sirius][Rigel]"
 D_Checkbox 2,"[Distance][Brightness][Temperature]"
 D_Empty 3
 D_Button 4,"                            [Execute]"
End_Dialog

'Initialize dialog buttons.
Dialog_Button%F(1,3,Dialog1)=-1
Dialog_Button%F(1,1,Dialog2)=-1
'Assign action functions.
D_Setaction Dialog1,4,2,&FN Display_Status(,,)

D_Setaction Dialog2,4,2,&FN Display_Status(,,)

M_Show Menu1
'Main Event Loop.
REPEAT
 Easy_Mesag Entry,Buffer$
 'Check for menu actions and Apple events.
 IF Entry
  THEN
   SELECT Entry
    CASE Open_Dialog1:D_Show Dialog1
    CASE Open_Dialog2:D_Show Dialog2
    CASE Quit1,CVIL("quit"):Quit_Program
   END_SELECT
  ELSE Win_Domessages Buffer$
 ENDIF

UNTIL 0

DEF PROC Quit_Program
 Easy_Exit
 END
END_PROC

'Define action function.
DEF FN Display_Status(Id,Lin,Obj)
 GRAF_PORT 0:CLS
 'Output status of dialog boxes.
 SELECT Id
  CASE Dialog1
   SELECT FN Rbutton(1,Id)
    CASE 1:PRINT "Mercury"
    CASE 2:PRINT "Venus"
    CASE 3:PRINT "Earth"
    CASE 4:PRINT "Mars"
   END_SELECT
   IF Dialog_Button%F(2,1,Id) THEN PRINT "Mass"
   IF Dialog_Button%F(2,2,Id) THEN PRINT "Radius"
   IF Dialog_Button%F(2,3,Id) THEN PRINT "Atmosphere"
  CASE Dialog2
   SELECT FN Rbutton(1,Id)
    CASE 1:PRINT "Sun"
    CASE 2:PRINT "Sirius"
    CASE 3:PRINT "Rigel"
   END_SELECT
   IF Dialog_Button%F(2,1,Id) THEN PRINT "Distance"
   IF Dialog_Button%F(2,2,Id) THEN PRINT "Brightness"
   IF Dialog_Button%F(2,3,Id) THEN PRINT "Temperature"
 END_SELECT
END_FN

This example gives you the opportunity to try out for yourself how a non-modal dialog box works. After opening a dialog box, you can use the menu to open the second one as well. You can switch between the dialog boxes by simply clicking into the other box with the mouse.
As soon as you click on one of the "Execute" buttons, your action function
Display_Status is called and the status of the radio buttons and checkboxes is displayed in the window.

Note: You need an extended form of Easy_Mesag and the procedure Win_Domessages to manage non-modal dialog boxes. Both are explained in the chapter discussing window programming.

3.7 Control Library Link

The objects that can be defined with the Dialog Library are so-called controls. The Dialog Library thus programs the Control Library by combining the different functions, by enabling an easy identification of the objects through division into lines, and thus taking over a large part of the management. The disadvantage of this method is that the number possibilities to access the separate objects individually has been reduced. The following function offers the opportunity to at least even out this disadvantage:

FN D_Controlid(Dialog_Id,Line_No,Object_No)
Returns the control identification number for the object specified by Dialog_Id,Line_No and Object_No.
You can thus use this to ascertain the control identification number for each individual object in your dialog box. This number can then be used to apply the functions of the Control Library to the corresponding object and to position this object pixel-wise, e.g., using Con_Setborder or changing text color, style, size, etc. using Con_Fontstyle.

And finally, one more sample program featuring an overview over the objects introduced up to now:
COMPILER "MIN_SIZE 1000000"
COMPILER "BAS_MEM 1000000"
COMPILER "Warnings off"

Easy_Init

'Defines Menu.
Def_Menu Menu1,"About this program",Info
 M_Title "File",File1
  M_Entry "Modal Dialog Box",Modal_Dialog1
  M_Line_Entry
  M_Entry "Quit/Q",Quit1
End_Menu

'Define pop-up menu.
Def_Popup Particles
 M_Entry "Photon",Photon
 M_Entry "Neutrino",Neutrino
 M_Entry "Electron",Electron
 M_Entry "Proton",Proton
 M_Entry "Neutron",Neutron
End_Popup

'Define dialog box.
Def_Dialog Mm_Dialog,"Moveable Modal Dialog Box",1
 D_Text 1,"This is an example for illustration purposes."
 D_Empty 2
 D_Checkbox 3,"Checkboxes [Checkbox 1][Checkbox 2][Checkbox 3]"
 D_Radiobutton 4,"Radio Buttons[Button 1 ][Button 2 ][Button 3 ]"
 D_Input 5,"Input Box 1",10
 D_Input 6,"Input Box 2[        ] Input Box 3[        ]"
 D_Popup 7,"Particles",Particles
 D_Empty 8
 D_Exitbutton 9," [Cancel]                              [ OK ] ",4
End_Dialog
Con=FN D_Controlid(Mm_Dialog,1,1):Con_Setborder Con,0,390,20
Con_Setfontstyle Con,0,13,%101,0,0,7,1
Dialog_Button%F(3,2,Mm_Dialog)=-1
Dialog_Button%F(3,4,Mm_Dialog)=-1
Dialog_Button%F(4,3,Mm_Dialog)=-1
Dialog_Text$(5,Mm_Dialog)="Input 1"
Dialog_Text$(6,2,Mm_Dialog)="Input 2"
Dialog_Text$(6,4,Mm_Dialog)="Input 3"
Dialog_Button%F(7,3,Mm_Dialog)=-1

M_Show Menu1
'Main event loop.
REPEAT
 Easy_Mesag Entry
 'Check for menu actions and Apple events.
 IF Entry
  THEN
   SELECT Entry
    CASE Modal_Dialog1:Open_Modal_Dialog
    CASE Quit1,CVIL("quit"):Quit_Program
   END_SELECT
 ENDIF
UNTIL 0

DEF PROC Quit_Program
 Extension_Exit
 END
END_PROC
DEF PROC Open_Modal_Dialog
 LOCAL Object_No
 M_Disable Menu1,File1:M_Draw:'Deactivate file menu.
 Easy_Dialog Mm_Dialog,MOUSEX,MOUSEY,Obj_No,0:'Load dialog box at
 'current mouse position.
 If Obj_No=4
  THEN 'OK was clicked.
  ELSE 'Cancel has been clicked.
 ENDIF
 M_Enable Menu1,File1:M_Draw:'Reactivate file menu.
END_PROC


Reference List Menu Library -turn page- Reference List Dialog Library

Contents | Start



© 1998-2000 Berkhan-Software
www.berkhan.com | Home