A number representing the current day, month, year, hour, minute, second, and hundredths of a second is returned if the corresponding parameter is not used. If an error occurs, the enumeration value of Error! is returned.
Parameters
Day: numeric (optional) A number representing a day of the week.
Month: enumeration or numeric (optional) One of the following enumerations, or a number representing a month (number in brackets).
January! [1]
February! [2]
March! [3]
April! [4]
May! [5]
June! [6]
July! [7]
August! [8]
September! [9]
October! [10]
November! [11]
December! [12]
Year: numeric (optional) A number representing a year. Example: 2007
Hour: numeric (optional) A number representing an hour.
Minutes: numeric (optional) A number representing a minute.
Seconds: numeric (optional) A number representing a second.
Hundredths: numeric (optional) A number representing hundredths of a second.
numeric := DateDay
Example
Syntax
([Date: numeric])
Description
Return a numeric value representing a day of the month.
Example
vDay := DateDay()
Messagebox (x; "Day of the Month"; vDay)
Result (current system day): 17
Return Value
Check for an error (illegal date) by comparing the return value to DateAndTime.Error!.
Parameters
Date: numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
numeric := DateDayOfYear
Syntax
([Date: numeric])
Description
Return the number of a day in the year.
Return Value
Number of the day in the year specified by the Date parameter. An error returns DateAndTime.Error!.
Parameters
Date: numeric (optional) Date for which to return the number of the day.
Note
* To pass a specific date and time, use the DateAndTime function.
*
numeric := DateDaysInMonth
Syntax
([Month: enumeration or numeric]; [Year: numeric])
Description
Return the number of days in a specified month.
Return Value
Number of days in a specified month (takes Leap year into account). An error returns DateAndTime.Error!.
Parameters
Month: enumeration or numeric (optional) Month for which to return the number of days. If missing, the current month is used. You can also specify a numeric value to represent the month. For example, 1 for January, 2 for February, and so on.
January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Year: numeric (optional) Year in which to return the number of days in the specified month. If missing, the current year is used.
Note
* To pass a specific date and time, use the DateAndTime function.
*
numeric := DateDaysInYear
Syntax
([Year: numeric])
Description
Return the number of days in a specified year.
Return Value
Number of calendar days in a specified year. An error returns DateAndTime.Error!.
Parameters
Year: numeric (optional) Year for which to return the number of calendar days. If missing, the current year is used. Leap years are taken into consideration.
boolean := DateIsLeapYear
Syntax
([Year: numeric])
Description
Determine whether a specified year is a leap year.
Return Value
True if leap year, False if not.
Parameters
Year: numeric (optional) Year to check for leap year. If missing, the current year is used.
Note
* A year that is evenly divisible by 4 is a leap year. The only exception is a century year (for example, 1600), which is a leap year only if it is evenly divisible by 400.
*
enumeration or numeric := DateMonth
Example
Syntax
([Date: numeric])
Description
Return an enumeration representing the month.
Example
// Assume the current month is February
vMonth := DateMonth()
MessageBox (x; "Month"; vMonth)
Result (current system month): 2 or February!
Return Value
Check for an error (illegal date) by comparing the return value to DateMonth.Error! or DateAndTime.Error!.
January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Error!
Parameters
Date: numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
string := DateMonthName
Syntax
([Date: numeric]; [Type: enumeration])
Description
Return the name of a month.
Examples
vDate := DateAndTime (1; 12; 1996)
vMonth := DateMonthName (vDate)
MessageBox (x; "Month"; vMonth)
Result: December
vDate := DateAndTime (1; 12; 1996)
vMonth := DateMonthName (vDate; Short!)
MessageBox (x; "Month"; vMonth)
Result: Dec
Return Value
An empty string ("") is returned for an illegal date.
Parameters
Date: numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
Type: enumeration (optional) Default: Long!
Short! Month is abbreviated.
Long! Month is spelled out.
numeric := DateOfMonthEnd
Syntax
([Month: enumeration or numeric]; [Year: numeric])
Description
Return the date for the end of a specified month.
Return Value
Date for the end of a specified month. An error returns DateAndTime.Error!.
Parameters
Month: enumeration or numeric (optional) Month for which to return the end-of-month date. If missing, the current month is used. You can also use numbers to specify the month. For example, 1 for January, 2 for February, and so on.
January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Years: numeric (optional) Year in which to return the end-of-month date for Month. If missing, the current year is used.
numeric := DateOfNthDay
Syntax
(Nth: numeric; [Year: numeric])
Description
Return the date for a specified day in a year.
Return Value
Date of a specified day number. An error returns DateAndTime.Error!.
Parameters
Nth: numeric Day number for which to return the date.
Year: numeric (optional) Year in which to return the date of a specified day. If missing, the current year is used.
Date of a specified week number. An error returns DateAndTime.Error!.
Parameters
Nth: numeric Week number for which to return the date.
Year: numeric (optional) Year in which to return the date of a specified week. If missing, the current year is used.
FirstDayOfWeek: enumeration (optional) Day of the week for the date to return. If missing, Sunday! is used.
Sunday!
Monday!
Tuesday!
Wednesday!
Thursday!
Friday!
Saturday!
numeric := DateOfNthWeekDay
Syntax
(Nth: enumeration or numeric; DayOfWeek: enumeration; [Month: enumeration]; [Year: numeric])
Description
Return the date for a specified weekday in a specified month.
Return Value
Date of the nth weekday in a specified month. An error returns DateAndTime.Error!.
Parameters
Nth: enumeration or numeric Number of the weekday in a specified month and year. Numeric values range from 1 to 5, or use one of the following enumerations:
First! Return the date of the first specified weekday.
Last! Return the date of the last specified weekday.
DayOfWeek: enumeration Day of the week to return.
Sunday!
Monday!
Tuesday!
Wednesday!
Thursday!
Friday!
Saturday!
Month: enumeration (optional) Month for which to return the date of a specified weekday. If missing, the current month is used.
January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Year: numeric (optional) Year for which to return the date of a specified weekday. If missing, the current year is used.
An empty string ("") is returned for an illegal date.
Parameters
Date: numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
Type: enumeration (optional) If missing, Short! is used.
Short! Date represented as digits.
Long! Date spelled out.
Custom! The format as specified by the Format parameter
Format: string (optional) Specify a date string format. If missing, the current system format from the Windows Control Panel is used. See the example above for use; see the table below for details.
String Codes
Day (month) d (digits without leading zeros for single-digit days)
dd (digits with leading zeros for single-digit days)
Day (week) ddd (three-letter abbreviation)
dddd (day of the week)
Month M (digits without leading zeros for single-digit months)
MM (digits with leading zeros for single-digit months)
MMM (three-letter abbreviation)
MMMM (month spelled out)
Year y (last digit only)
yy (last two digits)
yyyy (four digits)
Period/Era gg (ignored if era string is not associated)
enumeration := DateWeekday
Syntax
([Date: numeric])
Description
Return an enumeration representing the day of the week.
Check for an error (illegal date) by comparing the return value to DateWeekday.Error! or DateAndTime.Error!.
Sunday!
Monday!
Tuesday!
Wednesday!
Thursday!
Friday!
Saturday!
Error!
Parameters
Date: numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
date := DatePart
Syntax
([Date: date])
Description
Remove the time from the specified date, returning a date with only the date part in it. The time portion of the date/time value returned will be cleared, which is interpreted as midnight.
Return Value
The date portion of the specified date.
Parameters
Date:
date The date to return the date part of. If missing, the current date is used.
string := DateWeekdayName
Syntax
([Date: numeric]; [Type: enumeration])
Description
Return the name of a day of the week.
Example
vDate := DateAndTime (17; 2; 1996)
vWeekday := DateWeekdayName (vDate; Short!)
MessageBox (x; "Weekday"; vWeekday)
Result: Sat
Return Value
An empty string ("") is returned for an illegal date.
Parameters
Date: numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
See the server application's documentation for command names and syntax.
Return Value
If DDEExecute is unsuccessful, it returns an enumeration value of Error!. Otherwise, it returns the transaction ID.
Error! The command was not successful
Parameters
ConversationID: numeric A number that links the server and client applications. DDEInitiate returns ConversationID.
Command: string A command to execute.
TimeOut: numeric Asynchronous DDE: Set TimeOut to 0 or a negative value. DDE returns immediately, and notifies the macro that the command was delivered. When the server application acknowledges receiving the command, DDE notifies the macro and the macro calls Label. The return value is invalid for asynchronous DDE, because the server application has not yet processed the command.
Synchronous DDE: Set TimeOut to a positive integer, which specifies the maximum number of milliseconds to wait while the server application processes the command. The result is returned when the command is processed or DDE times out (command is not processed within the specified time). See Return Value above.
Label: label (optional) The Label to call when the server application acknowledges receiving the command (see the TimeOut parameter above). If the Label statement does not include Return, macro behavior is unpredictable.
numeric := DDEInitiate
Example
Syntax
(ServiceName: string; TopicName: string)
Description
Start a DDE conversation with a server application, and return a conversation ID.
A conversation must be started between server and client applications before you can use commands such as DDEPoke, DDERequest, and DDEExecute.
Return Value
A number that links the server and client applications is returned, or Error! if the conversation is not started. The return value returns an enumeration if the operation is not successful.
Parameters
ServiceName: string A DDE service name. See a server application's documentation.
"WPWin10_Macros (WordPerfect 10)
"WPWin9_Macros" (WordPerfect 9)
"WPWin8_Macros" (WordPerfect 8)
"Presentations" (Presentations 7)
"WPWin60_Macros" (WordPerfect 6.1)
TopicName: string A topic name. See the server application's documentation.
"Commands" (WordPerfect 10)
"Commands" (WordPerfect 9)
"Commands" (WordPerfect 8)
"Command" (Presentations)
"Commands" (WordPerfect 6.1)
DDEPoke
Example
Syntax
(ConversationID: numeric; ItemName: string; ItemData: string; [;TimeOut: numeric or enumeration])
Description
Assign data to an item in a server application. Check your server application documentation to see if it supports XTYP_POKE transactions. Many applications do not.
Parameters
ConversationID: numeric A number that links the server and client applications. DDEInitiate returns ConversationID.
ItemName: string A server application item. See the server application's documentation for item names.
ItemData: string The data to assign to a server application item.
TimeOut: numeric or enumeration [optional] Lets you specify the maximum amount of time, in milliseconds, to wait for the poke operation to complete.
Standard! Wait 18000 milliseconds.
NoTimeOut! Use the maximum timeout value possible (approximately 24.8 days).
string := DDERequest
Example
Syntax
(ConversationID: numeric; ItemName: string [;TimeOut: numeric or enumeration])
Description
Get the contents of a server application item. Check your server application documentation to see if it supports XTYP_REQUEST transactions. Many applications do not.
Return Value
Contents of the server application item specified by ItemName.
Parameters
ConversationID: numeric A number that links the server and client applications. DDEInitiate returns ConversationID.
ItemName: string The name of a server application item.
Timeout: numeric or enumeration [optional] Lets you specify the maximum amount of time, in milliseconds, to wait for the poke operation to complete.
Standard! Wait 18000 milliseconds.
NoTimeOut! Use the maximum timeout value possible (approximately 24.8 days).
DDETerminate
Example
Syntax
([ConversationID: numeric])
Description
End a DDE conversation with a server application.
Parameter
ConversationID: numeric [optional] A number that links the server and client applications. DDEInitiate returns ConversationID.
Note
* If you omit the ConversationID parameter, then DDETerminate terminates all conversations.
*
DDETerminateAll
Example
Syntax
()
Description
End all DDE conversations.
Declare
Example
Syntax
({<VariableName> variable := <Value> any})
Description
Create a local variable or array, which stores as many variables, constants, or expressions as memory allows.
An array can have up to 10 dimensions, and up to 32,767 elements per dimension depending on the amount of available memory. In the following example, Declare creates ArrayA with 10 elements and ArrayB with five elements. An element in each array is assigned a value. Parentheses are optional.
Examples
Declare(ArrayA[10]; ArrayB[5])
ArrayA[3] := "John"
Explanation: Assigns "John" to the third element in ArrayA.
ArrayB[5] := ArrayA[3]
Explanation: Assigns "John" to the fifth element in ArrayB.
In the next example, Declare creates a two-dimensional array (ArrayC) with 100 elements (10 rows and 10 columns). One element is assigned a value.
Declare ArrayC[10;10]
ArrayC[2;3] := 3+6
Explanation: Assigns 9 to the element at row 2, column 3.
Parameters
<VariableName> variable The name of a local variable or array. Use a semicolon to separate names when declaring more than one variable or array. If an array is declared, enclose the array indices in brackets. Use a semicolon to separate elements in a multi-dimensional array.
<Value> any (optional) The value assigned to <Variable> at the time of declaration. For example, Persist vTest = 20. vTest equals 20 at run time. If missing, the value of <Variable> is undefined.
Default
Example
Specify the code to execute when no CaseOF <Selector> matches the control expression in a Switch statement. See Switch.
enumeration := DefaultUnits
Example
Syntax
([Units: enumeration])
Description
Specify the default unit of measure, and return the previous unit of measure. You can set a new value, and then restore the previous value.
Examples
In the first example, Advance uses the default unit of measure (WPUnits!). In the second, Advance overrides the default unit of measure and uses inches. In the third, DefaultUnits specifies centimeters as the default unit of measure.
Advance(AdvanceFromTop!; 4)
Explanation: Advance insertion point 4 WPUnits.
Advance(AdvanceFromTop!; 4")
Explanation: Advance insertion point 4 inches.
DefaultUnits(Centimeters!)
Advance(AdvanceFromTop!; 4)
Explanation: Advance insertion point 4 centimeters.
The default unit of measure is effective until changed by another DefaultUnits command. If not specified by DefaultUnits, the default unit of measure is WPUnits!.
Discussion
None! has been added to the list of possible units. Normally, when a non-units value such as 1200 is combined with a units value such as 1.0C, the non-units value assumes the default unit type. If the default unit type is WPUnits,
1.0C + 1200 = 3.54C (1200 WPUnits = 2.54C)
If, however, the default unit is set to None!, the non-units value assumes the unit type of the value it is combined with (no conversion is performed). For example,
1.0C + 1200 = 1201.0C
With the default unit set to None!, 1200 assumes the unit type of centimeter.
Return Values
The previous unit value.
None!
Centimeters!
Inches!
Millimeters!
NoChange!
Points!
WPUnits!
Parameters
Units: enumeration (optional) The default unit of measure. If missing, the NoChange! is returned.
None!
Centimeters!
Inches!
Millimeters!
NoChange! (Return the current default units: new default units type is not changed.)
Points! (One Point equals 1/72 of an inch)
WPUnits! (One WordPerfect unit equals 1/1200 of an inch)
Add a bitmap control to a dialog box. After DialogLoad or DialogShow, bitmap controls can be added to a dialog created with the Dialog Editor.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. This same value is placed into the MacroDialogResult variable.
Parameters
Dialog: String The name or number of the dialog box to contain the bitmap control (see DialogDefine).
Control: string A name or number that identifies the bitmap control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the bitmap.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the bitmap.
Width: numeric (optional) The width of the bitmap control in dialog units.
Height: numeric (optional) The height of the bitmap control in dialog units.
Style: enumeration (optional) Lets you specify how to display the bitmap and the style of the bitmap control. New enumerations have been added that cause the same behavior that was specified by leaving this parameter off in previous versions. If this parameter is missing, NoResize! | Opaque! is used.
NoResize! (Don't resize the bitmap to fit the control and don't resize the control to fit the bitmap.)
Opaque! (The background is drawn with an opaque background, rather than transparent.)
SizeCtlToBmp!
SizeBmpToCtl!
Transparent!
FileName: string The path and filename of a bitmap file, or resource file such as a .dll. If "" or "0", and the Name parameter are missing, no bitmap is loaded and the bitmap control is cleared to nothing. If the Name parameter is missing, the Filename parameter is the name of the bitmap (bmp) file loaded from disk. Otherwise, the Filename parameter is the name of a .dll file that contains a bitmap resource to load. If the Filename parameter is "" or "0", the PFIT90EN.dll file is used. If the Filename parameter is a number other than "0", it is the instance handle of a previously loaded .dll. If the specified bitmap is not found, a special bitmap is displayed to indicate an error.
Name: string (optional) Specify a bitmap in a resource file such as "#1". If the Name parameter begins with "#", the reaminder is assumed to be an integer which is the resource id of the bitmap to load. Otherwise, the Name parameter is the resource name of the bitmap to load. I fthe specified bitmap is not found, a special bitmap is displayed to indicate an error.
TransparentColor: enueration (optional) Any color between 0 and 16,777,215 (0 is black). Colors are based on RGB colors. If the Style parameter is Transparent!, this parameter defines what color is to be used as the transparent color. The parameter may be specified as a numeric value of the colors specified as an RGB value, with the red component value of 0 to 255 in bits 0-7, the green component value of 0 to 255 in bits 8-15, and the blue component value of 0 to 255 in bits 16-23 (and 0 in bits 24-31) or a predefined enumeration may be specified that defines the RGB value of some predefined colors.
Add a check box control to a dialog box. After DialogLoad or DialogShow, a check box can be added to a dialog created with the Dialog Editor.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the check box control (see DialogDefine).
Control: string A name or number that identifies the check box control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the check box.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the check box.
Width: numeric (optional) The width of the check box control in dialog units.
Height: numeric (optional) The height of the check box control in dialog units.
Text: string The text displayed to the right of the check box, unless TextOnLeft! style is used. See Style below.
MacroVar: variable 1 is returned in this variable when the check box is checked, and 0 when it is not checked. The default value is 0. If MacroVar is assigned a value greater than 0 before the check box is added, the check box is checked when the dialog box is displayed.
Style: enumeration (optional) Specifies the style of the checkbox to add. If this is missing, then CheckboxAuto! | TextOnRight! is used. Checkbox styles are mutually exclusive (choose only one).
CheckboxAuto! Toggles between check and clear.
Checkbox! Can be one of two states: check or clear. See RegionSetCheck.
Checkbox3State! Can be one of three states: check, clear, or gray. See RegionSetCheck.
CheckboxAuto3State! Toggles between check, clear, and gray.
TextOnLeft! Positions text to the left of the check box.
TextOnRight! Positions text to the right of the check box.
Add a color wheel control to a dialog box, and return a number that represents the selected color when the dialog is dismissed. After DialogShow or DialogLoad, a color wheel can be added to a dialog created with the Dialog Editor.
The color selection consists of three color elements (red, green, and blue), separated into color values by the formula given below (see the MacroVar parameter below). These values are used in Windows programming to specify the color of a pen or brush.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. This same value is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the color wheel control (see DialogDefine).
Control: string A name or number that identifies the color wheel control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the color wheel control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the color wheel control.
Width: numeric (optional) The width of the color wheel control in dialog units.
Height: numeric (optional) The height of the color wheel control in dialog units.
MacroVar: variable A number corresponding to a color selection is returned in this variable. This number can be divided into three other numbers which correspond to red, green, and blue. The formulas are:
vRed := MacroVar % 256 (vRed contains the red component, which is the remainder of MacroVar divided by 256)
vGreen := MacroVar / 256 % 256 (vGreen contains the green component, which is the remainder of MacroVar divided by 256 divided by 256)
vBlue := MacroVar / 256 / 256 (vBlue contains the blue component, which is the result of MacroVar divided by 256 divided by 256)
Preselect a color by assigning its value to MacroVar before adding the color wheel control.
Add a combo box control to a dialog box. After DialogShow or DialogLoad, a combo box can be added to a dialog created with the Dialog Editor.
The combo box displays an edit box and a list box. You enter text in the edit box, or double-click a list item to insert it. Use DialogAddListItem to create list box items.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Example
Sort! | Simple!
Explanation: Name search allowed on a sorted list box. A vertical scrollbar automatically appears when needed.
Return Value
Name of the item added to the combo box control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the combo box control (see DialogDefine).
Control: string A name or number that identifies the combo box control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the combo box.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the combo box.
Width: numeric (optional) The width of the combo box control in dialog units.
Height: numeric (optional) The height of the combo box control in dialog units.
Style: enumeration (optional) Specifies the style of the combo box to add. If missing, then Sorted! Is used. The first three styles are exclusive (choose only one). Type | between enumerations to combine styles.
Dropdown! Display an edit control. Clicking the arrow to the right of the edit control displays a drop-down list box.
Droplist! Display a read-only edit control. Clicking the arrow to the right of the edit control displays a drop-down list box.
Simple! Display an edit control and an opened drop-down list box.
Unsorted! Items are not sorted.
Sorted! Items are sorted alphabetically. If Sorted! is used by itself, Simple! Is the default combo box style. This is the same as the obsolete enumeration Sort! See DialogAddListItem.
WPChars! Non-keyboard characters allowed in a list item. See DialogAddListItem.
AutoHScroll! Automatic horizontal scrolling.
OEMConvert! Convert ANSI to OEM character set.
MacroVar: variable The selected combo box item is returned in this variable. An item can be assigned to MacroVar before the control is added to a dialog.
LimitText: numeric (optional) The maximum number of characters the edit control accepts, up to the number of characters that fit in the edit box. This number has no effect if you choose style DropList!.
Add a custom control to a dialog box. After DialogShow or DialogLoad, a custom control can be added to a dialog created with the Dialog Editor.
The macro system knows nothing about custom controls. The user is responsible for all control message processing and queries.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control added to the dialog box if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the custom control (see DialogDefine).
Control: string A name or number that identifies the custom control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the custom control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the custom control.
Width: numeric (optional) The width of the custom control in dialog units.
Height: numeric (optional) The height of the custom control in dialog units.
Class: string The name of the control class. Standard Windows classes include Button, ComboBox, Edit, ListBox, ScrollBar, and Static. Other controls such as Meters and Spin buttons must be defined in a DLL (see the Instance parameter below).
Style: numeric (optional) A number that defines a valid style within the control Window class. For example, an edit control includes styles such as left, multiline, and password. The values for standard Windows styles are in the Windows SDK. If missing, no style bits are specified for this control.
WindowName: string The control text. For example, the text that appears on a button control. Set this value to "" if the control does not accept text.
MacroVar: variable (optional) The value returned by a control. This variable is retained for backward compatibility. You must query the control to retrieve needed values.
Instance: numeric (optional) This parameter is retained for backward compatibility. If the DLL is loaded, the macro should be able to locate the control.
Add a counter control to a dialog box. After DialogShow or DialogLoad, a counter can be added to a dialog created with the Dialog Editor.
Click the counter button to insert a number in the edit box that is within a specified range (see the CountMin and CountMax parameters below).
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. This same value is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the counter control (see DialogDefine).
Control: string A name or number that identifies the counter control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the counter control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the counter control.
Width: numeric (optional) The width of the counter control in dialog units.
Height: numeric (optional) The height of the counter control in dialog units.
Format: enumeration (optional) Specify counters of various unit values. When a value is entered without a unit of measure (24 instead of 24i), the value assumes the specified counter unit (not the default unit type). Use only one of the following enumerations.
DisplayNormal! (-2147483647 to 2147483647)
DisplayWPU! (-2147483647 to 2147483647)
DisplayPoints! (-4294967.0 to 4294966.0)
DisplayCentimeters! (-151518.0 to 151519.0)
DisplayFixedPoint! (-32767.0 to 32767.0)
DisplayPercent! (-2147483647 to 2147483647)
DisplayInches! (-59651.0 to 59652.0)
DisplayInches2! (-59651.0 to 59652.0)
DisplayMillimeters! (-1515513.0 to 1515514.0)
DisplayI_Inches (-59651.0 to 59652.0)
You can use any combination of the following enumerations with any of the above enumerations.
AutoHScroll!
NoScroll!
AutoValidate!
Type | between enumerations to combine enumerations.
MacroVar: variable The selected counter number is returned in this variable. A number can be assigned to MacroVar before the dialog is displayed.
CountMin: any (optional) The minimum number that you can insert by clicking the counter button. The range of values for CountMin is between -32767.0 to 32767.0
CountMax: any (optional) The maximum number that you can insert by clicking the counter button. The range of values for CountMax is between -32767.0 to 32767.0
CountStep: any (optional) The increment and decrement step value. Out-of-range values are replaced by the minimum or maximum values.
Add a date to a dialog box. After DialogShow or DialogLoad, a date can be added to a dialog created with the Dialog Editor.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Date added to the dialog box if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the date control (see DialogDefine).
Control: string A name or number that identifies the date control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the date.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the date.
Width: numeric (optional) The width of the date control in dialog units.
Height: numeric (optional) The height of the date control in dialog units.
Style: enumeration (optional) Determine whether the date is valid.
NoValidate! The contents of the edit field in the date control will not be validated, and will accept any string.
Validate! Validate the contents of the edit field in the date control for a valid date.
MacroVar: variable The initial value when the control is displayed, and the value of the control when the dialog is dismissed.
Year: numeric (optional) The number representing the year.
Month: enumeration (optional) January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Day: numeric (optional) The number representing the day.
Add an edit control to a dialog box. After DialogShow, an edit box can be added to a dialog created with the Dialog Editor.
The text entered in the edit box is returned in MacroVar when the dialog is dismissed (see MacroVar parameter).
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the edit control (see DialogDefine).
Control: string A name or number that identifies the edit control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the edit control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the edit control.
Width: numeric (optional) The width of the edit control in dialog units.
Height: numeric (optional) The height of the edit control in dialog units.
Style: enumeration (optional) The edit control styles. Type | between enumerations to combine styles. Not all combinations are possible.
Left! Text is left justified.
Right! Text is right justified if Multiline! style is set and WPChars! style is not set.
Center! Text is centered if Multiline! style is set and WPChars! style is not set.
VScroll! Edit control with a vertical scroll bar. Use with Multiline!
HScroll! Edit control with a horizontal scroll bar. Use with Multiline! or WPChars!.
WPChars! Can display WP Character box (press Ctrl+W). Non-keyboard characters are allowed.
Multiline! Multiple lines of input automatically wrap to the next line. Press Enter to cause the default button action (see DialogAddPushButton). If Enter2Hrtn! style is set in DialogDefine, press Enter to move the insertion point to the next line.
Uppercase! Text is automatically converted to uppercase.
Lowercase! Text is automatically converted to lowercase.
Password! Text is automatically displayed with asterisk (*) characters. The actual characters are stored by the edit control.
WordWrap! Text wraps if Multiline! is set.
SoftRet! Text contains Soft Return codes [SRt].
Attributes! Underline (press Ctrl+U) and italics (press Ctrl+I) are allowed if WPChars! Style is set.
NoTabs! Tab codes are not exported with output.
NoWPChar! Cannot display WP Character dialog box. Non-keyboard characters are not allowed.
AutoVScroll! Automatic vertical scrolling.
AutoHScroll! Automatic horizontal scrolling.
OEMConvert! Convert ANSI to OEM character set.
ReadOnly! Edit control is read only.
WantReturn! Pressing Enter produces a hard return. Use with Multiline!.
MacroVar: variable The text entered in the edit box is returned in this variable. Text can be assigned to MacroVar before the dialog is displayed.
LimitText: numeric The maximum number of characters the edit control accepts.
Add a filename edit control to a dialog box. After DialogShow or DialogLoad, a filename box can be added to a dialog created with the Dialog Editor.
The filename edit control consists of an edit control and a button control. Clicking the button displays the Select Directory or Select File dialog box depending on the control style (see the Style parameter).
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the filename edit control (see DialogDefine).
Control: string A name or number that identifies the filename edit control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the filename edit control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the filename edit control.
Width: numeric (optional) The width of the filename edit control in dialog units.
Height: numeric (optional) The height of the filename edit control in dialog units.
Style: enumeration (optional) The filename edit control styles. Default: FilesAndDirs!. Type | between enumerations to combine styles.
FilesAndDirs! Directories and filenames are allowed.
DirOnly! Only directories are allowed.
FileDoesntHaveToExist!
MacroVar: variable The directory or filename entered in the edit box is returned in this variable. A name can be assigned to MacroVar before the macro is displayed.
DefaultDir: string (optional) The default directory when the Select File dialog box is displayed.
Template: string (optional) The filenames to display in the Select File dialog box. For example, "*.*" (all files) and "*.bat" (all batch files).
Add a frame to a dialog box. After DialogShow or DialogLoad, a frame can be added to a dialog created with the Dialog Editor.
You can combine frame styles by creating two frames the same size and at the same position. For example, you can create a black frame and a white-filled frame (see the Control and Style parameters). You can also create custom controls by combining frames and QuickSpots (see DialogAddHotSpot and DialogShow).
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Examples
Frame! | White!
Explanation: White frame is displayed.
Filled! | White!
Explanation: White-filled frame is displayed.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the frame control (see DialogDefine).
Control: string A name or number that identifies the frame control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the frame control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the frame control.
Width: numeric (optional) The width of the frame control in dialog units.
Height: numeric (optional) The height of the frame control in dialog units.
Style: enumeration (optional) The frame styles. Type | between enumerations to combine styles. Not all combinations are possible.
Frame! Frame only.
Black! Black frame.
Gray! Gray frame. Gray is the default DeskTop color of the Windows Default color scheme. To select a different color, choose Colors in the Windows Control Panel.
Draw a rectangle around related dialog controls such as buttons. After DialogShow or DialogLoad, a group box can be added to a dialog created with the Dialog Editor.
Grouping related controls helps narrow user options.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the group box control (see DialogDefine).
Control: string A name or number that identifies the group box control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the group box control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the group box control.
Width: numeric (optional) The width of the group box control in dialog units.
Height: numeric (optional) The height of the group box control in dialog units.
Title: string The title displayed at the top-left corner.
Add a horizontal line to a dialog box. After DialogShow or DialogLoad, a horizontal line can be added to a dialog created with the Dialog Editor.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the horizontal line control (see DialogDefine).
Control: string A name or number that identifies the horizontal line control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the horizontal line control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the horizontal line control.
Length: numeric (optional) The length of the horizontal line control in dialog units.
Create an invisible area (QuickSpot) in a dialog box that closes the dialog box when clicked. After DialogShow or DialogLoad, a QuickSpot can be added to a dialog created with the Dialog Editor.
Other responses are possible when you use DialogAddHotSpot with a callback function (see DialogShow).
To create a QuickSpot within a frame (see DialogAddFrame), overlap size and position parameters.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the QuickSpot control (see DialogDefine).
Control: string A name or number that identifies the QuickSpot control (the "Named region" of a control created with the Dialog Editor). The Control value is returned in the implicit variable MacroDialogResult (see DialogAddPushButton or DialogDefine) if the user chooses the QuickSpot to dismiss the dialog box.
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the QuickSpot control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the QuickSpot control.
Width: numeric (optional) The width of the QuickSpot control in dialog units.
Height: numeric (optional) The height of the QuickSpot control in dialog units.
Style: enumeration (optional) The QuickSpot styles.
Add an icon to a dialog box. After DialogShow or DialogLoad, an icon can be added to a dialog created with the Dialog Editor.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the icon control (see DialogDefine).
Control: string A name or number that identifies the icon control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the icon control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the icon control.
Width: numeric (optional) The width of the icon control in dialog units.
Height: numeric (optional) The height of the icon control in dialog units.
IconName: string The name of an icon in a DLL. If an icon is identified by a number, precede the number with a pound sign (#). For example, "#160". If "" or "0" is used, no icon is loaded and the icon control are cleared to nothing. Otherwise, the IconName parameter identifies an icon resource in a .dll file to be loaded. If the IconName parameter begins with "#", the remainder is assumed to be an integer which is the resource name of a icon to load. If the specified icon is not found, a special icon is displayed to indicate an error.
Instance: numeric (optional) The instance handle of the DLL that contains the icon resource to load. The PerfectFit default is 0. DLLLoad returns the handle in a variable. If the Instance parameter is missing "" or "0", the PFIT90EN.dll file is used.
Add a list box control to a dialog box. After DialogShow or DialogLoad, a list box can be added to a dialog created with the Dialog Editor.
The item you choose is returned in MacroVar (see the MacroVar parameter). Use DialogAddListItem to create list box items.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Examples
Sort! | NameSearch!
Explanation: Name search is allowed on a sorted list box. A vertical scrollbar automatically appears when needed.
Sort! | NameSearch! | MultiColumn!
Explanation: Name search is allowed on a sorted list box. Items automatically roll in other columns as needed. A horizontal scrollbar automatically appears when needed.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the list box control (see DialogDefine).
Control: string A name or number that identifies the list box control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the list box control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the list box control.
Width: numeric (optional) The width of the list box control in dialog units.
Height: numeric (optional) The height of the list box control in dialog units.
Style: enumeration (optional) The list box control styles. Type | between enumerations to combine styles.
UseTabStops! Specifies that the listbox supports tab stops.
Unsorted! Items are listed in the order in which they are defined. Type a keyboard character to give the input focus to the first item that begins with that character. A vertical scrollbar automatically appears when needed. See DialogAddListItem.
Sorted! Default. Items are sorted alphabetically. Type a keyboard character to give the input focus to the first item that begins with that character. See DialogAddListItem.
NameSearch! Item search is allowed. Begin typing the name of an item to select. An edit control is displayed above the list box, and the input focus is given to the item that most closely matches the characters you type.
MultiColumn! Items automatically roll into other columns as needed. A horizontal scrollbar automatically appears when needed. Column width is set by Windows.
WPChars! Non-keyboard characters are allowed in a list item. See DialogAddListItem.
ExtendedSelection! Click an item, press shift key and select another item. Selects all items in between.
MultipleSelection! Click items to select or deselect.
Checkboxes! List the box items have check boxes. Use with WPChars!.
MacroVar: variable The selected list box item is returned in this variable. An item can be assigned to MacroVar before the dialog is displayed. The item is highlighted (selected) if it exists in the control's list of items. Otherwise, it is ignored.
numeric := DialogAddListItem
Example
Syntax
(Dialog: string; Control: string; {Item: string})
Description
Creates a list item(s) for DialogAddComboBox and DialogAddListBox. After DialogShow, a list item(s) can be added to a list box in a dialog created with the Dialog Editor.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Index (position) where the item was added to the list if successful, or -1 if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the list item (see DialogDefine).
Control: string The name or number of the control to contain the list item (the "Named region" of a control created with the Dialog Editor).
Item: string (repeating) One or more list items separated by a semicolon. Use the NToC programming command to include non-keyboard characters in a list item for DialogAddComboBox and DialogAddListBox, when the WPChars! style is set. For example,
Add a progress indicator to a dialog box. After DialogShow or DialogLoad, a progress indicator control can be added to a dialog created with the Dialog Editor. See RegionSetProgressPercent.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the progress indicator control (see DialogDefine6109).
Control: string A name or number that identifies the progress indicator control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the progress indicator.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the progress indicator.
Width: numeric (optional) The width of the progress indicator in dialog units.
Height: numeric (optional) The height of the progress indicator in dialog units.
Add a push button to a dialog box. After DialogShow or DialogLoad, a push button can be added to a dialog created with the Dialog Editor.
When you choose a user-defined push button or QuickSpot, the Control parameter value of the button or QuickSpot is returned in the implicit variable MacroDialogResult (see DialogDefine). Other controls return the following Control parameter values: 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4 or Esc.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string A name or number that matches the Dialog parameter of the dialog box to contain the push-button control (see DialogDefine).
Control: string A name or number that identifies the push-button control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the push-button control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the push-button control.
Width: numeric (optional) The width of the push-button control in dialog units.
Height: numeric (optional) The height of the push button control in dialog units.
Style: enumeration (optional) The push button styles.
NonDefaultBttn! Create a push button.
DefaultBttn! Create a default push button, with a heavy black border, that dismisses the dialog box. Press Enter to choose the default button. If Enter2HRtn! style is specified in DialogDefine, pressing Enter in a multiline edit control produces a hard return rather than the default button action.
OKBttn! Create a push button with ID OK style.
CancelBttn! Create a push button with ID Cancel style.
HelpBttn! Create a Help push button.
ButtonText: string The text displayed on the push button.
Add a radio button to a dialog box. After DialogShow or DialogLoad, a radio button can be added to a dialog created with the Dialog Editor.
Radio buttons represent mutually exclusive choices. Selecting one radio button deselects another. Group them together by a control such as a group box or horizontal or vertical line. For multiple selections, see DialogAddCheckBox.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the radio-button control (see DialogDefine).
Control: string A name or number that identifies the radio-button control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the radio-button control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the radio-button control.
Width: numeric (optional) The width of the radio-button control in dialog units.
Height: numeric (optional) The height of the radio-button control in dialog units.
ButtonText: string The text displayed by the radio button (see Styles).
MacroVar: variable 1 is returned in this variable if the radio button is selected, 0 if not. The default value is 0. If MacroVar is assigned a value greater than 0 before the macro compiles, the radio button is automatically selected.
Style: enumeration (optional) Radio! Button is not checked. Use RegionSetCheck in a callback function to check or uncheck. See DialogShow.
RadioAuto! Normal radio button.
RadioLeft! Positions text to the left of the radio button.
Adds a horizontal or vertical scroll bar to a dialog box. After DialogShow or DialogLoad, a scroll bar can be added to a dialog created with the Dialog Editor.
A callback function (see DialogShow) can receive Windows WM_HSCROLL and WM_VSCROLL messages from DialogAddScrollBar.
For more information, refer to your Windows 95 documentation.
Examples
Left! | VScroll!
Explanation: Creates a standard-size vertical scroll control on the left side of the window defined by Left, Top, Width, and Height.
Right! | HScroll!
Explanation: Creates a standard-size vertical scroll control on the right side of the window defined by Left, Top, Width, and Height.
VScroll!
A vertical scroll control that occupies the entire window defined by Left, Top, Width, and Height.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name that identifies the scroll bar control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
The runtime behavior of the scrollbar has changed. For macro dialogs created with the DialogDefine statement, the Step parameter was begin ignored and set to 1. This value is now used.
Parameters
Dialog: string The name or number of the dialog box to contain the scroll bar control (see DialogDefine).
Control: string A name or number that identifies the scroll bar control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the scroll bar control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the scroll bar control.
Width: numeric (optional) The width of the scroll bar control in dialog units (0 for vertical scroll bar).
Height: numeric (optional) The height of the scroll bar control in dialog units (0 for horizontal scroll bar).
Style: enumeration (optional) The scroll bar thumb position and type styles. If missing, Top! | vScroll! is used. Type "|" between enumerations to combine styles. Not all combinations are possible. HScroll! works the same as VScroll!, but uses the Top! and Bottom! styles.
Left!
Top!
Right!
Bottom!
VScroll! Create a vertical scroll bar.
HScroll! Create a horizontal scroll bar.
MacroVar: variable The position of the thumb is returned in this variable. To pre-select a thumb position, initialize MacroVar to the desired position. Default: the minimum position.
Minimum: numeric (optional) The minimum thumb position (default). If the maximum position is 6 and the minimum position is 1, there are six positions on the scroll bar. If the maximum position is 6 and the minimum position is 2, there are five positions on the scroll bar.
Maximum: numeric (optional) The maximum thumb position. See the Minimum parameter.
Step: numeric (optional) The distance the scroll bar moves with each click.
Display a line of text in a dialog box. After DialogShow or DialogLoad, text can be added to a dialog created with the Dialog Editor.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Examples
Left! | RecessBox!
Explanation: Text is left justified in a recess box.
Center! | ShadowBox!
Explanation: Text is centered in a shadow box.
Return Value
Text added to the dialog box if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the text control (see DialogDefine).
Control: string A name or number that identifies the text control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the text control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the text control.
Width: numeric (optional) The width of the text control in dialog units. This parameter determines how much horizontal space the control occupies, not the text width which is fixed by the system.
Height: numeric (optional) The height of the text control in dialog units. This parameter determines how much vertical space the control occupies, not the text height which is fixed by the system.
Style: enumeration (optional) The text control styles. Type | between enumerations to combine styles. Not all combinations are possible.
Left! Left justified.
Right! Right justified unless WPChars! style is set.
Center! Centered inside Width parameter value unless WPChars! style is set.
RecessBox! Recessed background.
ShadowBox! Shadowed background.
WPChars! Non-keyboard characters are allowed. See the Text parameter.
Multiline! Text wraps if WPChars! is set.
Filename! Ellipsis truncate path and filename to the length of the Width parameter.
NoPrefix! The & character is not interpreted as an accelerator prefix (displays in the text).
Text: string The text to display on the dialog box. Use the NToC programming command to display a non-keyboard character. For example,
Add a window to a dialog box for viewing files. The contents of the specified file are displayed in the viewer.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the viewer control (see DialogDefine6109).
Control: string A name or number that identifies the viewer control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the viewer control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the viewer control.
Width: numeric (optional) The width of the viewer control in dialog units.
Height: numeric (optional) The height of the viewer control in dialog units.
Filename: string (optional) The path and name of a file to view.
Add a vertical line to a dialog box. After DialogShow or DialogLoad, a vertical line can be added to a dialog created with the Dialog Editor.
Note
With any of the DialogAdd commands, the user can use the same name for several controls. While this is possible, creating multiple controls with identical names will prevent the macro from properly accessing the controls at a later time, since the macro system cannot determine which control the user is referencing in the macro. (Using DialogHandle, the first such control is used, while the Region... commands will use the "last" control with that name.)
If the macro does not need to ever explicitly access one of these controls with the same name (i.e. several static text fields), they can be given the same name, instead of requiring each one to have a unique name.
Return Value
Name of the control if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string The name or number of the dialog box to contain the vertical line control (see DialogDefine6109).
Control: string A name or number that identifies the vertical line control (the "Named region" of a control created with the Dialog Editor).
Left: numeric (optional) The number of dialog units from the left side of the dialog box to the left side of the vertical line control.
Top: numeric (optional) The number of dialog units from the top of the dialog box to the top of the vertical line control.
Length: numeric (optional) The length of the vertical line in dialog units.
Get the value of a control, or of all controls in a dialog.
Return Value
True if successful, False if not.
Parameters
Dialog: string The name or number of the dialog box from which to get the value of a control or controls (see DialogDefine).
Control: string (optional) A name or number of a control. If missing, the value of all the associated variables are updated.
MacroVar: variable (optional) The value of Control is returned in this variable. This variable does not become the associated variable for the control. If missing, the control's associated variable is updated.
boolean := DialogControlUpdate
Syntax
(Dialog: string; [Control: string]; [Value: any])
Description
Update a dialog control or controls from a value.
Return Value
True if successful, False if not.
Parameters
Dialog: string The name or number of the dialog box in which to update a control (see DialogDefine).
Control: string (optional) The name or number of a control to update. If missing, all controls are updated from the variables associated with the controls when they were created.
Value: any (optional) Value used to update a control(s). If missing, Control is updated from the variable associated with it when it was created.
Assemble dialog data in memory. Use DialogShow to create and display the dialog box.
Dialog names are limited to 25 characters.
Dialog sizes do not include caption and border space (in Windows 95, dialog captions and borders can be sized by the user).
The value of the control that dismisses a dialog box is returned in an implicit variable named MacroDialogResult: 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4 or Esc. It also returns the value of the Control parameter of a user-defined push button or QuickSpot (see DialogAddPushButton, DialogAddHotSpot).
MacroDialogResult is replaced or destroyed when you close a dialog box or call DialogDestroy. To save its value, assign it to a variable. For example, vResult := MacroDialogResult.
Dialog boxes are positioned and sized in dialog units. A vertical unit equals 1/8 of the font height, and a horizontal unit equals 1/4 of the font width.
Example
OK! | Percent! | NoTitle!
Explanation: Creates a modal dialog box without a title, and positions it in the center of the screen.
Return Value
Name of the dialog if successful, an empty string ("") if not. The same result is placed into the MacroDialogResult variable.
Parameters
Dialog: string A name or number that identifies the dialog box. This name or number is used by DialogShow and by DIALOGADD commands.
Left: numeric The number of dialog units from the left side of the screen to the left side of the dialog box. When used with Percent! (see Style parameter), this number is a percentage of the screen width minus the width of the dialog box.
Top: numeric The number of dialog units from the top of the screen to the top of the dialog box. When used with Percent! (see the Style parameter), this number is a percentage of the screen height minus the height of the dialog box.
Width: numeric The width of the dialog box in dialog units.
Height: numeric The height of the dialog box in dialog units.
Style: enumeration The dialog box styles. Type | between enumerations to combine styles. Not all combinations are possible.
OK! Create an OK button.
Cancel! Create a Cancel button.
Percent! Set Top and Left parameters to a percentage of the screen width or height minus the width or height of the dialog box. Use 50 to display the dialog box in the center of the screen.
NoFrame! Create a dialog box without a frame. Style has no effect in Windows 95.
Sizeable! Resizing of the dialog box is allowed.
NoTitle! Remove the caption (title) bar.
Modeless! Dialog box can lose input focus without closing. The WordPerfect command InhibitInput must be Off!. Default is modal dialog box.
Enter2HRtn! Press Enter in a multiline edit control (see DialogAddEditBox) to move the insertion point to the next line. This does not cause the default button action (see DialogAddPushButton).
NoCloseBox!
Caption: string The text displayed in the caption (title) bar.
boolean := DialogDelete
Example
Syntax
(Dialog: string)
Description
Delete a (binary form) dialog from the prefix packet area of the current macro file.
Return Value
Return True if successful, False if not.
Parameters
Dialog: string Name of the dialog to delete (see DialogDefine).
boolean := DialogDestroy
Example
Syntax
(Dialog: string)
Description
Remove an old-style dialog box from memory.
Discussion
A dialog created with the Dialog Editor, without a callback (see DialogShow), is removed from memory when any button is pushed. Subsequent calls to the dialog create an error (the macro system no longer knows anything about the dialog). For example, DialogDismiss in
DialogShow ("Dialog1"; "PerfectScript")
DialogDismiss ("Dialog1"; "OKBttn")
creates an error when OK is pressed (Dialog1).
The next example, which includes a callback function, displays the dialog, continuously executes instructions (callback function "CallHere"), is dismissed (hidden), and is finally destroyed.
DialogShow ("Dialog1"; "PerfectScript"; CallHere)
DialogDismiss ("Dialog1"; "OKBttn")
DialogDestroy ("Dialog1")
Quit
Label (CallHere)
...other statements...
Return
Return Value
True if successful, False if not. This same value is placed in MacroDialogResult.
Parameters
Dialog: string The name or number of a dialog box to destroy (see DialogDefine).
string := DialogDismiss
Example
Syntax
(Dialog: string; Control: string)
Description
Hide a dialog box. Use DialogShow to display a hidden dialog box.
Discussion
A dialog created with the Dialog Editor, without a callback (see DialogShow), is removed from memory when any button is pushed. Subsequent calls to the dialog create an error (the macro system no longer knows anything about the dialog). For example, DialogDismiss in
DialogShow ("Dialog1"; "PerfectScript")
DialogDismiss ("Dialog1"; "OKBttn")
creates an error when OK is pressed (Dialog1).
The next example, which includes a callback function, displays the dialog, continuously executes instructions (callback function "CallHere"), is dismissed (hidden), and is finally destroyed.
DialogShow ("Dialog1"; "PerfectScript"; CallHere)
DialogDismiss ("Dialog1"; "OKBttn")
DialogDestroy ("Dialog1")
Quit
Label (CallHere)
...other statements...
Return
Return Value
Returns the name of the control that was used to dismiss the dialog.
Parameters
Dialog: string The name or number of the dialog box to hide (see DialogShow).
Control: string OKBttn or 1 for OK, CancelBttn or 2 for Cancel, or the control value of a user-defined push button or QuickSpot. CancelBttn cancels value assignments to control return variables. For example, an edit control does not return the text entered in the edit box. The value of Control is returned in MacroDialogResult as OKBttn, CancelBttn, or the control value of another push button or QuickSpot.
numeric := DialogHandle
Example
Syntax
(Dialog: string; [Control: string])
Description
Return the handle of a dialog or dialog box control.
Return Value
Handle of a dialog or dialog box control.
Parameters
Dialog: string The name or number of a dialog (see DialogDefine).
Control: string (optional) The name or number of a dialog box control (see Control parameter of any dialog control). If you omit this parameter, the handle of the dialog box is returned.
numeric := DialogLoad
Example
Syntax
(Dialog: string; [Parent: string])
Description
Load a dialog in memory without displaying it. You can use Region commands on a dialog box that has been loaded. See also DialogShow and Discussion under DialogDismiss.
Return Value
The window handle if successful, or 0 if not.
Parameters
Dialog: string The name or number of a dialog box (see DialogDefine).
Parent: string (optional) The name of the parent region, such as "Corel PerfectScript," or "WordPerfect" for WordPerfect.
boolean := DialogSave
Syntax
(Dialog: string; [SaveAsName: string])
Description
Save the specified dialog as a binary form dialog in the prefix packet area of the current macro file.
Return Value
True if saved successfully, False if not.
Parameters
Dialog: string The name of the dialog to save (see DialogDefine).
SaveAsName: string (optional) The name to save the dialog under. If missing, the dialog is saved under the current dialog name.
Dialog: string The name or number of a dialog box (see DialogDefine).
FontName: string (optional) The font that dialog text will appear in.
FontSize: measurement (optional) Specify the font size using a measurement type, such as 12p. If the measurement type specifier is not used, default units is assumed. See DefaultUnits.
ClassName: string (optional) Specify another class name (see Dialog Editor).
HelpFile: string (optional) The name of the Help file associated with the dialog.
HelpString: string (optional) The part of the Help file to come up along with the dialog.
Display a dialog box, and, optionally, identify a callback function. The parent of this dialog is maintained by the macro and is initially set to the application that started the macro. The dialog may be attached to a different application or window by setting a new default parent with the SetDefaultParent command.
Use DialogDismiss to hide a dialog box. See Discussion under DialogDismiss or DialogDestroy.
A callback function enables a macro to respond immediately and in specific ways to events such as selecting a radio button or check box, without waiting until the dialog box is dismissed. Without a callback function, user input is acted upon only after the dialog box is dismissed and the macro resumes execution.
To create a callback function, use the Label parameter of DialogShow, and a loop statement after DialogShow. For example,
DialogShow(1000; "WordPerfect"; Msgs)
CallbackWait
Label(Msgs)
... other statements ...
Return
The value of the control that dismisses a dialog box is returned in an implicit variable named MacroDialogResult: 1 for OK, 2 for Cancel, 2 for Close (system menu box), 2 if you double-click the system menu box, 2 if you press Alt+F4, or the value of the Control parameter of a user-defined push button or QuickSpot (see DialogAddPushButton, DialogAddHotSpot).
If DialogShow is used with Dialog commands, such as DialogDefine and DialogAddEditBox (old-style dialog box), the first control that can return a value has the input focus.
If a dialog is preloaded through DialogLoad or a Region command, the Parent parameter of DialogDefine is not used (the dialog is already created or "parented"). Before loading a dialog through a Region command, use DialogLoad to specify the parent.
Return Value
Returns the control name used to dismiss the dialog (for non-callback dialogs), or the window handle of the dialog (for callback dialogs). If DialogShow is used to display a callback dialog, the window handle of the dialog is returned (the same value placed into MacroDialogResult), and returned from DialogShow. If an error occurs, 0 is returned.
Parameters
Dialog: string The name of a dialog box to display (see DialogDefine for old-style dialog boxes).
Parent: string (optional) When displaying dialogs created by the Macro Dialog Editor, if no parent is specified, the same parent as used in a dialog defined by the DialogDefine statement without a parent. This parent defaults to the window of the application which starts the macro, but can be changed using the SetDefaultParent command
Callback: label (optional) Identify a callback function (Label to call) when the dialog box becomes active, or the user:
Chooses Close from the system menu.
Presses Alt+F4.
Double-clicks the system menu box.
Chooses a push button, radio button, check box, QuickSpot, or scroll-bar control.
The Windows messages are:
WM_ACTIVATE
WM_COMMAND
WM_DESTROY
WM_HSCROLL
WM_INITDIALOG
WM_SYSCOMMAND
WM_VSCROLL
For more information, see Callback Data Description.
Focus: string (optional) Specify the control to receive the initial focus.
Return dimension information about an array variable.
Return Value
Return the number of dimensions or elements, or the index range (see the IndexOption parameter).
Parameters
VariableName: variable Array variable name. Return dimension information about this variable.
IndexOption: enumeration (optional) Type of dimension information to return. If missing, DimensionCount! is used. Use 0 to return the total number of array elements. Use a dimension number to return the number of elements in that dimension (the numeric value 2 is equivalent to IndexLimit2!).
DimensionCount! Return the total number of dimensions in the array.
ElementCount! Return the total number of elements in the array.
IndexLimit1! Return the upper limit of the array's first index.
IndexLimit2! ... 9! Return the upper limit of a specified index (2 through 9).
IndexLimit10! Return the upper limit of the array's tenth index.
Discard
Example
Syntax
({VariableName: variable})
Description
Remove Local, Global, or Persist variables from memory, in that order.
Discard does not specify a variable table. If a variable by the same name exists in all three tables, call Discard three times.
While(Exists(VariableName))
Discard(VariableName)
EndWhile
Parameters
VariableName: variable (repeating) Variable(s) to discard. Variables begin with a letter and can include any other combination of letters or numbers. Separate multiple variables with a semicolon.
Do not use this command unless you are familiar with Windows programming. Incorrect DLL calls can damage files and/or reset your computer. Macros using DLLCalls written for Windows 3.x must be rewritten for Windows 95.
Parameters
<ModuleInstance> numeric A DLL handle. DLLLoad returns the handle in a variable.
<FunctionName> string A function name. See DLL documentation for function names.
<ReturnVariable> variable (optional) The DLL function may return a value in this variable. The ReturnType parameter defines the expected data type.
<ReturnType> enumeration The data type to return (see ReturnVariable parameter).
AnsiString! (Windows type LPSTR)
Bool! (Windows type BOOL)
DWord! (Windows type DWord)
Integer! (Windows type LONG)
OemString! (Windows type LPSTR)
Real! (Microsoft C type double)
String! (Windows type LPSTR)
Word! (Windows type WORD)
WPString! (WordPerfect wordstring)
Void! (Nothing)
ReturnType must match the data type returned in ReturnVariable (see DLL function documentation for return types). If it does not, an Unrecoverable Application Error or system crash may result.
<Parameter> any (optional) Parameter information passed to a DLL function, enclosed in braces and separated by a semicolon. The type of information depends on the function being called (see DLL function documentation for parameter values to pass).
integer (LONG or Dword)
string (FAR pointer to an ANSI string)
boolean (BOOL)
real (Microsoft c-type double)
AnsiString (string) (FAR pointer to an ANSI string)
OemString (string) (FAR pointer to an OEM string)
WPString (string) (FAR pointer to a WP 6.0 word string)
ADDRESS (integer) (LPDWord)
ADDRESS (Dword(integer))
ADDRESS (boolean) (BOOL FAR*)
ADDRESS (string) (FAR pointer to an ANSI string)
ADDRESS (AnsiString(string)) (FAR pointer to an ANSI string)
ADDRESS (OemString(string)) (FAR pointer to OEM string)
ADDRESS (WPString(string)) (FAR pointer to a WP 6.0 word string.)
ADDRESS (real) (FAR pointer to a Microsoft C-type double)
ADDRESS (Real (real)) (FAR pointer to a Microsoft C-type double)
Note
This command is not available for use on a Linux operating system.
DLLCall Prototype <Name> label
Syntax
(<ModuleFileName> string or variable; [<FunctionName> string]; <ReturnType> enumeration; {[<Parameter> any}])
Description
Define the calling format of a DLL routine (see example).
DLLCall Prototype must occur before calling a DLL function. The DLL library is loaded and freed each time the DLL function is called.
DLLCall Prototype makes a macro easier to read and provides safer DLL calls (routines can be called only as defined).
Do not use this command unless you are familiar with Windows programming. Incorrect DLL calls can damage files and/or reset your computer.
DLLCall is a compile-time only command that allows a variable name (simple variables only, no array elements are allowed), specified as the DllLibraryFile parameter as well as the literal character string that it supports. When a variable name is specified (see ModuleFileName parameter), the contents of the variable specified in the DLLCall Prototype statement is used, which must contain the name of the DLL library file. If the specified variable does not exist when the DLL routine is called, an undefined variable error occurs at runtime. This occurs when the DLL filename or instance handle is loaded in a local variable in a user-defined routine or macro file, and the DLL routine is called from a different file or different user-defined routine in which the variable does not exist. Define the variable containing the DLL name or instance handle as a Global macro variable, which makes it visible throughout the execution of the macro.
Parameters
<Name> label Name used to call the DLL function.
<ModuleFileName> string or variable DLL library file containing the DLL function, defined as a literal string, or as a variable that must contain the DLL library module name at runtime. If the variable contains an integer value, this value is assumed to be the instance handle of a DLL that was loaded using the DLLLoad command.
<FunctionName> string (optional) A function name. See DLL documentation for function names. If not used, the Name parameter is used.
<ReturnType> enumeration The data type returned by the DLL function. See DLLCall.
AnsiString!
Bool!
DWord!
Integer!
OemString!
Real!
String!
Word!
WPString!
Void!
<Parameter> any (optional) Parameter information passed to a DLL function, enclosed in braces and separated by a semicolon. The type of information depends on the function being called (see DLL function documentation for parameter values to pass). See DLLCall.
Note
This command is not available for use on a Linux operating system.
DLLFree
Syntax
(ModuleInstance: numeric)
Description
Remove a dynamic link library (DLL) from memory.
Do not use this command unless you are familiar with Windows programming. Incorrect DLL calls can damage files and/or reset your computer.
Parameters
ModuleInstance: numeric A DLL handle. DLLLoad returns the handle in a variable.
Note
This command is not available for use on a Linux operating system.
numeric := DLLLoad
Syntax
(Filename: string)
Description
Load a dynamic link library (DLL) into memory.
You should respond to error values with code similar to the following (see ModuleInstance parameter):
Result := DLLLoad(filename)
Switch(vResult)
CaseOF 0: ...statement block...
CaseOF 2: ...statement block...
EndSwitch
Do not use this command unless you are familiar with Windows programming. Incorrect DLL calls can damage files and/or reset your computer.
Return Value
A DLL handle if the DLL successfully loads, or an error value. For example, 31 means a General Failure occurred; 1157 means the DLL was not found.
See your Windows documentation for more information.
Parameters
Filename: string DLL path and filename.
Note
This command is not available for use on a Linux operating system.
boolean := DoesDialogExist
Example
Syntax
(Dialog: string)
Description
Look for a dialog in the current macro, then look through the Use file list for the current macro. See Use.
Return Value
True if the dialog is found, False if not.
Parameters
Dialog: string The name or number of a dialog box (see DialogDefine).
boolean := DoesDirectoryExist
Example
Syntax
(DirectoryName: string)
Description
Return True if a directory exists, False if not.
Return Value
True/False.
Parameters
DirectoryName: string Include the full path.
boolean := DoesFileExist
Example
Syntax
(Filename: string)
Description
Return True if a file exists, False if not.
Return Value
True/False.
Parameters
Filename: string Include the full path.
boolean := DoesRegionExist
Example
Syntax
(NamedRgn: string)
Description
Return whether a named region exists.
Return Value
True if the named region exists, False if not.
Parameters
NamedRgn: string Dialog ID and control ID, or Dialog ID and name of a named region. Enclose IDs in double quotation marks, separated by a period.
numeric := DWord
Syntax
(<Value> numeric)
Description
Pass a value as a DWord (DLL call in-line parameter function). DWord or double word is an unsigned long integer. See DLLCall.
