GAMBAS-BOOK 3.19.5

In the first example, a dialogue is developed that is called up before the main program and is used to enter two pieces of data - a freely selectable name and a password. When planning your own dialogue, questions to be answered include the following, although the order does not imply any ranking:

• (F1) In which mode will the dialogue be called?
• (F2) Is the dialogue displayed as a preview window of the (main) program or at runtime of the (main) program?
• (F3) Should a title (window line) be displayed in the dialogue?
• (F4) Do data have to be passed to the dialogue for modification? With which data type will this data be passed to the dialogue (type, array, collection)?
• (F5) Will data be read from the dialogue? Is it multiple data? What is the data type of this data?
• (F6) What should the graphical user interface for the dialogue window look like (controls, arrangement)?

In relation to the 1st project, here are the answers:

• (A1) The dialogue is called modally → _call(..) method.
• (A2) Preview window of the (main) program.
• (A3) Yes → dialogue title text: 'Enter the data!'
• (A4) No.
• (A5) Yes - exactly two. Both data are of the same type 'String' and are stored as a key-value pair in the dialogue in a collection. The return value of the method used to call the dialogue therefore has the same data type.
• (A6) The following → Figure 12.4.4.1.1 shows two labels, two text boxes and two buttons:

Figure 12.4.4.1.1: Dialogue box (IDE)

With these preliminaries, the development of a custom dialogue can be tackled.

In essence, one defines a dialogue box → Figure 12.4.4.1.1 and calls it using the special _call(..)-method in the main program. For information on this method, see the Gambas documentation → http://gambaswiki.org/wiki/lang/special/call. In the optional arguments of the _call(…) method you can pass data to the dialogue and read data from the dialogue in the return value of the method (function value). By calling the _call(..) method, the dialogue box can display itself modally! Now you can edit the data in the dialogue. If the dialogue box is closed, the ShowModal() call - this happened automatically - returns to the _call() call and you can read data from the dialogue.

This all takes place in the Open event of the main form in the first example - before this form is displayed! The _call() method allows you to use an object syntactically like a function. Use the _call(..) method whenever a form (or a class in general) has a very specific task that it can do itself, without needing event handlers in other classes, for example.

The following two source texts for example 1 show the implementation of an own dialogue in Gambas:

Source code (main) program (FMain.class):

[1] ' Gambas class file
[2]
[3] Public Sub Form_Open()
[4]   Dim cData As Collection
[5]   Dim sDialogTitel As String
[6]   Dim frmLogin As New FLogin
[7]
[8]   FMain.Center
[9]   FMain.Resizable = False
[10]   sDialogTitel = "Enter the data!"
[11]
[12] ' Before the main window is displayed, the login window is automatically opened 'modally'.
[13]   cData = frmLogin(sDialogTitel)
[14]   If Not cData Then ' Cancel?
[15]   Me.Close() ' Exit the main program without a comment.
[16]      Return
[17]   Endif
[18]
[19]   If cData["password"] <> "mgA+" Then ' Failed login attempt? End with comment.
[20]      Message.Title = "Error in the dialogue box".
[21]      Message.Error("Login failed!")
[22]      Me.Close()
[23]      Return
[24]   Else
[25]    ' Otherwise start main program ...
[26]     lblGreet.Text = Subst$("So you are &1. Good to know!", cData["name"])
[27]   Endif
[28]
[29] End ' Form_Open()

Comment:

• To save the return value of the _call(..) method, the variable cData of the data type Collection is created in line 4. It corresponds to the type of the return value.
• In line 6, a new window of the type FLogin - which is the dialogue - is created.
• The complete functionality of the dialogue is encapsulated in a single _call(..) method. In line 13, the _call(..) method is called. The dialogue title is set as the argument.
• When the dialogue box is closed, the return value of the _call(…) method is stored in the variable cData.
• If the variable cData is empty because the dialogue was cancelled, the main program is terminated (lines 14 to 17).
• If an incorrect password was entered (line 19), then an error is displayed and the main program is terminated (lines 22 and 23).
• If the correct password is entered, the main program is displayed and a message is displayed using the saved name (line 26) from the dialogue.

Source code dialogue (FLogin.class):

[1] ' Gambas class file
[2]
[3] Public Sub _call(sTitel As String) As Collection
[4]   Me.Text = sTitel
[5]
[6]   If Me.ShowModal() = 0 Then
[7]      Return Null
[8]   Else
[9]      Return ["name": txtName.Text, "password": txtPassword.Text]
[10]   Endif
[11]
[12] End ' _call(sTitel As String)
[13]
[14] Public Sub btnCancel_Click()
[15]   Me.Close(0)
[16] End ' btnCancel_Click()
[17]
[18] Public Sub btnOK_Click()
[19]   Me.Close(1)
[20] End ' btnOK_Click()
[21]
[22] Public Sub txtName_Activate()
[23]   txtPassword.SetFocus()
[24] End ' txtName_Activate()
[25]
[26] Public Sub txtPassword_Activate()
[27]   btnOK_Click()
[28] End ' txtPassword_Activate()

Comment:

• The _call(..) method is given the dialogue title as an argument in line 3.
• After closing the dialogue, lines 6 to 10 evaluate which value the dialogue window returned when closing in Me.ShowModal() in line 6. Note: This return value has nothing to do with the function value of the _call(..) method.
• The value of Me.ShowModal() is either 0 if the dialogue was cancelled (line 15) or 1 (line19) if the edited data was accepted.
• Depending on the value, either an empty collection is returned or the collection with the entered name and password.

Notes:

• The Window.ShowModal() method has a (often forgotten) return value. If one has a window modally open and closes it with ME.Close(iStatus), then the return value of ShowModal() is equal to iStatus.
• Note that you can also pass an optional argument to the Window.Close() method to evaluate it in an appropriate way.
• If an open window is closed with the close symbol [x] in the window bar, the value 0 is automatically returned.

The results in the first example are not spectacular - but exactly those that were to be expected.The dialogue is displayed as a preliminary program and you are prompted to enter the required data:

Figure 12.4.4.1.2: Dialogue Box - Data Entry

If the password is incorrect - stored in the return value of the dialogue cData[“password”] - you will see this message and then nothing more … .

Figure 12.4.4.1.3: Error message

If the login was successful, the main program is displayed. The name entered in the dialogue (cData[“name”]) is used in the comment:

Figure 12.4.4.1.4: The main program is displayed …