User Tools

Site Tools

k12:k12.4:k12.4.4:k12.4.4.1:start Own Dialogues - Project 1

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 shows two labels, two text boxes and two buttons:

Figure Dialogue box (IDE)

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

In essence, one defines a dialogue box → Figure and calls it using the special _call(..)-method in the main program. For information on this method, see the Gambas documentation → 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
[3] Public Sub Form_Open()
[4]   Dim cData As Collection
[5]   Dim sDialogTitel As String
[6]   Dim frmLogin As New FLogin
[8]   FMain.Center
[9]   FMain.Resizable = False
[10]   sDialogTitel = "Enter the data!"
[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
[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
[29] End ' Form_Open()


  • 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
[3] Public Sub _call(sTitel As String) As Collection
[4]   Me.Text = sTitel
[6]   If Me.ShowModal() = 0 Then
[7]      Return Null
[8]   Else
[9]      Return ["name": txtName.Text, "password": txtPassword.Text]
[10]   Endif
[12] End ' _call(sTitel As String)
[14] Public Sub btnCancel_Click()
[15]   Me.Close(0)
[16] End ' btnCancel_Click()
[18] Public Sub btnOK_Click()
[19]   Me.Close(1)
[20] End ' btnOK_Click()
[22] Public Sub txtName_Activate()
[23]   txtPassword.SetFocus()
[24] End ' txtName_Activate()
[26] Public Sub txtPassword_Activate()
[27]   btnOK_Click()
[28] End ' txtPassword_Activate()


  • 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.


  • 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 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 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 The main program is displayed …




The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k12/k12.4/k12.4.4/k12.4.4.1/start.txt · Last modified: 01.02.2022 (external edit)

Page Tools