Form event

version 6.5 (Modified)

Form event Number

Parameter	Type		Description
This command does not require any parameters
Function result	Number		Form event number

Form event returns a numeric value identifying the type of form event that has just occurred. Usually, you will use Form event from within a form or object method.

4th Dimension provides the following predefined constants:

Constant	Value	Description
On Load	1	The form is about to be displayed or printed
On Unload	24	The form is about to be exited and released
On Validate	3	The record data entry has been validated
On Clicked	4	A click occurred on an object
On Double Clicked	13	A double click occurred on an object
On Before Keystroke	17	A character is about to be entered in the object that has the focus
		Get edited text returns the object's text without this character
On After Keystroke	28	A character is about to be entered in the object that has the focus
		Get edited text returns the object's text including this character
On Getting Focus	15	A form object is getting the focus
On Losing Focus	14	A form object is losing the focus
On Activate	11	The form's window becomes the frontmost window
On Deactivate	12	The form's window ceases to be the frontmost window
On Outside Call	10	The form received a CALL PROCESS call
On Drop	16	Data has been dropped onto an object
On Drag Over	21	Data could be dropped onto an object
On Menu Selected	18	A menu item has been chosen
On Data Change	20	Object Data has been modified
On Plug in Area	19	An External object requested its object method to be executed
On Header	5	The form's header area is about to be printed or displayed
On Printing Detail	23	The form's detail area is about to be printed
On Printing Break	6	One of the form's break areas is about to be printed
On Printing Footer	7	The form's footer area is about to be printed
On Close Box	22	The window's close box has been clicked
On Display Detail	8	A record is about to be displayed in a list
On Open Detail	25	A record is double clicked and you are going to the input form
On Close Detail	26	You left the input form and are going back to the output form
On Timer	27	The number of ticks defined by the SET TIMER command has
		passed
On Resize	29	The form window is resized

When a form event occurs, 4th Dimension performs the following actions:

• First, it browses the objects of the form and calls the object method for any object (involved in the event) whose corresponding object event property has been selected.

• Second, it calls the form method if the corresponding form event property has been selected.

Do not assume that the object methods, if any, will be invoked in a particular order. The rule of thumb is that the object methods are always called before the form method. If an object is a subform, the object methods of the subform's list form are called, then the form method of the list form is called. 4D then continues to call the object methods of the parent form. In other words, when an object is a subform, 4D uses the same rule of thumb for the object and form methods within the subform object.

Except for the On Load and On Unload events, if the form event property is not selected for a given event, this does not prevent calls to the object methods for the objects whose same event property is selected. In other words, enabling or disabling an event at the form level has no effect on the object event properties.

The number of objects involved in an event depends on the nature of the event:

• On Load event - All the objects of the form (from any page) whose On Load object event property is selected will have their object method invoked. Then, if the On Load form event property is selected, the form will see its form method invoked.

• On Activate or On Resize event - No object method will be invoked, because this event applies to the form as a whole and not to a particular object. Consequently, if the On Activate form event property is selected, only the form will see its form method invoked.

• On Drag Over event - Only the droppable object involved in the event will see its object method invoked if its On Drag Over object event property is selected. The form method will not be called.

• On Open Detail and On Close Detail events - These events are triggered only in the context of an output form displayed with DISPLAY SELECTION or MODIFY SELECTION, when an existing record is displayed or modified. These events must be placed in the output form method.

• On Timer event - This event is generated only if the form method contains a previous call to the SET TIMER command. If the On Timer form event property is selected, only the form method will receives the event, no object method will be invoked.

WARNING: Unlike all other events, during an On Drag over event, the object method for an object is executed in the context of the process of the drag and drop source object, not in the context of the process of the drag and drop destination object. For more information, see the commands DRAG AND DROP PROPERTIES and Drag and drop position.

The following table summarizes how object and form methods are called for each event type:

Event	Object Methods	Form Method	Which Objects
On Load	Yes	Yes	All objects
On Unload	Yes	Yes	All objects
On Validate	Yes	Yes	All objects
On Clicked	Yes (if clickable) (*)	Yes	Involved object only
On Double Clicked	Yes (if clickable) (*)	Yes	Involved object only
On Before Keystroke	Yes (if keyboard enterable) (*)	Yes	Involved object only
On After Keystroke	Yes (if keyboard enterable) (*)	Yes	Involved object only
On Getting Focus	Yes (if tabbable) (*)	Yes	Involved object only
On losing Focus	Yes (if tabbable) (*)	Yes	Involved object only
On Activate	Never	Yes	None
On Deactivate	Never	Yes	None
On Outside Call	Never	Yes	None
On Drop	Yes (if droppable) (*)	Yes	Involved object only
On Drag Over	Yes (if droppable) (*)	Never	Involved object only
On Menu Selected	Never	Yes	None
On Data Change	Yes (if modifiable) (*)	Yes	Involved object only
On Plug in Area	Yes	Yes	Involved object only
On Header	Yes	Yes	All objects
On Printing Detail	Yes	Yes	All objects
On Printing Break	Yes	Yes	All objects
On Printing Footer	Yes	Yes	All objects
On Close Box	Never	Yes	None
On Display Detail	Yes	Yes	All objects
On Open Detail	Never	Yes	None
On Close Detail	Never	Yes	None
On Resize	Never	Yes	None
On Timer	Never	Yes	None

(*) For more infomation, see the section Events, Objects and Properties below.

IMPORTANT: Always keep in mind that, for any event, the method of a form or an object is called if the corresponding event property is selected for the form or objects. The benefit of disabling events in the Design environment (using the Form and Object Properties windows) is that you can greatly reduce the number of calls to methods and therefore significantly optimize the execution speed of your forms.

WARNING: The On Load and On Unload events are generated for objects if the events are enabled for both objects and the form to which belong. If the events are enabled for objects only, they will not occur; these two events must also be enabled at the form level.

An object method is called if the event can actually occur for the object, depending on its nature and properties. The following section details the events you will generally use to handle the various types of objects.

Clickable objects are mainly handled using the mouse. They include:

• Boolean enterable fields or variables

• Buttons, default buttons, radio buttons, check boxes, button grid

• 3D Buttons, 3D radio buttons, 3D check boxes

• Pop-up menus, hierarchical pop-up menus, picture menus

• Drop-down lists, menus/drop-down lists

• Scrollable areas, hierarchical lists

• Invisible buttons, highlight buttons, radio pictures

• Thermometers, rulers, dials (also known as slider objects)

• Tab controls

• Splitters

After the On Clicked or On Double Clicked object event property is selected for one of these objects, you can detect and handle the clicks within or on the object, using the Form event command that returns On Clicked or On Double Clicked, depending on the case.

If both events are selected for an object, the On Clicked and then the On Double Clicked events will be generated when the user double-clicks the object.

For all these objects, the On Clicked event occurs once the mouse button is released. However, there are two exceptions:

• Invisible buttons - The On Clicked event occurs as soon as the click is made and does not wait for the mouse button to be released.

• Slider objects (thermometers, rulers, and dials) - If the display format indicates that the object method must be called while you are sliding the control, the On Clicked event occurs as soon as the click is made.

Note: Some of these objects can be activated with the keyboard. For example, once a check box gets the focus, it can be entered using the space bar. In such a case, an On Clicked event is still generated.

WARNING: Combo boxes are not considered to be clickable objects. A combo box must be treated as an enterable text area whose associated drop-down list provides default values. Consequently, you handle the data entry within a combo box through the On Before Keystroke, On After Keystroke and On Data Change events.

Keyboard enterable objects are objects into which you enter data using the keyboard and for which you may filter the data entry at the lowest level by detecting On Before Keystroke and On After Keystroke events. You can take advantage of these events using the Get edited text command.

Keyboard enterable objects include:

• All enterable field objects (except Picture, Subform, and BLOB)

• All enterable variables (except Picture, BLOB, Pointer, and Array)

• Combo boxes

After the On Before Keystroke and On After Keystroke event properties are selected for one of these objects, you can detect and handle the keystrokes within the object, using the command Form event that will return On Before Keystroke and then On After Keystroke (for more information, please refer to the description of the Get edited text command).

Notes:

• The command POST KEY generates On Before Keystroke and On After Keystroke events.

• Although hierarchical lists are enterable objects, they do not generate On Before Keystroke and On After Keystroke events.

Modifiable objects have a data source whose value can be changed using the mouse or the keyboard; they are not truly considered as user interface controls handled through the On Clicked event. They include:

• All enterable field objects (except Subtable and BLOB)

• All enterable variables (except BLOB, Pointer, and Array)

• Combo boxes

• External objects (for which full data entry is accepted by the 4D Extension)

These objects receive On Data Change events. After the On Data Change object event property is selected for one of these objects, you can detect and handle the change of the data source value, using the command Form event that will return On Data Change.

Tabbable objects get the focus when you use the Tab key to reach them and/or click on them. The object having the focus receives the characters (typed on the keyboard) that are not accelerators (Windows) or shortcuts (MacOS) to a menu item or to an object such as a button.

All objects are tabbable, EXCEPT the following:

• Non-enterable fields or variables

• Buttons (when used on MacOS)

• Button grid

• 3D buttons, 3D radio buttons, 3D check boxes

• Pop-up menus, hierarchical pop-up menus

• Menus/drop-down lists (when used on MacOS)

• Picture menus

• Scrollable areas

• Invisible buttons, highlight buttons, radio pictures

• Graphs

• External objects (for which full data entry is not accepted by the 4D Extension)

• Tab control

• Splitters

After the On Getting Focus and/or On losing Focus object event properties are selected for a tabbable object, you can detect and handle the change of focus, using the command Form event that will return On Getting Focus or On losing Focus, depending on the case.

Form events can be classified in the following categories:

• General events

         On Load, On Unload, On Validate, On Display Detail, On Open Details, On Close Detail

• Events proper to the form

         On Activate, On Deactivate, On Outside Call, On Close Box, On Menu Selected, On Timer,

On Resize

• Events related to user actions

         On Clicked, On Double Clicked, On Before Keystroke, On After Keystroke, On Getting Focus,

On losing Focus, On Data Change, On Plug in Area

• Drag and drop events

         On Drop, On Drag Over

• Printing Events

         On Header, On Printing Detail, On Printing Break, On Printing Footer

The following table summarizes the equivalence between V6 form events and V3 layout execution cycles.

V6 Events	V3 Layout Execution cycles	V3 command
On Load	Before phase	Before
On Unload	No equivalent execution cycle	None
On Validate	After phase	After
On Clicked	Generic During phase	During
On Double Clicked	Generic During phase	During
On Before Keystroke	No equivalent execution cycle	None
On After Keystroke	No equivalent execution cycle	None
On Getting Focus	No equivalent execution cycle	None
On losing Focus	No equivalent execution cycle	None
On Activate	Activated phase	Activated
On Deactivate	Deactivated phase	Deactivated
On Outside Call	Outside call phase	Outside call
On Drop	No equivalent execution cycle	None
On Drag Over	No equivalent execution cycle	None
On Menu Selected	Generic During phase	During plus Menu selected
On Data Change	Generic During phase	During
On Plug in Area	Generic During phase	During
On Header	Printing header phase	In header
On Printing Detail	Generic During phase	During
On Printing Break	Printing break phase	In break
On Printing Footer	Printing footer phase	In footer
On Close Box	No equivalent execution cycle	OPEN WINDOW (with Close box)
On Display Detail	Before and During phase	Before & During
On Open Detail	Generic During phase	During
On Close Detail	Generic During phase	During
On Timer	No equivalent execution cycle	None
On Resize	No equivalent execution cycle	None

When you open a V3 database using 4th Dimension V6, the program performs two operations:

• Converts the structure file to the new format.

• Converts the data file to the new format.

When using the database after the conversion, if a form has not been edited or modified in the Design environment, it is still stored in the structure file in the way it was with V3. In order to insure compatibility with your existing V3 applications, the form and object event properties are automatically set to reflect the settings "ala V3". This means that the V6 event properties will be automatically selected and the "old V3 commands" will act as they did with version 3:

V6 Events	V3 Layout Execution cycles	V3 command
On Load	Before phase	Before
On Validate	After phase	After
On Clicked	Generic During phase	During
On Double Clicked	Generic During phase	During
On Activate	Activated phase	Activated
On Deactivate	Deactivated phase	Deactivated
On Outside Call	Outside call phase	Outside call
On Menu Selected	Generic During phase	During plus Menu selected
On Data Change	Generic During phase	During
On Plug in Area	Generic During phase	During
On Header	Printing header phase	In header
On Printing Detail	Generic During phase	During
On Printing Break	Printing break phase	In break
On Printing Footer	Printing footer phase	In footer
On Display Detail	Before and During phase	Before & During
On Open Detail	Generic During phase	During
On Close Detail	Generic During phase	During

If an object (field or variable) has the V3 Script only if modified option selected, the event properties are reduced to those corresponding to any During execution cycle that could occur during data entry in V3:

V6 Events	V3 Layout Execution cycles	V3 command
On Clicked	Generic During phase	During
On Double Clicked	Generic During phase	During
On Data Change	Generic During phase	During
On Plug in Area	Generic During phase	During

Once you start editing a form and its objects in V6, the form and object event properties are, by default, set according to the same scheme. To take advantage of the new events introduced by V6, select the event properties for the form and objects in the Design environment, and modify the form and object methods using the new Form event command.

The new events without corresponding V3 execution cycle are:

V6 Events	V3 Layout Execution cycles	V3 command
On Unload	No equivalent execution cycle	None
On Keystroke	No equivalent execution cycle	None
On Getting Focus	No equivalent execution cycle	None
On losing Focus	No equivalent execution cycle	None
On Drop	No equivalent execution cycle	None
On Drag Over	No equivalent execution cycle	None
On Close Box	No equivalent execution cycle	OPEN WINDOW (with Close box)

The new events that allow you to perform actions better tuned to the nature of the events are:

V6 Events	V3 Layout Execution cycles	V3 command
On Clicked	Generic During phase	During
On Double Clicked	Generic During phase	During
On Menu Selected	Generic During phase	During plus Menu selected
On Data Change	Generic During phase	During
On Plug in Area	Generic During phase	During
On Printing Detail	Generic During phase	During
On Display Detail	Before and During phase	Before & During
On Open Detail	Generic During phase	During
On Close Detail	Generic During phase	During

In all the examples discussed here, it is assumed that the event properties of the forms and objects have been selected appropriately.

1. This example sorts a selection of subrecords for the subtable [Parents]Children before a form for the table [Parents] is displayed on the screen:

      ` Method of a form for the table [Parents]
   Case of
      : (Form event=On Load)
         ORDER SUBRECORDS BY([Parents]Children;[Parents]Children'First name;>)
         ` ...
   End case

2. This example shows the On Validate event being used to automatically assign (to a field) the date that the record is modified:

      ` Method of a form
   Case of
         ` ...
      : (Form event=On Validate)
         [aTable]Last Modified On:=Current date
   End case

3. In this example, the complete handling of a drop-down list (initialization, user clicks, and object release) is encapsulated in the method of the object:

      ` asBurgerSize Drop-down list Object Method
   Case of
      : (Form event=On Load)
         ARRAY STRING(31;asBurgerSize;3)
         asBurgerSize{1}:="Small"
         asBurgerSize{1}:="Medium"
         asBurgerSize{1}:="Large"
      : (Form event=On Clicked)
         If (asBurgerSize#0)
            ALERT("You chose a "+asBurgerSize{asBurgerSize}+" burger.")
         End if
      : (Form event=On Unload)
         CLEAR VARIABLE(asBurgerSize)
   End case

4. This example shows how, in an object method, to accept and later handle a drag and drop operation for a field object that only accepts picture values.

      ` [aTable]aPicture enterable picture field object method
   Case of
      : (Form event=On Drag Over)
            ` A drag and drop operation has started and the mouse is currently over the field
            ` Get the information about the source object
         DRAG AND DROP PROPERTIES ($vpSrcObject;$vlSrcElement;$lSrcProcess)
            ` Note that we do not need to test the source process ID number
            ` for the object method is exceptionally here executed in the context of that process
         $vlDataType:=Type ($vpSrcObject->)
            ` Is the source data a picture (field, variable or array) ?
         If (($vlDataType=Is Picture) | ($vlDataType=Picture Array))
               ` If so, accept the drag.
               ` Note that the mouse button is still pressed, the only effect while
               ` accepting the drag is to let 4D highlighting the object so the user
               ` knows the source data could be dropped onto that object
            $0:=0
         Else
               ` If so, refuse the drag
            $0:=-1
               ` In this case, the object is not highlighted
         End if
      : (Form event=On Drop)
            ` The source data has been dropped on the object, we therefore need to copy it
            ` into the object
            ` Get the information about the source object
         DRAG AND DROP PROPERTIES ($vpSrcObject;$vlSrcElement;$lSrcProcess)
         $vlDataType:=Type ($vpSrcObject->)   
         Case of
               ` The source object is Picture field or variable
            : ($vlDataType=Is Picture)
                  ` Is the source object from the same process (thus from the same window and form)?
               If ($lSrcProcess=Current process)
                     ` If so, just copy the source value
                  [aTable]aPicture:=$vpSrcObject->
               Else
                     ` If not, is the source object a variable?
                  If (Is a variable ($vpSrcObject))
                         ` If so, get the value from the source process
                     GET PROCESS VARIABLE ($lSrcProcess;$vpSrcObject->;$vgDraggedPict)
                     [aTable]aPicture:=$vgDraggedPict
                  Else
                     ` If not, use CALL PROCESS to get the field value from the source process
                  End if
               End if
               ` The source object is an array of pictures
            : ($vlDataType=Picture Array)
                  ` Is the source object from the same process (thus from the same window and form)?
               If ($lSrcProcess=Current process)
                     ` If so, just copy the source value
                  [aTable]aPicture:=$vpSrcObject->{$vlSrcElement}
               Else
                     ` If not, get the value from the source process
                  GET PROCESS VARIABLE ($lSrcProcess;$vpSrcObject
                        ->{$vlSrcElement};$vgDraggedPict)
                  [aTable]aPicture:=$vgDraggedPict
               End if
         End case
   End case

Note: For other examples showing how to handle On Drag Over and On Drop events, see the examples of the command DRAG AND DROP PROPERTIES.

5. This example is a template for a form method. It shows each of the possible events that can occur while a summary report uses a form as an output form:

      ` Method of a form being used as output form for a summary report
   $vpFormTable:=Current form table
   Case of
         ` ...
      : (Form event=On Header)
            ` A header area is about to be printed
         Case of
            : (Before selection($vpFormTable->))
               ` Code for the first break header goes here
            : (Level = 1)
               ` Code for a break header level 1 goes here
            : (Level = 2)
               ` Code for a break header level 2 goes here
               ` ...
         End case
      : (Form event=On Printing Detail)
            ` A record is about to be printed
            ` Code for each record goes here
      : (Form event=On Printing Break)
            ` A break area is about to be printed
         Case of
            : (Level = 0)
               ` Code for a break level 0 goes here
            : (Level = 1)
               ` Code for a break level 1 goes here
               ` ...
         End case
      : (Form event=On Printing Footer)
         If(End selection($vpFormTable->))
            ` Code for the last footer goes here
         Else
            ` Code for a footer goes here
         End if      
   End case

6. This example shows the template of a form method that handles the events that can occur for a form displayed using the commands DISPLAY SELECTION or MODIFY SELECTION. For didactic purposes, it displays the nature of the event in the title bar of the form window.

      ` A Form method
   Case of
      : (Form event=On Load)
         $vsTheEvent:="The form is about to be displayed"
      : (Form event=On Unload)
         $vsTheEvent:="The output form has been exited and is about to disappear from the screen"
      : (Form event=On Display Detail)
         $vsTheEvent:="Displaying record #"+String(Selected record number([TheTable]))
      : (Form event=On Menu Selected)
         $vsTheEvent:="A menu item has been selected"
      : (Form event=On Header")
         $vsTheEvent:="The header area is about to be drawn"
      : (Form event=On Clicked")
         $vsTheEvent:="A record has been clicked"
      : (Form event=On Double Clicked")
         $vsTheEvent:="A record has been double clicked"
      : (Form event=On Open Detail)
         $vsTheEvent:="The record #"+String(Selected record number([TheTable]))+" is double-clicked"
      : (Form event=On Close Detail)
         $vsTheEvent:="Going back to the output form"
      : (Form event=On Activate)
         $vsTheEvent:="The form's window has just become the frontmost window"
      : (Form event=On Deactivate)
         $vsTheEvent:="The form's window is no longer the frontmost window"
      : (Form event=On Menu Selected)
         $vsTheEvent:="A menu item has been chosen"
      : (Form event=On Outside call)
         $vsTheEvent:="A call from another has been received"
      Else
         $vsTheEvent:="What's going on? Event #"+String(Form event)
   End case
   SET WINDOW TITLE ($vsTheEvent)

7. For examples on how to handle On Before Keystroke and On After Keystroke events, see examples for the commands Get edited text, Keystroke and FILTER KEYSTROKE.

8. This example shows how to treat clicks and double clicks in the same way as a scrollable area:

      ` asChoices scrollable area object method
   Case of
      : (Form event=On Load)
         ARRAY STRING (...;asChoices;...)
            ` ...
         asChoices:=0
      : ((Form event=On Clicked) | (Form event=On Double Clicked))
         If (asChoices#0)
               ` An item has been clicked, do something here
               ` ...
         End if
            ` ...
   End case

9. This example shows how to treat clicks and double clicks using a different response. Note the use of the element zero for keeping track of the selected element:

      ` asChoices scrollable area object method
   Case of
      : (Form event=On Load)
         ARRAY STRING (...;asChoices;...)
            ` ...
         asChoices:=0
         asChoices{0}:="0"
      : (Form event=On Clicked)
         If (asChoices#0)
            If (asChoices#Num(asChoices))
                  ` A new item has been clicked, do something here
                  ` ...
                  ` Save the new selected element for the next time
               asChoices{0}:=String (asChoices)
            End if
         Else
            asChoices:=Num(asChoices{0})
         End if
      : (Form event=On Double Clicked)
         If (asChoices#0)
               ` An item has been double clicked, do something different here
         End if
            ` ...
   End case

10. This example shows how to maintain a status text information area from within a form method, using the On Getting Focus and On losing Focus events:

      ` [Contacts];"Data Entry" form method
   Case of
      : (Form Event=On Load)
         C_TEXT(vtStatusArea)
         vtStatusArea:=""
      : (Form Event=On Getting Focus)
         RESOLVE POINTER (Last object;$vsVarName;$vlTableNum;$vlFieldNum)
         If (($vlTableNum#0) & ($vlFieldNum#0))
            Case of
               : ($vlFieldNum=1) ` Last name field
                  vtStatusArea:="Enter the Last name of the Contact, it will be automatically capitalized"
                     ` ...
               : ($vlFieldNum=10) ` Zip Code field
                  vtStatusArea:="Enter a 5-digit zip code, it will be automatically checked and validated"
                     ` ...
            End case
         End if
      : (Form Event=On Losing Focus)
         vtStatusArea:=""
            ` ...   
   End case

11. This example shows how to respond to a close window event with a form used for record data entry:

      ` Method for a data entry form
   $vpFormTable:=Current form table
   Case of
         ` ...
      : (Form Event=On Close Box)
         If (Modified record($vpFormTable->))
            CONFIRM ("This record has been modified. Save Changes?")
            If (OK=1)
               ACCEPT
            Else
               CANCEL
            End if
         Else
            CANCEL
         End if
            ` ...
   End case

12. This example shows how to capitalize a text or alphanumeric field each time its data source value is modified:

      ` [Contacts]First Name Object method
   Case of
         ` ...
      : (Form event=On Data Change)
         [Contacts]First Name:= Uppercase(Substring([Contacts]First Name;1;1))
                  +Lowercase(Substring([Contacts]First Name;2))
            ` ...
   End case

CALL PROCESS, Current form table, DRAG AND DROP PROPERTIES, FILTER KEYSTROKE, Get edited text, Keystroke, SET TIMER.