Methods on a Form

Each form has a set of standard methods. You can override these methods to alter the form's behavior when it opens, there are responses to user interface events, and so on.

To access these methods, expand the node for the form, right-click the Methods node, and then select Override Method.

You can define variables to be used in form methods by adding them to the classDeclaration method available in the Methods node for the form.

The methods are available on the FormRun system class.

Methods are also available on each form data source and on each form control. For more information, see Methods on a Form Data Source and Methods on Form Controls.

The following table lists the methods available for forms and explains when they are executed. For more information about each method, click the method name.

Note

Code written on forms cannot be re-used or inherited. If possible, write your code on the underlying table or in a class.


Method name

Executed when

Comments

activate

A form receives focus.

N/A

canClose

The form is closed.

The super() call checks whether it is a valid action to close the form.

canClose is activated by the closeCancel and by closeOK methods.

Use this method to add your own checks to the system's close verifications.

close

The form is closed.

The super() call closes the form window, manages database updates, and sets the closed method to true.

The close method is activated either by closeCancel or by closeOK.

closeCancel

The user presses a Cancel button or the ESC key.

The super() call sets the Boolean flag closedCancel, and calls the close method.

When a form is closed with closeCancel, user modifications are not saved.

closed

The form is closed.

Use this method to check whether the form has been closed.

closedCancel

Set by closeCancel.

This method is set to true if the form is closed by a cancel action (Cancel button or ESC key).

closedOk

Set by closeOK.

This method is set to true if an OK button was used to close the form.

closeOk

The user presses an OK button.

The super() call sets the Boolean flag closedOK, and calls the close method.

closeSelect

A lookup form is closed following the user's selection in the form.

The closeSelect method calls the closeOK method, and it is called before the close method is called.

controlMethodOverloadObject

Not called by the system.

This method allows you to specify that a user interface event should trigger a method on an object rather than on the form control. The object is specified in the parameter for the method. For example, you might want to call a clicked method on a class rather than on the form.

NoteNote
If you want to call an event method on the form, use the FormRun.controlMethodOverload method instead of the controlMethodOverloadObject method.

copy

The user performs a copy operation on the form.

If the user has selected multiple records, the copy operation is handled by the super() call in this method. If only one record has been selected, the copy method on the form calls the copy method on the form control.

cut

The user performs a cut operation on the form.

This method calls the cut method on the form control.

doApply

The user closes a modal window.

NoteNote
A modal window is a secondary window that requires the user to complete an interaction within it and to close it before continuing with any interaction outside the window.

docCursor

Not called by the system.

This method returns a cursor to the current record's data source. This is useful when a form has more than one data source.

Note   This method is used by the document management system.

finalize

The form is closed.

This method destructs the form object and releases the space allocated to it.

firstField

Focus moves to the first field on the form.

N/A

init

The form is opened.

init is activated immediately after new and creates the run-time image of the form.

Typical uses of init include:

  • Modifying a form by using the FormBuild system class

  • Initializing variables for specific controls on the form.

You must call super() if you override this method, and you should place your code before the super() call.

In addition to creating the form, the super() constructs the data source for the form by activating the init method on the data source. The form data source init method creates the query to fetch data from the database and sets up links if the form is linked to another form.

For more information about how to access the active query generated by the system, see How to: Access the Active Query on Forms.

lastField

Focus moves to the last field on the form.

N/A

loadUserSetting

The user settings for a form are loaded.

N/A

new

The form is opened.

new is the first method called when a form instance is created. For more information about the execution sequence of methods on a form, see Event Method Sequences in Form Scenarios.

NoteNote
When the new method is executed, the data source and form controls do not yet exist. If you need to add code to be executed when the form is opened, do so in the init method instead.

nextField

Focus moves to the next field, for example, when the user presses the TAB key.

When a form is opened, nextfield is activated to focus on the first visible, editable field.

When the nextField method is executed, the system checks the DataSource property on the control's container to ascertain which table data should be displayed.

nextGroup

Focus moves to the next group of fields, for example, when the user presses SHIFT+TAB.

When the nextGroup method is executed, the system checks the DataSource property on the control's container to ascertain which table data should be displayed.

paste

The user performs a paste operation (CTRL+V) on the form.

The paste method calls the corresponding method on the form control.

prevField

Focus moves to the previous field.

When the prevField method is executed, the system checks the DataSource property on the control's container to ascertain which table data should be displayed.

prevGroup

Focus moves to the previous group of fields.

When the prevGroup method is executed, the system checks the DataSource property on the control's container to ascertain which table data should be displayed.

print

When the user has a form open and activates the Print command on the File menu.

When a user selects Print on a form, a report based on the data source fields in the AutoReport field group is automatically generated. Add your own code to the print method if you want to change the layout of this report.

printPreview

When the user has a form open activates the Print Preview command on the File menu.

N/A

reload

Reserved for future use.

N/A

resize

The form opened and when it is resized.

N/A

run

The form is opened.

The run method is called immediately after the init method. The super() call makes the form window appear on the screen and performs a database search for the data to be displayed in the form.

Typical reasons for overriding this method include:

  • Activating or de-activating some fields

  • Modifying the query

You must call super() if you override this method, and you should place your code before the super() call.

saveUserSetting

When the form is closed after a user makes changes to the user settings.

N/A

selectControl

When the form is opened, or when the user selects a different control.

N/A

send

When a change to the data in a form is submitted to the database.

N/A

setApply

Not activated by the system.

Takes the object to be activated as a parameter. This is typically a form.

An apply() method must be present on the form or class and is called if a command button exists on the calling form.

TipTip
Run the tutorial class Tutorial_Apply, and then examine the code in the class and in the form of the same name.

sysColorChanged

The form color is changed.

N/A

task

The user performs some task in a form by using the toolbar, the menu, or the keyboard.

The super() call activates the relevant method for the task. For example, if the user has activated the TAB key, the nextField method is called.

wait

The system is waiting for a form to finish execution.

The most common use for wait is to launch a form that prompts the user for some input, and then call wait on that form. The next line of code will not be executed until the user either closes the form or presses Apply.

equal

Not activated by the system.

Used for debugging purposes.

Use equal to discover whether the object supplied as a parameter is equal to the current object.

toString

Not activated by the system.

Used for debugging purposes.

Retrieves the name of the form as a string.

xml

Not activated by the system.

Used for debugging purposes.

Retrieves an object reference for the form as an XML string.

See Also

FormRun Class

Form Classes