The class MaskBox (gb. form) implements a TextBox with an input mask. As tempting as the use of a MaskBox may seem - the masks 990.990.990.990 for an IP address or 09.09.0000 for a date also allow nonsensical entries such as a date with 02.13.2014 or an IP address with 202.112.237.273.

The most important property of a MaskBox is MaskBox.Mask. The mask is a string that specifies which input characters are allowed (input alphabet). The mask can be set or read out. If the mask is empty, the MaskBox behaves like a TextBox.

Table 16.7.1 Overview of the characters in a MaskBox

Examples of selected masks:

• Value of money → “########0<!,00 €”
• Date → “99.99.9999”
• IPv4 → “##0<.##0<.##0<.##0<”
• Color value (hex) → “&H![0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]&”
• Image size → “[0-9][0-9][0-9]x[0-9][0-9][0-9][ ]px”

For example, specifying a date mask does not necessarily imply that the entry of the date 02/29/2013 - in contrast to 02/29/2012 - is recognized as an incorrect date. You must check entries that are read from a MaskBox to use valid data in the program. This means that there are two tasks for you if you want to use the MaskBox component as a specialized TextBox:

• Choice and testing of a suitable MaskBox mask and
• Checking the string MaskBox.Text with a suitable test method to continue working only with valid data.

In a project with 5 MaskBoxes for different inputs you will be shown how to handle these two tasks successfully. Therefore, the complete source code is presented. There you will find the special input masks and the check procedures, which all rely on the component gb.pcre.

' Gambas class file
 
Public sMaske As String
Private sSubject As String
Private sPattern As String
 
Public Sub Form_Open()
  FMain.Center()
  FMain.Resizable = False
 
  mboxTime.Mask = "00:00 Uhr"
  mboxCurrency.Mask = "########0<!,00 €"
  mboxColor.Mask = "&H![0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]&"  
' mboxPictureSize.Mask = "### x ### px" ' Alternative
  mboxPictureSize.Mask = "[0-9][0-9][0-9]x[0-9][0-9][0-9][ ]px" ' 999 x 100
  mboxPoint3D.Mask = "P(!#0|#0|#0)" ' Koordinaten im Intervall 00..99
 
End ' Form_Open()
 
'*********************************************************************************************************
 
Public Sub MBGroup_Activate()
 
  Select Last.Tag
    Case "T"
      lblValue.Text = MBGroupCheck(mboxTime.Text, "T")
    Case "G"
      lblValue.Text = MBGroupCheck(mboxCurrency.Text, "G")
    Case "F"
      lblValue.Text = MBGroupCheck(mboxColor.Text, "F")
    Case "B" ' Default
      lblValue.Text = MBGroupCheck(mboxPictureSize.Text, "B")
    Case "3D" ' Default
      lblValue.Text = MBGroupCheck(mboxPoint3D.Text, "3D")
  End Select
 
End ' MBGroup_Activate()
 
Public Sub MBGroup_DblClick()
  MBGroup_Activate()
End ' MBGroup_DblClick()
 
Public Function MBGroupCheck(sMBText As String, sTag As Variant) As String
  Dim aMatrix As String[]
 
  Select sTag
    Case "T"
        sSubject = Replace(sMBText, " Uhr", "")
      ' Stunden gibt es von 00-19 Uhr und von 20-23 und 24 Uhr ist 00:00 Uhr
      ' Minuten von 00 bis 59
        sPattern = "^([01][0-9]|2[0-3]):[0-5][0-9]$" ' hh:mm
      ' sPattern = "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$" ' hh:mm:ss mit Sekunden
        If Match(sSubject, sPattern) = True Then
           Return "Zeit-Eingabe O.K."
        Else
           Return "Zeit-Eingabe falsch!"
        Endif ' Match(...) = True ?
    Case "G"
        sSubject = sMBText
        sPattern = "^[ 0-9]+,[0-9]{2}( €)$"
        If Match(sSubject, sPattern) = True Then
           Return "Geldwert-Eingabe O.K."
        Else
           Return "Geldwert-Eingabe falsch!"
        Endif ' Match(...) = True ?
    Case "F"
      sMBText = Replace(sMBText, "&H", "")
      sMBText = Replace(sMBText, "&", "")
      sSubject = sMBText
      sPattern = "^[0-9a-fA-F]{6}$"
      If Match(sSubject, sPattern) = True Then
           mboxColor.Text = "&H" & Upper(sMBText) & "&"
           Return "FarbWert-Eingabe (hex) O.K."
        Else
           Return "Farbwert-Eingabe falsch!"
      Endif ' Match(...) = True ?
    Case "B"
      sSubject = Replace(sMBText, " px", "")
      sPattern = "^[0-9]{3}x[0-9]{3}$"
      If Match(sSubject, sPattern) = True Then           
           Return " Bildgrößenangabe O.K."
        Else
           Return "Bildgrößenangabe falsch!"
      Endif ' Match(...) = True ?
    Case "3D"
      sMBText = Replace(sMBText, "P(", "")
      sMBText = Replace(sMBText, ")", "")
      aMatrix = Split(sMBText, "|")
      Return "x = " & aMatrix[0] & ", y = " & aMatrix[1] & ", z = " & aMatrix[2]
  End Select
End ' MBGroupCheck(...)
 
 
Public Function Match(Subject As String, Pattern As String) As Boolean
  Dim rRegex As Regexp
' Die Komponente gb.pcre (Perl Compatible Regular Expression) muss eingebunden sein
  rRegex = New Regexp(Subject, Pattern)
  If rRegex.Offset = -1 Then
     Return False
  Else
     Return True
  Endif ' rRegex.Offset = -1 
End ' Match(...) As Boolean

You do not need to use the Group and Tag property for the 5 mask boxes if you only perform one check in your project. By selecting the mask “P(!#0|#0|#0)” a check is not necessary for the coordinates of a point in the room, because only valid coordinates can be entered. This is not true for the mask mboxPoint3D.Mask = “P(!##|##|##)” - here it has to be checked! This mask also reserves 2 digits for each coordinate, but the default value for # is a blank character and not zero as in the case of the wildcard character 0.

Figure 16.7.1: Project MaskBox

After the complete input in a MaskBox you can check the input string and display the result by pressing Enter or double-clicking on the MaskBox.