Methods on a Form

Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

Each form has a set of standard methods. You can override these methods to change the behavior of the form, respond to user interface events, and customize the appearance of a form.

To override a form method, expand the node for the form, right-click the Methods node, click Override Method, and then click the name of method that you want to override. Methods that have been customized appear in the Methods node. To view the code, double-click the method name.

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

There are also methods on each form data source and on each form control. For more information about these methods, 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. All the form methods are also members of the FormRun system class. 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.	Returns boolean data type that specifies whether a form has focus.
addHistory	The address bar history changed.	Adds an entry after the list of entries that appear when you click the travel history button.
blockPersonalization	A personalization change is made to the form.	Specifies whether you can open the personalization form. Set to true when the form has been personalized and the form has to be restarted before more changes can be accepted.
canClose	The form is closed.	Specifies whether you can close the form. The call to super in the method checks whether closing the form is a valid action. The canClose method is started by the closeCancel or the closeOK methods. Use this method to add your own checks that determine whether the form should close.
canSubmitToWorkflow	This method is invoked in updateWorkflowControls to determine when the Submit button and context message are to be displayed.	Use this method to determine whether the Submit button should be displayed. Caution To enable workflow, you MUST override this method as the base implementation always returns False.
close	The form is closed.	Closes a form. The call to super in this method closes the form window, manages database updates, and sets the closed method to true. The close method is started either by the closeCancel or the closeOK methods.
closeCancel	The user presses a Cancel button or the ESC key.	Stops a form from closing. 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.	Use this method to check whether the form has been closed by a cancel action. The method is set to true if the form is closed by a cancel action (Cancel button).
closedOk	Set by closeOK.	Use this method to check whether the form has been closed by the OK button. The method is set to true if an OK button was used to close the form.
closeOk	The user presses an OK button.	Specifies whether the form was closed by clicking the OK button. The call to the super method sets the Boolean flag closedOK, and calls the close method.
closeSelect	A lookup form is closed following the selection in the form.	Use this method to close the lookup form. The closeSelect method calls the closeOK method, and it is called before the close method is called.
closeSelectRecord	A lookup form is closed when a record is selected in the form.	Supports the use of a Reference control that is bound to and displays all of a record. Handles the close and select event for the lookup form.
controlMethodOverloadObject	Not called by the system.	Enables you to specify that a user interface event should trigger a method on an object instead of 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 instead of on the form. Note 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.	Use this method to complete a copy operation. If the user has selected multiple records, the copy operation is handled by the call to super in this method. If only one record has been selected, the copy method on the form calls the copy method on the form control.
createRecord	The user executes the New action for the form.	Enables you to respond to the creation of a new record. When the method executes, the create method is called on the specified data source.
cut	The user performs a cut operation on the form.	Use this method to call the cut method on the form control.
doApply	The user closes a modal window.	Use this method to follow-up on the closing of the modal window. Note 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.	Returns a cursor to the current data source record. 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.	Destructs the form object and releases the space allocated to it.
firstField	Focus moves to the first field on the form.	Use an integer to specify the field flag.
getActiveWorkflowConfiguration	Used by the updateWorkflowControls method to determine what controls to display.	Returns the active workflow configuration for the current document. The method returns the workflow configuration that was originally retrieved by the loadWorkflowConfiguration method.
getActiveWorkflowTrackingStatus	Used by the updateWorkflowControls method to determine what controls to display.	Returns the current workflow tracking status record to load with the workflow controls.
getActiveWorkflowWorkItem	Used by the updateWorkflowControls method to determine what controls to display.	Returns the active work item for the current document.
init	The form is opened.	Use the method to initialize a form. The init method is started immediately after the new method and creates the run-time image of the form. Typical uses of init include the following: Modifying a form by using the FormBuild system class Initializing variables for specific controls on the form. You must call the super method if you override this method, and you should add your code before the super call. In addition to creating the form, the call to the super method constructs the data source for the form by starting 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.
initWorkflowControls	During initialization of the form.	Adds the workflow controls to the form but leaves the controls disabled.
lastField	Focus moves to the last field on the form.	Override this method on a form to pass different bit-flag constants or to prevent the move to the last field group by preventing the call to the super method.
loadUserSetting	The user settings for a form are loaded.	Use this method when user settings are loaded.
loadWorkflowConfiguration	When a document is opened in a form.	Finds the workflow configuration for the current document. The method evaluates activation conditions for all workflow configurations associated with the document.
nextField	Focus moves to the next field, for example, when the user presses the TAB key.	Use this method to focus on the first visible, editable field in the form. When the nextField method is executed, the system checks the DataSource property on the container control to determine which table data should be displayed.
nextGroup	Focus moves to the next group of fields, for example, when the user presses SHIFT+TAB.	Use this method to check the DataSource property on the container control to determine which table data should be displayed.
paste	The user performs a paste operation (CTRL+V) on the form.	Use the paste method to call the corresponding method on the form control.
prevField	Focus moves to the previous field.	Use this method to check the DataSource property on the container control to determine which table data should be displayed.
prevGroup	Focus moves to the previous group of fields.	Use this method to check the DataSource property of the container control to determine which table data should be displayed.
print	When the user has a form open and starts the Print command on the File menu.	Use this method to generate a report based on the data source fields in the AutoReport field group. 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 and starts the Print Preview command from the File menu.	Use this method to view the automatic report for the active form. You can also call the printPreview method to initiate the view of the automatic report.
reload	Reserved for future use.	N/A
resize	The form opened and when it is resized.	Use this method to determine the new height and width of the form.
run	The form is opened.	Call the run method immediately after the init method. The call to the super method 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 the following: Activating or de-activating some fields Modifying the query You must call the super method if you override this method. You should add your code before the call to the super method.
saveUserSetting	When the form is closed after a user makes changes to the user settings.	Saves the user setting for the form.
selectControl	When the form is opened, or when the user selects a different control.	Use this method to determine the control that was selected.
send	When a change to the data in a form is submitted to the database.	Use this method to print an automatic report from the contents of the form.
setApply	Not started by the system.	Takes the object to be started 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.
skipSaveUserSetting	When you attempt to personalize a form.	Specifies whether the form saves user settings when it closes. If you personalize the form and a restart is required, additional personalization information is not saved when the form closes.
sysColorChanged	The form color is changed.	Use this method to determine when the form color is changed.
task	The user performs some task in a form by using the toolbar, the menu, or the keyboard.	Use the call to the super method to start the relevant method for the task. For example, if the user has started the TAB key, the nextField method is called.
updateWorkflowControls	Invoked by the formNotify method when the workflow data source changes. In addition, this method can be invoked when a work item is completed.	Refreshes the workflow controls, and determines what buttons and context messages must be displayed. The method inspects workflow configurations, work items for the current user, and then calls canSubmitToWorkflow or other methods.
wait	The system is waiting for a form to finish execution.	Use the wait after the form prompts the user for some input. 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.	Use this method for debugging. Use equal to discover whether the object supplied as a parameter is equal to the current object.
xml	Not activated by the system.	Use this method for debugging. Retrieves an object reference for the form as an XML string.

See also

FormRun Class

Form Classes

Announcements: New book: "Inside Microsoft Dynamics AX 2012 R3" now available. Get your copy at the MS Press Store.