Dialog statement - MapBasic - 2023

Purpose

Displays a custom dialog box.

Restrictions

You cannot issue a Dialog statement through the MapBasic window.

Syntax

Dialog 
	[ Title title ]
	[ Width w ] [ Height h ] [ Position x, y ] 
	[ Calling handler ] 
		Control control_clause
	[ Control control_clause... ] 

title is a string expression that appears in the title bar of the dialog box.

h specifies the height of the dialog box, in dialog box units (8 dialog box height units represent the height of one character).

w specifies the width of the dialog, in dialog units (4 dialog height units represent the width of one character).

x, y specifies the dialog box's initial position, in pixels, representing distance from the upper-left corner of MapInfo Pro's work area; if the Position clause is omitted, the dialog box appears centered.

handler is the name of a procedure to call before the user is allowed to use the dialog box; this procedure is typically used to issue Alter Control statements.

Each control_clause can specify one of the following types of controls:

• Button
• OKButton
• CancelButton
• EditText
• StaticText
• PopupMenu
• CheckBox
• MultiListBox
• GroupBox
• RadioGroup
• PenPickerm
• BrushPicker
• FontPicker
• SymbolPicker
• ListBox

See the separate discussions of those control types for more details (for example, for details on CheckBox controls, see Control CheckBox clause; for details on Picker controls, see Control PenPicker/BrushPicker/SymbolPicker/FontPicker clause; etc.).

Each control_clause can specify one of the following control types:

• Button / OKButton / CancelButton
• CheckBox
• GroupBox
• RadioGroup
• EditText
• StaticText
• PenPicker / BrushPicker / SymbolPicker / FontPicker
• ListBox / MultiListBox
• PopupMenu

Description

The Dialog statement creates a dialog box, displays it on the screen, and lets the user interact with it. The dialog box is modal; in other words, the user must dismiss the dialog box (for example, by clicking OK or Cancel) before doing anything else in MapInfo Pro. For an introduction to custom dialog boxes, see the MapBasic User Guide.

Anything that can appear on a dialog box is known as a control. Each dialog box must contain at least one control (for example, an OKButton control). Individual control clauses are discussed in separate entries (for example, see Control CheckBox clause for a discussion of check-box controls). As a general rule, every dialog box should include an OKButton control and/or a CancelButton control, so that the user has a way of dismissing the dialog box.

The Dialog statement lets you create a custom dialog box. If you want to display a standard dialog box (for example, the Open dialog box), use one of the following statements or functions: Ask( ) function, Note statement, ProgressBar statement, FileOpenDlg( ) function, FileSaveAsDlg( ) function, or GetSeamlessSheet( ) function).

For an introduction to the concepts behind MapBasic dialog boxes, see the MapBasic User Guide.

Sizes and Positions of Dialog Boxes and Dialog Box Controls

Within the Dialog statement, sizes and positions are stated in terms of dialog box units. A width of four dialog box units equals the width of one character, and a height of eight dialog box units equals the height of one character. Thus, if a dialog box control has a height of 40 and a width of 40, that control is roughly ten characters wide and 5 characters tall. Control positions are relative to the upper left corner of the dialog box. To place a control at the upper-left corner of a dialog box, use x- and y-coordinates of zero and zero.

The Position, Height, and Width clauses are all optional. If you omit these clauses, MapBasic places the controls at default positions in the dialog box, with subsequent control clauses appearing further down in the dialog box.

Terminating a Dialog Box

After a MapBasic program issues a Dialog statement, the user will continue interacting with the dialog box until one of four things happens:

• The user clicks the OKButton control (if the dialog box has one);
• The user clicks the CancelButton control (if the dialog box has one);
• The user clicks a control with a handler that issues a Dialog Remove statement; or
• The user otherwise dismisses the dialog box (for example, by pressing Esc on a dialog box that has a CancelButton).

To force a dialog box to remain on the screen after the user has clicked OK or Cancel, assign a handler procedure to the OKButton or CancelButton control and have that handler issue a Dialog Preserve statement.

Reading the User's Input

After a Dialog statement, call the CommandInfo( ) function to determine whether the user clicked OK or Cancel to dismiss the dialog box. If the user clicked OK, the following function call returns TRUE:

CommandInfo(CMD_INFO_DLG_OK)

There are two ways to read values entered by the user: Include Into clauses in the Dialog statement, or call the ReadControlValue( ) function from a handler procedure.

If a control specifies the Into clause, and if the user clicks the OKButton, MapInfo Pro stores the control's final value in a program variable.

To read a control's value from within a handler procedure, call the ReadControlValue( ) function.

Specifying Hotkeys for Controls

When a MapBasic application runs on MapInfo, dialog boxes can assign hotkeys to the various controls. A hotkey is a convenience allowing the user to choose a dialog box control by pressing key sequences rather than clicking with the mouse.

To specify a hotkey for a control, include the ampersand character (&) in the title for that control. Within the Title clause, the ampersand should appear immediately before the character which is to be used as a hotkey character. Thus, the following Button clause defines a button which the user can choose by pressing Alt+R:

Control Button
	Title "&Reset"

Although an ampersand appears within the Title clause, the final dialog box does not show the ampersand. If you need to display an ampersand character in a control (for example, if you want a button to read "Find & Replace"), include two successive ampersand characters in the Title clause:

Title "Find && Replace" 

If you position a StaticText control just before or above an EditText control, and you define the StaticText control with a hotkey designation, the user is able to jump to the EditText control by pressing the hotkey sequence.

Specifying the Tab Order

The user can press the Tab key to move the keyboard focus through the dialog box. The focus moves from control to control according to the dialog box's tab order.

Tab order is defined by the order of the Control clauses in the Dialog statement. When the focus is on the third control, pressing Tab moves the focus to the fourth control, etc. If you want to change the tab order, change the order of the Control clauses.

Examples

The following example creates a simple dialog box with an EditText control. In this example, none of the Control clauses use the optional Position clause; therefore, MapBasic places each control in a default position.

Dialog
	Title "Search" 
	Control StaticText
		Title "Enter string to find:" 
	Control EditText 
		Value gs_searchfor 'this is a Global String variable
		Into gs_searchfor
	Control OKButton
	Control CancelButton 
If CommandInfo(CMD_INFO_DLG_OK) Then 
	' ...then the user clicked OK, and the variable
	' gs_searchfor contains the text the user entered. 
End If 

The following program demonstrates the syntax of all of MapBasic's control types.

Include "mapbasic.def"
Declare Sub reset_sub `resets dialog to default settings
Declare Sub ok_sub ' notes values when user clicks OK.
Declare Sub Main
Sub Main 
	Dim s_title As String 'the title of the map
	Dim l_showlegend As Logical 'TRUE means include legend
	Dim i_details As SmallInt '1 = full details; 2 = partial
	Dim i_quarter As SmallInt '1=1st qrtr, etc. 
	Dim i_scope As SmallInt '1=Town;2=County; etc.
	Dim sym_variable As Symbol 

	Dialog 
	Title "Map Franchise Locations" 

	Control StaticText 
		Title "Enter Map Title:"
		Position 5, 10

	Control EditText
		Value "New Franchises, FY 95" 
		Into s_title 
		ID 1 
		Position 65, 8 Width 90 
	Control GroupBox 
		Title "Level of Detail" 
		Position 5, 30 Width 70 Height 40 

	Control RadioGroup
		Title "&Full Details;&Partial Details" 
		Value 2 
		Into i_details 
		ID 2 
		Position 12, 42 Width 60 

	Control StaticText 
		Title "Show Franchises As:" Position 95, 30
	Control SymbolPicker
		Position 95, 45 
		Into sym_variable 
		ID 3 

	Control StaticText 
		Title "Show Results For:" 
		Position 5, 80 
	Control ListBox 
		Title "First Qrtr;2nd Qrtr;3rd Qrtr;4th Qrtr" 
		Value 4 
		Into i_quarter
		ID 4 
		Position 5, 90 Width 65 Height 35 
	Control StaticText 
		Title "Include Map Layers:" 
		Position 95, 80 
	Control MultiListBox 
		Title "Streets;Highways;Towns;Counties;States"
		Value 3
		ID 5 
		Position 95, 90 Width 65 Height 35 
	Control StaticText 
		Title "Scope of Map:" 
		Position 5, 130 
	Control PopupMenu 
		Title "Town;County;Territory;Entire State" 
		Value 2 
		Into i_scope 
		ID 6 
		Position 5, 140 
	Control CheckBox 
		Title "Include &Legend" 
		Into l_showlegend 
		ID 7
		Position 95, 140
	Control Button
		Title "&Reset" 
		Calling reset_sub 
		Position 10, 165 
	Control OKButton 
		Position 65, 165 
		Calling ok_sub 

	Control CancelButton 
		Position 120, 165 
	If CommandInfo(CMD_INFO_DLG_OK) Then
		' ... then the user clicked OK. 
	Else 
		' ... then the user clicked Cancel. 
	End If 
End Sub 
Sub reset_sub
	' here, you could use Alter Control statements
	' to reset the controls to their original state. 
End Sub
Sub ok_sub
	' Here, place code to handle user clicking OK
End Sub

The preceding program produces the following dialog box.

See Also: