DOCUMENT #767
===========================================================================
TRAPPING KEYSTROKES IN EEPS
===========================================================================
PRODUCT: R:BASE VERSION: 4.5+ or Higher
===========================================================================
CATALOG: Forms, Reports & Labels AREA : Forms
===========================================================================
EEPs always execute when the placement action occurs -- a field is exited,
a row is saved, etc. You can't keep the EEP code from executing, but you
can make it appear as if it did not execute by trapping for keystrokes and
returning immediately to the form if certain keys were pressed, only
executing the remainder of the EEP code based on other keystrokes.
A conditional EEP is generally placed On exit from field. It is conditional
on the keystroke used to leave the field.
When we use the terminology "execute the EEP" we mean that all the code in
the EEP executes. The EEP always executes, but if it immediately returns you
to the form without performing any action, we say the EEP did not execute --
it really did but it didn't do anything.
You can move off a field using the keystrokes: [Enter], [Down], [Up], [Tab],
and [Shift][Tab]. The [PgDn], and [PgUp] keys also move you off the field if
you are going to a second page of your form, but these keys are best
reserved for use with table level EEPs.
Directional EEPs
In its simplest implementation , trap the direction of cursor movement so
that an EEP executes when the user is moving forward but not backward
through the fields in a form. The EEP is placed On exit from field. The
code sample below illustrates this.
*(FORWARD.EEP)
IF (LASTKEY(0)) = '[UP]' OR +
(LASTKEY(0)) = '[SHIFT][TAB]' THEN
RETURN
ENDIF
*( EEP code to perform actions below here)
Embedding these lines into the beginning of your EEP allows the user to
"pass over" the field when the user is moving backwards through the field
order. The EEP executes, but immediately returns to the form without
performing the coded actions. For example, if your EEP displayed a menu,
it would only display as the user moves down through the fields in the
form. If they backup, the menu does not display.
Press a key to execute
Another option is to trap for a deliberate keystroke on the field to cause
it to execute the coded actions, rather than executing whenever passing
over the field. The keystrokes that work best for trapping deliberate
execution are [F2] and any [ALT] combination. Again, the EEP is placed
On exit from field. For example, establish "hot-keys" for the field as
illustrated in the code samples below.
This code at the beginning of an EEP returns the user to the form unless
they have pressed F2. If the users presses the F2 key in the field, then
the rest of the EEP executes.
IF (LASTKEY(0)) <> '[F2]' THEN
RETURN
ENDIF
*( EEP code to perform actions below here)
This code at the beginning of the EEP checks to see if the user press Alt-Q.
Any other keystroke returns to the user to the form and does not execute
the rest of the code in the EEP.
IF (LASTKEY(0)) <> '[ALT]Q' THEN
RETURN
ENDIF
*( EEP code to perform actions below here)
The keys being trapped for can be combined into one IF...THEN statement as
shown below.
IF (LASTKEY(0)) NOT IN ('[F2]','[ALT]Q','[ALT]M') THEN
RETURN
ENDIF
*( EEP code to perform actions below here)
Using the new SET KEYMAP command of R:BASE 4.5 Plus!, remap various function
keys to act as [F2]. The F2 key moves the cursor off the field and triggers
the exit EEP. Then have the EEP further interrogate which function key was
actually struck.
Before letting the user into the form, remap your function keys as shown
below.
SET KEYMAP [F3] = [F2]
SET KEYMAP [F4] = [F2]
SET KEYMAP [F5] = [F2]
SET KEYMAP [F6] = [F2]
SET KEYMAP [F7] = [F2]
In the EEP, trap for the LASTKEY(0) looking for [F2]. Then interrogate
LASTKEY(1) to find the actual keystroke used.
IF (LASTKEY(0)) <> '[F2]' THEN
RETURN
ELSE
IF (LASTKEY(1)) NOT IN ('[F4]','[F5]','[F6]','[F7]') THEN
RETURN
ENDIF
ENDIF
*( EEP code to perform actions below here
different sections of code execute depending on
the actual function key pressed )
Execute different actions
There are two basic methods to execute different actions in the EEP code.
You can include all the code in the EEP, or you can RUN a separate command
file. Use either IF...THEN logic, or SWITCH...CASE logic to execute
subroutines within the same EEP. For example,
IF (LASTKEY(0)) <> '[F2]' THEN
RETURN
ELSE
IF LASTKEY(1) NOT IN ('[F4]','[F5]','[F6]','[F7]') THEN
RETURN
ENDIF
ENDIF
IF (LASTKEY(1)) = '[F4]' THEN
*( Execute code subroutine for [F4] action)
ENDIF
IF (LASTKEY(1)) = '[F5]' THEN
*( Execute code subroutine for [F5]action)
ENDIF
IF (LASTKEY(1)) = '[F6]' THEN
*( Execute code subroutine for [F6] action)
ENDIF
IF (LASTKEY(1)) = '[F7]' THEN
*( Execute code subroutine for [F7] action)
ENDIF
RETURN
Or use the SWITCH and CASE logic to affect the same ends.
Rather than having the code actually stored within the EEP, have the EEP
call subroutines in other files. The advantage in using this method is that
your code will be cleaner and more modular. The disadvantage (which is in
turn an advantage for the previous method) is that having all code in one
EEP, you can see it all when editing the EEP code. This is useful when using
the new SHIFT-F4 to edit EEPs while modifying the form.
IF (LASTKEY(0)) <> '[F2]' THEN
RETURN
ELSE
IF LASTKEY(1) NOT IN ('[F4]','[F5]','[F6]','[F7]') THEN
RETURN
ENDIF
ENDIF
SWITCH (LASTKEY(1))
CASE '[F4]'
RUN F4.EEP
BREAK
CASE '[F5]'
RUN F5.EEP
BREAK
CASE '[F6]'
RUN F4.EEP
BREAK
CASE '[F7]'
RUN F5.EEP
BREAK
ENDSW