Form event

version 2004.2 (Modified)

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 predefined constants (found in the "Form Events" theme) in order to compare the values returned by the Form event command.

Certain events are generic (generated for any type of object) and others are specific to a particular type of object.

The following events can be generated for any form or object:

The following events are only generated for List boxes:

The following events are only generated for 3D buttons:

The following events are only generated for hierarchical lists:

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 called 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 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 called. Then, if the On Load form event property is selected, the form will have its form method called.

• On Activate or On Resize event - No object method will be called, 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 have its form method called.

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

• 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 receive the event, no object method will be called.

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 DRAG AND DROP PROPERTIES and Drag and drop position commands.

• If the On Mouse Enter, On Mouse Move and On Mouse Leave events have been checked for the form, they are generated for each form object. If they are checked for an object, they are generated only for that object. When there are superimposed objects, the event is generated by the first object capable of managing it that is found going in order from top level to bottom. Objects that are made invisible using the SET VISIBLE command do not generate these events. During object entry, other objects may receive these type of events depending on the position of the mouse.

• Records in list: The sequence of calls to methods and form events in the list forms displayed via MODIFY SELECTION / DISPLAY SELECTION and the subforms is as follows:

   For each object in the header area:
      Object method with On Header event
   Form method with On Header event
   For each record:
      For each object in the detail area:
         Object method with On Display Detail event
      Form method with On Display Detail event 

Calling a 4D command that displays a dialog box from the On Display Detail and On Header events is not allowed and will cause a syntax error to occur.

More particularly, the commands concerned are: ALERT, DIALOG, CONFIRM, Request, ADD RECORD, MODIFY RECORD, DISPLAY SELECTION and MODIFY SELECTION.

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

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

(**) Only list box, hierarchical list and subform type objects support this event.

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 Property List of the Form editor) 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 they are enabled for both the objects and the form to which the objects 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.

Keep in mind that the Property List of the Form editor only displays the events compatible with the selected object or the form.

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

• Boolean enterable fields or variables

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

• 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, list boxes

• 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 several 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 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 After Edit, On Before Keystroke and On After Keystroke events. You can take advantage of these events using the Get edited text command.

Keyboard enterable objects and data types include:

• All enterable field objects of the alpha, text, date, time, number or (On After Edit only) picture type

• All enterable variables of the alpha, text, date, time, number or (On After Edit only) picture type

• Combo boxes

• List boxes.

Note: Even though they are "enterable" objects, hierarchical lists do not manage the On After Edit, On Before Keystroke and On After Keystroke form events (see also the "Hierarchical lists" paragraph below).

• On Before Keystroke and On After Keystroke

Note: Beginning with version 2004.2 of 4th Dimension, the On After Keystroke event can generally be replaced by the On After Edit event (see below).

After the On Before Keystroke and On After Keystroke event properties are selected for an object, you can detect and handle the keystrokes within the object, using the Form event command 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). These events are also activated by language commands that simulate a user action like POST KEY.

Keep in mind that user modifications that are not carried out using the keyboard (paste, drag-drop, etc.) are not taken into account. To process these events, you must use On After Edit.

Note: The On Before Keystroke andOn After Keystroke events are not generated when using an input method. An input method (or IME, Input Method Editor) is a program or a system component that can be used to enter complex characters or symbols (for example, Japanese or Chinese) using a Western keyboard.

• On After Edit

When it is used, this event is generated after each change made to the contents of an enterable object, regardless of the action that caused the change, i.e.:

- Standard editing actions which modify content like paste, cut, delete or cancel;

- Dropping a value (action similar to paste);

- Any keyboard entry made by the user; in this case, the On After Edit event is generated after the On Before Keystroke and On After Keystroke events, if they are used.

- Any modification made using a language command that simulates a user action (i.e., POST KEY).

Be aware that the following actions do NOT trigger this event:

- Editing actions that do not modify the contents of the area like copy or select all;

- Dragging a value (action similar to copy);

- Any modifications made to the contents by programming, except for the commands simulating a user action.

This event can be used to control user actions in order, for example, to prevent the pasting in of text that is too long, to block certain characters or to prevent a password field from being cut.

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 subtables and BLOBs)

• All enterable variables (except BLOBs, pointers, and arrays)

• Combo boxes

• External objects (for which full data entry is accepted by the plug-in)

• Hierarchical lists

• List boxes.

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 Form event command that will return On Data Change. The event is generated as soon as the variable associated with the object is updated internally by 4D (i.e., in general, when the entry area of the object loses the focus).

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 (Mac OS) to a menu item or to an object such as a button.

All objects are tabbable, EXCEPT the following:

• Non-enterable fields or variables

• Button grids

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

• Pop-up menus, hierarchical pop-up menus

• Menus/drop-down lists

• Picture menus

• Scrollable areas

• Invisible buttons, highlight buttons, radio picture buttons

• Graphs

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

• Tab controls

• 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 Form event command that will return On Getting Focus or On losing Focus, depending on the case.

3D buttons let you set up advanced graphic interfaces (for a description of 3D buttons, refer to the Design Reference manual). In addition to generic events, two specific events can be used to manage these buttons:

• On Long Click: This event is generated when a 3D button receives a click and the mouse button is held for a certain length of time. In theory, the length of time for which this event is generated is equal to the maximum length of time separating a double-click, as defined in the system preferences.

This event can be generated for all styles of 3D buttons, 3D radio buttons and 3D check boxes, with the exception of "previous generation" 3D buttons (i.e. background offset style) and arrow areas of 3D buttons with a pop-up menu (see below).

This event is generally used to display pop-up menus in case of long button clicks. The On Clicked event, if enabled, is generated if the user releases the mouse button before the "long click" time limit.

• On Arrow Click: Some 3D button styles can be linked to a pop-up menu and display an arrow. Clicking on this arrow causes a selection pop-up to appear that provides a set of additional actions in relation to the primary button action.

4th Dimension allows you to manage this type of button using the On Arrow Click event. This event is generated when the user clicks on the "arrow" (as soon as the mouse button is held down):

- If the pop-up menu is "separated," the event is only generated when a click occurs on the portion of the button with the arrow.

- If the pop-up menu is "linked," the event is generated when a click occurs on any part of the button. Please note that the On Long Click event cannot be generated with this type of button.

The following 3D button, 3D radio button and 3D check box styles accept the "With pop-up menu" property: None, Toolbar button, Bevel, Rounded bevel and Office XP.

Seven form events can be used to manage various specific features of list boxes:

• On Before Data Entry: This event is generated just before a cell in the list box is edited (before the entry cursor is displayed). This event allows the developer, for example, to display a different text depending on whether the user is in the display or edit mode.

• On Selection Change: This event is generated each time the current selection of rows or columns of the list box is modified. This event is also generated for lists of records and hierarchical lists.

• On Column Moved: This event is generated when a column of the list box is moved by the user using drag and drop. It is not generated if the column is dragged and then dropped in its initial location. The MOVED LISTBOX COLUMN NUMBER command returns the new position of the column.

• On Row Moved: This event is generated when a row of the list box is moved by the user using drag and drop. It is not generated if the row is dragged and then dropped in its initial location.

• On Column Resize: This event is generated when the width of a column in the list box is modified (using the mouse or by programming using the SET LISTBOX COLUMN WIDTH command).

• On Header Click: This event is generated when a click occurs on the header of a column in the list box. In this case, the Self command lets you find out the header of the column that was clicked. The On Clicked event is generated when a right click (Windows) or Ctrl+click (Mac OS) occurs on a column or column header.

If the Sortable property was checked in the list box, you can decide whether or not to authorize a standard sort of the column by passing the value 0 or -1 in the $0 variable:

- If $0 equals 0, a standard sort is performed.

- If $0 equals -1, a standard sort is not performed and the header does not display the sort arrow. The developer can still generate a column sort based on customized sort criteria using the 4th Dimension array management commands.

If the Sortable property is not selected for the list box, the $0 variable is not used.

• On After Sort: This event is generated just after a standard sort is performed (however, it is not generated if $0 returns -1 in the On Header Click event). This mechanism is useful for storing the directions of the last sort performed by the user. In this event, the Self command returns a pointer to the variable of the column that was sorted.

In addition to generic events, three specific events can be used to handle user actions performed on hierarchical lists:

• On Selection Change: This event is generated every time the selection in the hierarchical list is modified after a mouse click or keystroke.

This event is also generated in list box objects and record lists.

• On Expand: This event is generated every time an element of the hierarchical list is expanded with a mouse click or keystroke.

• On Collapse: This event is generated every time an element of the hierarchical list is collapsed with a mouse click or keystroke.

These events are not mutually exclusive. They can be generated one after another for a hierarchical list:

- Following a keystroke (in order):

	Event	Context
	On Data Change	Element was edited
	On Expand/On Collapse	Opening/Closing of a sublist using the -&gt; or <;-
		arrow keys
	On Selection Change	Selection of a new element
	On Clicked	Activation of the list using keyboard

- Following a mouse click (in order):

	Event	Context
	On Data Change	Element was edited
	On Expand/On Collapse	Opening/Closing of a sublist using the expand/collapse
		icons
		or
		Double-click on non-editable sublist
	On Selection Change	Selection of a new element
	On Clicked / On Double Clicked	Activation of the list using click or double-click

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 [Parents] table is displayed on the screen:

      ` Method of a form for the [Parents] table
   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 executed since it is in the same 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 highlight the object so the user
               ` knows the source data could be dropped onto it
            $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 DRAG AND DROP PROPERTIES command.

5. This example is a template for a form method. It shows each of the possible events that can occur when 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 DISPLAY SELECTION or MODIFY SELECTION commands. 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 Get edited text, Keystroke and FILTER KEYSTROKE commands.

8. This example shows how to treat clicks and double clicks in the same way in 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 (Focus 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 capitalized automatically"
                     ` ...
               : ($vlFieldNum=10) ` Zip Code field
                  vtStatusArea:="Enter a 5-digit zip code; it will be checked and validated automatically"
                     ` ...
            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 an input 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.