FILTER KEYSTROKE

version 6.0

FILTER KEYSTROKE (filteredChar)

FILTER KEYSTROKE enables you to replace the character entered by the user into a field or an enterable area with the first character of the string filteredChar you pass.

If you pass an empty string, the keystroke is cancelled and ignored.

Usually, you will call FILTER KEYSTROKE within a form or object method while handling an On Before Keystroke form event. To detect keystroke events, use the command Form event. To obtain the actual keystroke, use the command Keystroke.

IMPORTANT NOTE: The command FILTER KEYSTROKE allows you to cancel or replace the character entered by the user with another character. On the other hand, if you want to insert more than one character for a specific keystroke, remember that the text you see on the screen is NOT YET the value of the data source field or variable for the area being edited. The data source field or variable is assigned the entered value after the data entry for the area is validated. It is therefore up to you to "shadow" the data entry into a variable and then to work with this shadow value and reassign the enterable area (see the example in this section).

You will use the command FILTER KEYSTROKE for:

• Filtering characters in a customized way

• Filtering data entry in a way that you cannot produce using data entry filters

• Implement dynamic lookup or type-ahead areas

WARNING: If you call the command Keystroke after calling FILTER KEYSTROKE, the character you pass to this command is returned instead of the character actually entered.

1. Using the following code:

      ` myObject enterable area object method
   Case of 
      : (Form event=On Load )
         myObject:=""
      : (Form event=On Before Keystroke )
         If(Position(Keystroke;"0123456789")>0)
            FILTER KEYSTROKE("*")
         End if
   End case

All the digits entered in the area myObject are transformed into star characters.

2. This code implements the behavior of a Password enterable area in which all the entered characters are replaced (on the screen) by random characters:

      ` vsPassword enterable area object method
   Case of 
      : (Form event=On Load )
         vsPassword:=""
         vsActualPassword:=""
      : (Form event=On Before Keystroke )
         Handle keystroke (->vsPassword;->vsActualPassword)
         If (Position(Keystroke;Char(Backspace )+Char(Left Arrow Key )+   
               Char(Right Arrow Key )+Char(Up Arrow Key )+Char(Down Arrow Key ))=0)
            FILTER KEYSTROKE(Char(65+(Random%26)))
         End if 
   End case

After the data entry is validated, you retrieve the actual password entered by the user in the variable vsActualPassword. Note: The method Handle keystroke is listed in the Example section for the command Keystroke.

3. In your application, you have some text areas into which you can enter a few sentences. Your application also includes a dictionary table of terms commonly used throughout your database. While editing your text areas, you would like to be able to quickly retrieve and insert dictionary entries based on the selected characters in a text area. You have two ways to do this:

- Provide some buttons with associated keys, or

- Intercept special keystrokes during the editing of the text area

This example implements the second solution, based on the Help key.

As explained above, during the editing of the text area, the data source for this area will be assigned the entered value after you validate the data entry. In order to retrieve and insert dictionary entries into the text area while this area is being edited, you therefore need to shadow the data entry. You pass pointers to the enterable area and the shadow variable as the first two parameters, and you pass a string of the "forbidden" characters as the third parameter. No matter how the keystroke will be treated, the method returns the original keystroke. The "forbidden" characters are those that you do not want to be inserted into the enterable area and you want to treat as special characters.

      ` Shadow keystroke project method
      ` Shadow keystroke ( Pointer ; Pointer ; String ) -> String
      ` Shadow keystroke ( -> srcArea ; -> curValue ; Filter ) -> Old keystroke
   C_STRING(1;$0)
   C_POINTER($1;$2)
   C_TEXT($vtNewValue)
   C_STRING(255;$3)
      ` Return the original keystroke
   $0:=Keystroke
      ` Get the text selection range within the enterable area
   GET HIGHLIGHT($1->;$vlStart;$vlEnd)
      ` Start working with the current value
   $vtNewValue:=$2->      ` Depending on the key pressed or the character entered,
      ` Perform the appropriate actions
   Case of
         ` The Backspace (Delete) key has been pressed    
      : (Ascii($0)=Backspace )
            ` Delete the selected characters or the character at the left of the text cursor 
         $vtNewValue:=Delete text ($vtNewValue;$vlStart;$vlEnd)
            ` An Arrow key has been pressed
            ` Do nothing, but accept the keystroke
      : (Ascii($0)=Left Arrow Key )
      : (Ascii($0)=Right Arrow Key )
      : (Ascii($0)=Up Arrow Key )
      : (Ascii($0)=Down Arrow Key )

         ` An acceptable character has been entered
      : (Position($0;$3)=0)
         $vtNewValue:=Insert text ($vtNewValue;$vlStart;$vlEnd;$0)
   Else 
         ` The character is not accepted
      FILTER KEYSTROKE("")
   End case 
      ` Return the value for the next keystroke handling
   $2->:=$vtNewValue

This method uses the two following submethods:

      ` Delete text project method
      ` Delete text ( String ; Long ; Long ) -> String
      ` Delete text ( -> Text ; SelStart ; SelEnd ) -> New text
   C_TEXT($0;$1)
   C_LONGINT($2;$3)
   $0:=Substring($1;1;$2-1-Num($2=$3))+Substring($1;$3)

      ` Insert text project method
      ` Insert text ( String ; Long ; Long ; String ) -> String
      ` Insert text ( -> srcText ; SelStart ; SelEnd ; Text to insert ) -> New text
   C_TEXT($0;$1;$4)
   C_LONGINT($2;$3)
   $0:=$1
   If ($2#$3)
      $0:=Substring($0;1;$2-1)+$4+Substring($0;$3)
   Else 
      Case of 
         : ($2<=1)
            $0:=$4+$0
         : ($2>Length($0))
            $0:=$0+$4
      Else 
         $0:=Substring($0;1;$2-1)+$4+Substring($0;$2)
      End case 
   End if 

After you have added these project methods to your project, you can use them in this way:

      ` vsDescription enterable area object method
   Case of 
      : (Form event=On Load )
         vsDescription:=""
         vsShadowDescription:=""
            ` Establish the list of the "forbidden" characters to be treated as special keys
            ` ( here, in this example, only the Help Key is filtered)
         vsSpecialKeys:=Char(HelpKey)
      : (Form event=On Before Keystroke )
         $vsKey:=Shadow keystroke (->vsDescription;->vsShadowDescription;vsSpecialKeys)
         Case of 
            : (Ascii($vsKey)=Help Key )
                       ` Do something when the Help key is pressed
                  ` Here, in this example, a Dictionary entry must be searched and inserted
                LOOKUP DICTIONARY (->vsDescription;->vsShadowDescription)
         End case 
   End case 

The LOOKUP DICTIONARY project method is listed below. Its purpose is to use the shadow variable for reassigning the enterable area being edited:

      ` LOOKUP DICTIONARY project method
      ` LOOKUP DICTIONARY ( Pointer ; Pointer )
      ` LOOKUP DICTIONARY ( -> Enterable Area ; ->ShadowVariable )

   C_POINTER($1;$2)
   C_LONGINT($vlStart;$vlEnd)

      ` Get the text selection range within the enterable area
   GET HIGHLIGHT($1->;$vlStart;$vlEnd)
      ` Get the selected text or the word on the left of the text cursor
   $vtHighlightedText:=Get highlighted text ($2->;$vlStart;$vlEnd)
      ` Is there something to look for?
   If ($vtHighlightedText#"")
         ` If the text selection was the text cursor, 
         ` the selection now starts at the word preceeding the text cursor
      If ($vlStart=$vlEnd)
         $vlStart:=$vlStart-Length($vtHighlightedText)
      End if 
         ` Look for the first avaliable dictionary entry  
      QUERY([Dictionary];[Dictionary]Entry=$vtHighlightedText+"@")
         ` Is there one?
      If (Records in selection([Dictionary])>0)
            ` If so, insert it in the shadow text
         $2->:=Insert text ($2->;$vlStart;$vlEnd;[Dictionary]Entry)
            ` Copy the shadow text to the enterable being edited
         $1->:=$2->
            ` Set the selection just after the insert dictionary entry
         $vlEnd:=$vlStart+Length([Dictionary]Entry)
         HIGHLIGHT TEXT(vsComments;$vlEnd;$vlEnd)
      Else 
            ` There is no corresponding entry in the Dictionary    
         BEEP
      End if 
   Else 
         ` There is no highlighted text  
      BEEP
   End if 

The Get highlighted text method is listed here:

      ` Get highlighted text project method
      ` Get highlighted text ( String ; Long ; Long ) -> String
      ` Get highlighted text ( Text ; SelStart ; SelEnd ) -> highlighted text
   C_TEXT($0;$1)
   C_LONGINT($2;$3)
   If ($2<$3)
      $0:=Substring($1;$2;$3-$2)
   Else 
      $0:=""
      $2:=$2-1
      Repeat 
         If ($2>0)
            If (Position($1[[$2]];"  ,.!?:;()-_–—")=0)
               $0:=$1[[$2]]+$0
               $2:=$2-1
            Else 
               $2:=0
            End if 
         End if 
      Until ($2=0)
   End if 

Form event, Get edited text, Keystroke.