Previous

Next

Interaction methods

Completed

When you write code in application language (AL), you might want to interact with the user at certain moments. You can ask the user for a confirmation, provide some extra information, or let the user make a choice.

To accomplish these tasks, you can use the following interaction functions:

• Message

• Confirm

• StrMenu

• Error

You can use several specialized methods to display messages and gather input. We recommend that you use pages to ensure that your application has a consistent user interface. However, there are situations where you may want to use the dialog methods instead of pages. The most important uses of the dialog methods are as follows:

• To display a window that indicates the progress of some processing that may take a long time.

• To stop the running program to display an error message.

• To let the user confirm a choice before the program continues running.

You can also use the StrMenu method to create pages that present options to the user. It's much faster to use this method than to design a page, which only presents a limited set of options to the user.

Best practices for user messages

We recommend the following guidelines for writing messages for end users:

• Write messages correctly according to the grammatical rules for your language.

• Don't use backslashes to indicate line breaks in a message. Line formatting is completed automatically. The only exception is in the Open Method). You must use backslashes for the message to be aligned correctly.

• Use the FieldCaption() Method and TableCaption() Method whenever possible to return names of fields and tables as strings. This is important so that the user can always recognize a term that indicates a field or table name. The only exception to this is in Open Method) where you can use the field name directly. Otherwise, it can be difficult to align correctly. If you refer to a field name without using the FieldCaption) method, then type the field name without any single or double quotation marks.

• Try to write all messages on only one line. If you want to use more than one line, then start a new line after a period instead of in the middle of a sentence.

• Don't enter the text directly in the AL code. Instead, enter it as a label so that the message can be translated.

Message method

The Message function is used frequently in Business Central, and it's used to communicate information to the user. By using the Message function, you can notify your user that a certain process has finished or shows the output of an expression.

Message(string [,Value1, ...]);

Message('Hello World');

If your string contains placeholders, they can be replaced with the values that follow the string.

var
    MyInt: Integer;
    TheValueOfTxt: Label 'The value of %1 is %2';
begin
    MyInt := 5;
    Message(TheValueOfTxt, 'MyInt', MyInt);
    // Displays: The value of MyInt is 5
end;

The Message method runs asynchronously, which means that the message isn't run until the method from which it was called ends or another method requests user input. The method is useful for notifying the user that some processing has been successfully completed.

Confirm method

When you want to run only certain parts of your code after a confirmation from the user, use the Confirm function. You can use the Confirm function based on a string, which is generated from the question that you ask the user. The message is displayed with a Yes and a No button.

You can select which button should get the focus when the window appears. This rule can be set with the second parameter. If your string contains placeholders, they can be replaced with values from other parameters.

Ok := Dialog.Confirm(string [,Default] [,Value1, ...]);

The Confirm function can be used in combination with an if statement.

if Confirm('Are you sure you want to delete?') then
   Message('OK')
else
   Message('Not OK');

If you want the No button to have the default focus, add false as a parameter.

if Confirm('Are you sure you want to delete?', false) then
   Message('OK')
else
   Message('Not Ok');

StrMenu method

The StrMenu function can be used to ask people for information and provide them with a selection of choices.

OptionNumber := StrMenu(OptionString [,DefaultNumber] [,Instruction]);

The following example shows the StrMenu function being used.

var
   Days: Text[50];
   Selection: Integer;
begin
   Days := 'Monday,Tuesday,Wednesday,Thursday,Friday';
   Selection := StrMenu(Days, 1, 'Which day is today ?');
   Message('You selected %1.', Selection);
end;

If the user selects Wednesday, the system will display: You selected 3.

Error method

If something goes wrong, or certain conditions aren't met while you are processing code, you can use the Error message to notify the user. After the Error message, code will stop running.

Error(String [,Value1, ...]);

For example, the following code will generate three messages to the user: 1, 2, and an OOPS! error message. After the error message, the system stops running code. The fourth message with the text 3 is never displayed.

MESSAGE('1');
MESSAGE('2');
ERROR('OOPS !');
MESSAGE('3');

The Error Method) is similar to the Message method except that when the user has acknowledged the message from an Error method, execution ends. The Error method is also similar to the FieldError method. For more information, see CalcFields, CalcSums, FieldError, FieldName, Init, TestField, and Validate Methods.

Continue