GAMBAS BOOK 3.19.1

Messages in a programme assist programme developers in designing and testing, and users in successfully using the programme. The class Message is suitable for displaying messages in a message box. The class is static and can be used like a function that has a maximum of 4 arguments. The first argument - the message text - is necessary, the other three are optional. The arguments are of type string and the function value is an integer number from the set {1,2,3}. The messages can be output as plain text or in HTML format. Depending on the type, a meaningful icon is displayed in the message box. The messages can also be divided into the two categories “static text of the message” and “dynamic text of the message” if the structural composition of the text of the message is used as a criterion. In the case of a dynamic message text, for example, the current values of programme variables or system messages are inserted into the message text. Since the message box has only a small standard width, you must format the text of the message in a suitable way to achieve the intended effect. You can resize the message box at programme runtime.

Gambas has 5 different message box types:

• information box (message.info(…) = message(…)) as default.
• question box (message.question(…)).
• warning box (message.warning(…))
• error box (message.error(…))
• delete box (message.delete(…))

This is the syntax for the standard message box as an information message box and for the warning message box:

FUNCTION Info (Message AS String [, Button AS String ]) AS Integer
FUNCTION Warning (Message AS String [, Button1 AS String,Button2 AS String,Button3 AS String]) AS Integer

Figure 20.1.1.1: Info message box

Figure 20.1.1.2: Warning message box

The trigger for the display of a message box is either a special state of the programme that is evaluated internally or a reaction of the user (examples: Pressing a button or a mouse reaction or calling up a menu item). In any case, the display of a message box causes an interruption of the programme, because the call of the message box is modal. The programme is not continued until the user reacts to the message, whereby there are a maximum of three different ways to do this.

The answer to the following questions will help you decide whether to use a message box:

• At what point in the programme flow does it seem necessary to interrupt the programme to display a message in a message box?
• Which type of the 5 possible types of message box should be used?
• What format should the text of the message have?
• How many buttons should be displayed in the message box and what text should these buttons receive?
• In what form should the function value returned by the message box object be recorded? How are the possible function values evaluated and how are the function values reacted to in the programme?
• Are translations into other languages provided for the programme?

The following examples are sufficiently commented so that you can easily recognise special features and alternative solutions are also offered.

The message here informs the user of a (successfully) completed programme action. He only has to click on the OK button to cancel the programme interruption.

Figure 20.1.1.1: Info message box

  ...
  Message.Info("Die Datei " & User.Home &/ "message.txt" & " wurde gespeichert")
  ...

Alternative:

  ...
  Message.Info("Die Datei " & User.Home &/ "message.txt" & " wurde gespeichert", "OK")
  ...

The text of the message is of type Text/Plain and 2 buttons are used:

Figure 20.1.1.2.1: Info message box

PUBLIC SUB btnAktuelleKonfigurationSpeichern_Click()
  DIM iIndexMBQ AS Integer
 
  iIndexMBQ = Message.Question("Soll die aktuelle Konfiguration der V24-Schnittstelle \
              gespeichert werden?", "Ja", "Nein")
 
  IF iIndexMBQ = 1 THEN
     v24Settings["V24Konfiguration/Port-Name"] = cmbRS232PortName.Text
     ...
     v24Settings["V24Konfiguration/Datenflusskontrolle"] = cmbFlow.Text
     v24Settings.Save
  ELSE
     RETURN
  ENDIF
END

Alternative:

PUBLIC SUB btnAktuelleKonfigurationSpeichern_Click()
  IF Message.Question("Soll die aktuelle Konfiguration der V24-Schnittstelle \
     gespeichert werden?", "Ja", "Nein") = 1 THEN
     v24Settings["V24Konfiguration/Port-Name"] = cmbRS232PortName.Text
     ...
     v24Settings["V24Konfiguration/Datenflusskontrolle"] = cmbFlow.Text
     v24Settings.Save
  ELSE
     RETURN
  ENDIF
END

Calling the message box interrupts the programme. If the user has pressed the “Yes” button, then the current configuration of the V24 interface is saved and then the programme is continued. In the alternative case “No”, the programme will continue immediately. If you had used the following text:

IF Message.Question("Soll die aktuelle Konfiguration der V24-Schnittstelle gespeichert werden?", \
   "Na klar...", "Nö – jetzt nicht!") = 1 THEN

then this would have had no influence on the function value, which is only determined by the button pressed, because their order in the message box implies a ranking:

• Button1 “Alright” → function value = 1,
• Button2 “Nope - not now!” → function value = 2,
• Button3 not used here; but would result in function value = 3.

Figure 20.1.1.3.1: Question message box.

In this case, either 1 or 2 or 3 is returned as the function value. You should evaluate the function value using the Select … Case control structure:

SELECT message.question("Soll die Datei message.txt gesichert werden?", "Ja", "Nein", "Abbruch")
   CASE 1
      File.Save(dateipfad &/ message.txt , txaTextFeld.Text)
   CASE 2
      TRY KILL dateipfad &/ message.txt
      IF ERROR THEN
         Message.Error("Die Datei konnte nicht gelöscht werden!")
         RETURN
      ENDIF
   CASE 3
      RETURN
END SELECT

Figure 20.1.1.4.1: Info Message Box (HTML).

The text of the message can be formatted in an appropriate way by choosing text of type text/html:

PUBLIC SUB btnInfo_Click()
  DIM text, leerzeile AS String
  DIM iCount AS Integer
 
  FOR iCount = 1 TO 10 * 15
      leerzeile &= " "
  NEXT
  text = "<center><h2><font color='red'>Example to make bar chart</h2></font></center>"
  text &= "<center><p>This example has made by Tobias Boege - Markgraf-Albrecht-Gymnasium \
           Osterburg (Germany)<br>"
  text &= "Mail: tobias@gambas-buch.de</center></p>"
  text &= "<hr>"
  text &= "<center><b>Web: http://www.gambas-buch.de</b></center>"
  text &= "<hr>"
  text &=  leerzeile
 
  Message.Info(text, "&Close") ' ---> Schließen mit [ALT]+[C]
 
END

The special features of this message are the insertion of a line of protected spaces to enforce the required width of the box and the two horizontal lines as well as the marking of parts of the text with the attribute “bold” and the use of colours. Such a message is informative and stands out.

Figure 20.1.1.5.1: Info Message Box (HTML)

You can call up this message from a menu, for example:

...
  DIM leerzeile AS String
  DIM iCount AS Integer
 
  FOR iCount = 1 TO 10 * 1
      leerzeile &= " "
  NEXT
 
  Message.Info(File.Load("help.htm") & leerzeile)
...

or via the F1 key:

PUBLIC SUB Form_KeyPress()
  DIM leerzeile AS String
  DIM iCount AS Integer
 
  FOR iCount = 1 TO 10 * 1
      leerzeile &= " "
  NEXT
 
  IF Key.Code = Key.F1 THEN Message.Info(File.Load("help.htm") & leerzeile)
 
END

If you save the following HTML source text in the file help.html in the project directory, you cannot change the text in the HTML file later because it has been compiled. The style instructions are anchored here as inline CSS in the HTML file. The alternative of maintaining these style instructions in a separate CSS file is certainly only worthwhile for larger projects.

<html>
  <head>
    <title>Hilfetext</title>
    <meta http-equiv="content-type" content="text/html; charset=UTF8">
    <style type="text/css">
    html {background-color:#FFFFDF; color:#000000; font-family:Verdana,Helvetica,Arial,sans-serif; \
          font-size:12px;}
    H1 {font-size:12px;}
    <!-- Alternative: <link rel="stylesheet" type="text/css" href="help.css" /> -->
    </style>
  </head>
  <body>
    <h1><font color='Blue'>Ich bin die kleine Hilfe ...</font></h1>
    <hr>
    <p><b>F1HilfeW</b> ist eine einfache Anwendung mit einer Programm-Hilfe im HTML-Format:</p>
    <p>
    Die <b><font color='Blue'>F1-Taste</font></b> ruft das Hilfefenster der Anwendung F1HilfeW auf.<br>
    Die <b><font color='Blue'>Escape-Taste (ESC)</font></b> beendet das Hilfefenster.<br>
    Das <b><font color='Blue'>Hilfefenster</font></b> kann in der Größe verändert werden.<br>
    </p>
    <hr>
    <p>
    Das Programm (Version 0.0.20) wurde von Hans Lehmann 2012 entwickelt.
    <br />
    Weitere Hilfe finden Sie unter www.gambas-buch.de.<br />
    Anfragen bitte nur an hans@gambas-buch.de.
    </p>
  </body>
</html>

Of course, it is also possible to go one size smaller in the text mark-up, as these two examples show:

Figure 20.1.1.5.2: Warning message box (HTML)

...
Message.Warning("Die Datei <b>message.txt</b> ist gesperrt!", "Die Datei entsperren", "Abbruch")
...

Figure 20.1.1.5.3: Warning message box (HTML)

...
  DIM text, s AS String
  DIM iCount AS Integer
 
  FOR iCount = 1 TO 10 * 8 ' auch mal mit Werten < 8 probieren...
      s &= "&nbsp;"
  NEXT
 
  text = s & "<br />"
  text &= "Das Verzeichnis <font color='red'>Home.User &/ Sicherung</font> existiert nicht!"
  Message.Warning(text, "&Ignorieren")
...

Messages are particularly informative if, for example, you catch an error in a programme at a certain point that is considered time-critical when it occurred and you could then refer to displayed error codes in the error message for error analysis or to information about the programme section or module that triggered an error. In addition, you can add your own texts to the messages. As a programme developer, you can certainly do something with the following error message. Especially if several developers are involved in the project:

Illustration 20.1.1.6.1: Error Message Box with Error Code and Hints

You are told that an error has occurred, you get the corresponding English error text for error code 43 and you also see the name of the procedure and the line number in the programme where an error occurred.

The source code - with the corresponding programme section for programme developers - is given in full:

PUBLIC SUB btnCreatingFile_Click()
  DIM hFile AS Stream
  DIM sErrorText AS String
  IF NOT Exist(TextBox1.Text) THEN
     hFile = OPEN TextBox1.Text FOR CREATE
 '-- Den Benutzer über den Erfolg der Operation informieren
     Message.Info("Die Datei wurde angelegt.")
     CLOSE #hFile
  ELSE
 '-- Wenn die Datei existiert, eine Fehlermeldung ausgeben
     Message.Error("Datei existiert bereits.")
  ENDIF
  CATCH
  SELECT CASE Error.Code
    CASE 43 '---Access forbidden
    CASE 44 '-- File name is too long
    CASE 45 '-- File or Directory does not exist
    CASE 46 '-- File is a Directory
    CASE 48 '-- Write Error
    CASE ELSE
  '-- NOOP
  END SELECT
 
  Message.Error("FehlerCode: " & Error.Code & Chr(10) & "FehlerText: " & Error.Text & Chr(10) & \
                "FehlerQuelle: " & Error.Where)
 
END ' btnCreatingFile_Click()

In the tested programme version, you will probably only use the following statement block:

...
SELECT CASE Error.Code
    CASE 43
     sErrorText = "Sie besitzen nicht die Rechte,\num diese Datei anzulegen."
    CASE 44
     sErrorText = "Der Dateiname ist zu lang."
    CASE 45
     sErrorText = "Die Datei existiert nicht."
    CASE 46
     sErrorText = "Der Pfad führt zu einem Ordner."
    CASE 48
     sErrorText = "Fehler beim Schreiben in die Datei."
    CASE ELSE
     sErrorText = "Fehler?"
  END SELECT
 
  Message.Error(sErrorText)
...

The error message is intended for the programme user, has a self-written German text in the message box and clearly names the error:

Figure 20.1.1.6.2: Error message box with own text