Desktop.Tile (method)
Chapter 2 DlgProc (function) 175 3 This action is sent when the content of a text box or combo box has been
changed. This action is only sent when the control loses focus. When this action is sent, ControlName$ contains the name of the text box or combo box, and SuppValue contains the length of the new content.
The dialog function's return value is ignored with this action.
4 This action is sent when a control gains the focus. When this action is sent, ControlName$ contains the name of the control gaining the focus, and SuppValue contains the index of the control that lost the focus (0-based).
The dialog function's return value is ignored with this action.
5 This action is sent continuously when the dialog box is idle. If the dialog
function returns 1 in response to this action, then the idle action will continue to be sent. If the dialog function returns 0, then WM Basic will not send any additional idle actions.
When the idle action is sent, ControlName$ contains a zero-length string, and SuppValue contains the number of times the idle action has been sent so far.
6 This action is sent when the dialog box is moved. The ControlName$ parameter contains a zero-length string, and SuppValue is 0.
The dialog function's return value is ignored with this action.
User-defined dialog boxes cannot be nested. In other words, the dialog function of one dialog box cannot create another user-defined dialog box. You can, however, invoke any built-in dialog box, such as MsgBox or InputBox$.
Within dialog functions, you can use the following additional WM Basic statements and functions. These statements allow you to manipulate the dialog box controls dynamically.
DlgVisible DlgText$ DlgText
DlgSetPicture DlgListBoxArray DlgFocus DlgEnable DlgControlId
For compatibility with previous versions of WM Basic, the dialog function can optionally be declared to return a Variant. When returning a variable, WM Basic will attempt to convert the variant to an Integer. If the returned variant cannot be converted to an Integer, then 0 is assumed to be returned from the dialog function.
Example 'This dialog function enables/disables a group of option buttons 'when a check box is clicked.
Function SampleDlgProc(ControlName$, Action%, SuppValue%) If Action% = 2 And ControlName$ = "Printing" Then
DlgEnable "PrintOptions",SuppValue%
SampleDlgProc = 1 'Don't close the dialog box.
End If End Function Sub Main()
Begin Dialog SampleDialogTemplate 34,39,106,45,"Sample",.SampleDlgProc
OKButton 4,4,40,14 CancelButton 4,24,40,14
CheckBox 56,8,38,8,"Printing",.Printing OptionGroup .PrintOptions
OptionButton 56,20,51,8,"Landscape",.Landscape OptionButton 56,32,40,8,"Portrait",.Portrait End Dialog
Dim SampleDialog As SampleDialogTemplate SampleDialog.Printing = 1
r% = Dialog(SampleDialog) End Sub
See Also Begin Dialog (statement).
Platform(s) Windows and Macintosh.
DlgSetPicture (statement)
Syntax DlgSetPicture {ControlName$ | ControlIndex},PictureName$,PictureType
Description Changes the content of the specified picture or picture button control.
Chapter 2 DlgSetPicture (statement) 177 Comments The DlgSetPicture statement accepts the following parameters:
Parameter Description
ControlName$ String containing the name of the .Identifier parameter associated with a control in the dialog box template. A case-insensitive comparison is used to locate the specified control within the template. Alternatively, by specifying the ControlIndex parameter, a control can be referred to using its index in the dialog box template (0 is the first control in the template, 1 is the second, and so on).
PictureName$ String containing the name of the picture. If PictureType is 0, then this parameter specifies the name of the file containing the image. If PictureType is 10, then PictureName$ specifies the name of the image within the resource of the picture library.
If PictureName$ is empty, then the current picture associated with the specified control will be deleted. Thus, a technique for conserving memory and resources would involve setting the picture to empty before hiding a picture control.
PictureType Integer specifying the source for the image. The following sources are supported:
0 The image is contained in a file on disk.
10 The image is contained in the picture library specified by the Begin Dialog statement.
When this type is used, the PictureName$
parameter must be specified with the Begin Dialog statement.
Examples DlgSetPicture "Picture1","\windows\checks.bmp",0 'Set picture from a file.
DlgSetPicture 27,"FaxReport",10 'Set control 10's image
'from a library.
See Also DlgControl (statement); DlgEnable (function); DlgEnable (statement);
DlgFocus (function); DlgFocus (statement); DlgListBoxArray (function);
DlgListBoxArray (statement); DlgText (statement); DlgText (function);
DlgValue (function); DlgValue (statement); DlgVisible (statement);
DlgVisible (function), Picture (statement), PictureButton (statement).
Platform(s) Windows and Macintosh.
Platform Notes:
Windows
Under Windows, picture controls can contain either bitmaps or WMFs (Windows metafiles). When extracting images from a picture library, WM Basic assumes that the resource type for metafiles is 256.
Picture libraries are implemented as DLLs on the Windows.
Platform Notes:
Macintosh
Picture controls on the Macintosh can contain only PICT images. These are contained in files of type PICT.
Picture libraries on the Macintosh are files with collections of named PICT resources. The PictureName$ parameter corresponds to the name of one the resources as it appears within the file.
DlgText (statement)
Syntax DlgText {ControlName$ | ControlIndex}, NewText$
Description Changes the text content of the specified control.
Comments The effect of this statement depends on the type of the specified control:
Control Type Effect of DlgText Picture Runtime error.
Option group Runtime error.
Drop list box Sets the current selection to the item matching NewText$. If an exact match cannot be found, the DlgText statement searches from the first item looking for an item that starts with NewText$. If no match is found, then the selection is removed.
OK button Sets the label of the control to NewText$.
Cancel button Sets the label of the control to NewText$.
Push button Sets the label of the control to NewText$.
List box Sets the current selection to the item matching NewText$. If an exact match cannot be found, the DlgText statement searches from the first item looking for an item that starts with NewText$. If no match is found, then the selection is removed.
Combo box Sets the content of the edit field of the combo box to NewText$.
Text Sets the label of the control to NewText$.
Text box Sets the content of the text box to NewText$.
Group box Sets the label of the control to NewText$.
Option button Sets the label of the control to NewText$.
The ControlName$ parameter contains the name of the .Identifier parameter associated with a control in the dialog box template. A case-insensitive comparison is used to locate the specific control within the template.
Alternatively, by specifying the ControlIndex parameter, a control can be referred to using its index in the dialog box template (0 is the first control in the template, 1 is the second, and so on).
Chapter 2 DlgText$ (function) 179 Example DlgText "GroupBox1","Save Options" 'Change text of group box 1.
If DlgText$(9) = "Save Options" Then
DlgText 9,"Editing Options" 'Change text to "Editing Options".
End If
See Also DlgControl (statement); DlgEnable (function); DlgEnable (statement);
DlgFocus (function); DlgFocus (statement); DlgListBoxArray (function);
DlgListBoxArray (statement); DlgSetPicture (statement); DlgText
(function); DlgValue (function); DlgValue (statement); DlgVisible
(statement); DlgVisible (function).
Platform(s) Windows and Macintosh.
DlgText$ (function)
Syntax DlgText$(ControlName$ | ControlIndex)
Description Returns the text content of the specified control.
Comments The text returned depends on the type of the specified control:
Control Type Value Returned by DlgText$
Picture No value is returned. A runtime error occurs.
Option group No value is returned. A runtime error occurs.
Drop list box Returns the currently selected item. A zero-length string is returned if no item is currently selected.
OK button Returns the label of the control.
Cancel button Returns the label of the control.
Push button Returns the label of the control.
List box Returns the currently selected item. A zero-length string is returned if no item is currently selected.
Combo box Returns the content of the edit field portion of the combo box.
Text Returns the label of the control.
Text box Returns the content of the control.
Group box Returns the label of the control.
Option button Returns the label of the control.
The ControlName$ parameter contains the name of the .Identifier parameter associated with a control in the dialog box template. A case-insensitive comparison is used to locate the specific control within the template.
Alternatively, by specifying the ControlIndex parameter, a control can be referred to using its index in the dialog box template (0 is the first control in the template, 1 is the second, and so on).
Example MsgBox DlgText$(10) 'Display the text in the tenth control.
If DlgText$("SaveOptions") = "EditingOptions" Then
MsgBox "You are currently viewing the editing options."
End If
See Also DlgControl (statement); DlgEnable (function); DlgEnable (statement);
DlgFocus (function); DlgFocus (statement); DlgListBoxArray (function);
DlgListBoxArray (statement); DlgSetPicture (statement); DlgText
(statement); DlgValue (function); DlgValue (statement); DlgVisible
(statement); DlgVisible (function).
Platform(s) Windows and Macintosh.
DlgValue (function)
Syntax DlgValue(ControlName$ | ControlIndex)
Description Returns an Integer indicating the value of the specified control.
Comments The value of any given control depends on its type, according to the following table:
Control Type DlgValue Returns
Option group The index of the selected option button within the group (0 is the first option button, 1 is the second, and so on).
List box The index of the selected item.
Drop list box The index of the selected item.
Check box 1 if the check box is checked; 0 otherwise.
A runtime error is generated if DlgValue is used with controls other than those listed in the above table.
The ControlName$ parameter contains the name of the .Identifier parameter associated with a control in the dialog box template. Alternatively, by specifying the ControlIndex parameter, a control can be referred to using its index in the dialog box template (0 is the first control in the template, 1 is the second, and so on).
Example
See DlgValue (statement).
Chapter 2 DlgValue (statement) 181 See Also DlgControl (statement); DlgEnable (function); DlgEnable (statement);
DlgFocus (function); DlgFocus (statement); DlgListBoxArray (function);
DlgListBoxArray (statement); DlgSetPicture (statement); DlgText
(statement); DlgText (function); DlgValue (statement); DlgVisible
(statement); DlgVisible (function).
Platform(s) Windows and Macintosh.
DlgValue (statement)
Syntax DlgValue {ControlName$ | ControlIndex},Value
Description Changes the value of the given control.
Comments The value of any given control is an Integer and depends on its type, according to the following table:
Control Type Description of Value
Option group The index of the new selected option button within the group (0 is the first option button, 1 is the second, and so on).
List box The index of the new selected item.
Drop list box The index of the new selected item.
Check box 1 if the check box is to be checked; 0 if the check is to be removed.
A runtime error is generated if DlgValue is used with controls other than those listed in the above table.
The ControlName$ parameter contains the name of the .Identifier parameter associated with a control in the dialog box template. A case-insensitive comparison is used to locate the specific control within the template.
Alternatively, by specifying the ControlIndex parameter, a control can be referred to using its index in the dialog box template (0 is the first control in the template, 1 is the second, and so on).
Example 'This code fragment toggles the value of a check box.
If DlgValue("MyCheckBox") = 1 Then DlgValue "MyCheckBox",0
Else
DlgValue "MyCheckBox",1 End If
See Also DlgControl (statement); DlgEnable (function); DlgEnable (statement);
DlgFocus (function); DlgFocus (statement); DlgListBoxArray (function);
DlgListBoxArray (statement); DlgSetPicture (statement); DlgText
(statement); DlgText (function); DlgValue (function); DlgVisible
(statement); DlgVisible (function).
Platform(s) Windows and Macintosh.
DlgVisible (function)
Syntax DlgVisible(ControlName$ | ControlIndex)
Description Returns True if the specified control is visible; returns False otherwise.
The ControlName$ parameter contains the name of the .Identifier parameter associated with a control in the dialog box template. Alternatively, by specifying the ControlIndex parameter, a control can be referred to using its index in the template (0 is the first control in the template, 1 is the second, and so on).
A runtime error is generated if DlgVisible is called with no user dialog is active.
Example If DlgVisible("Portrait") Then Beep If DlgVisible(10) And DlgVisible(12) Then
MsgBox "The 10th and 12th controls are visible."
End If
See Also DlgControl (statement); DlgEnable (function); DlgEnable (statement);
DlgFocus (function); DlgFocus (statement); DlgListBoxArray (function);
DlgListBoxArray (statement); DlgSetPicture (statement); DlgText
(statement); DlgText (function); DlgValue (function); DlgValue (statement);
DlgVisible (function).
Platform(s) Windows and Macintosh.
DlgVisible (statement)
Syntax DlgVisible {ControlName$ | ControlIndex} [,isOn]
Description Hides or shows the specified control.
Comments Hidden controls cannot be seen in the dialog box and cannot receive the focus using Tab.
The isOn parameter is an Integer specifying the new state of the control. It can be any of the following values:
1 The control is shown.
0 The control is hidden.
Omitted Toggles the visibility of the control.
Option buttons can be manipulated individually (by specifying an individual option button) or as a group (by specifying the name of the option group).
Chapter 2 DlgVisible (statement) 183 The ControlName$ parameter contains the name of the .Identifier parameter associated with a control in the dialog box template. A case-insensitive comparison is used to locate the specific control within the template.
Alternatively, by specifying the ControlIndex parameter, a control can be referred to using its index in the dialog box template (0 is the first control in the template, 1 is the second, and so on).
Picture Caching
When the dialog box is first created and before it is shown, WM Basic calls the dialog function with action set to 1. At this time, no pictures have been loaded into the picture controls contained in the dialog box template. After control returns from the dialog function and before the dialog box is shown, WM Basic will load the pictures of all visible picture controls. Thus, it is possible for the dialog function to hide certain picture controls, which prevents the associated pictures from being loaded and causes the dialog box to load faster. When a picture control is made visible for the first time, the associated picture will then be loaded.
Example 'This example creates a dialog box with two panels. The DlgVisible 'statement is used to show or hide the controls of the different 'panels.
Sub EnableGroup(start%, finish%)
For i = 6 To 13 'Disable all options.
DlgVisible i, False Next i
For i = start% To finish% 'Enable only the right ones.
DlgVisible i, True Next i
End Sub
Function DlgProc(ControlName$, Action%, SuppValue%) If Action% = 1 Then
DlgValue "WhichOptions",0 'Set to save options.
EnableGroup 6, 8 'Enable the save options.
End If
If Action% = 2 And ControlName$ = "SaveOptions" Then EnableGroup 6, 8 'Enable the save options.
DlgProc = 1 'Don't close the dialog box.
End If
If Action% = 2 And ControlName$ = "EditingOptions" Then
EnableGroup 9, 13 'Enable the editing options.
DlgProc = 1 'Don't close the dialog box.
End If End Function Sub Main()
Begin Dialog OptionsTemplate 33, 33, 171, 134, "Options", .DlgProc 'Background (controls 0-5)
GroupBox 8, 40, 152, 84, ""
OptionGroup .WhichOptions
OptionButton 8, 8, 59, 8, "Save Options",.SaveOptions
OptionButton 8, 20, 65, 8, "Editing Options",.EditingOptions OKButton 116, 7, 44, 14
CancelButton 116, 24, 44, 14 'Save options (controls 6-8)
CheckBox 20, 56, 88, 8, "Always create backup",.CheckBox1 CheckBox 20, 68, 65, 8, "Automatic save",.CheckBox2 CheckBox 20, 80, 70, 8, "Allow overwriting",.CheckBox3 'Editing options (controls 9-13)
CheckBox 20, 56, 65, 8, "Overtype mode",.OvertypeMode CheckBox 20, 68, 69, 8, "Uppercase only",.UppercaseOnly CheckBox 20, 80, 105, 8, "Automatically check
syntax",.AutoCheckSyntax
CheckBox 20, 92, 73, 8, "Full line selection",.FullLineSelection CheckBox 20, 104, 102, 8, "Typing replaces
selection",.TypingReplacesText End Dialog
Dim OptionsDialog As OptionsTemplate Dialog OptionsDialog
End Sub
Chapter 2 Do...Loop (statement) 185 See Also DlgControl (statement); DlgEnable (function); DlgEnable (statement);
DlgFocus (function); DlgFocus (statement); DlgListBoxArray (function);
DlgListBoxArray (statement); DlgSetPicture (statement); DlgText
(statement); DlgText (function); DlgValue (function); DlgValue (statement);
DlgVisible (statement).
Platform(s) Windows and Macintosh.
Do...Loop (statement)
Syntax 1 Do {While | Until} condition statements Loop
Syntax 2 Do
statements
Loop {While | Until} condition
Syntax 3 Do
statements Loop
Description Repeats a block of WM Basic statements while a condition is True or until a condition is True.
Comments If the {While | Until} conditional clause is not specified, then the loop repeats the statements forever (or until WM Basic encounters an Exit Do statement).
The condition parameter specifies any Boolean expression.
Examples Sub Main()
'This first example uses the Do...While statement, which performs 'the iteration, then checks the condition, and repeats if the 'condition is True.
Dim a$(100) i% = -1 Do
i% = i% + 1 If i% = 0 Then
a(i%) = Dir$("*") Else
a(i%) = Dir$
End If
Loop While (a(i%) <> "" And i% <= 99) r% = SelectBox(i% & " files found",,a)
'This second example uses the Do While...Loop, which checks the 'condition and then repeats if the condition is True.
Dim a$(100)
r% = SelectBox(i% & " files found",,a)
'This third example uses the Do Until...Loop, which does the 'iteration and then checks the condition and repeats if the 'condition is True.
r% = SelectBox(i% & " files found",,a)
'This last example uses the Do...Until Loop, which performs the 'iteration first, checks the condition, and repeats if the 'condition is True. r% = SelectBox(i% & " files found",,a) End Sub
See Also For...Next (statement); While ...WEnd (statement).
Platform(s) Windows and Macintosh.
Platform Notes:
Windows
Due to errors in program logic, you can inadvertently create infinite loops in your code. Under Windows, you can break out of infinite loops using
Ctrl+Break.
Platform Notes:
Macintosh
Due to errors in program logic, you can inadvertently create infinite loops in your code. On the Macintosh, you can break out of infinite loops using Command+Period.
Chapter 2 DoEvents (function) 187
DoEvents (function)
Syntax DoEvents[()]
Description Yields control to other applications, returning an Integer 0.
Comments This statement yields control to the operating system, allowing other applications to process mouse, keyboard, and other messages.
If a SendKeys statement is active, this statement waits until all the keys in the queue have been processed.
Example See DoEvents (statement).
See Also DoEvents (statement).
Platform(s) Windows and Macintosh.
DoEvents (statement)
Syntax DoEvents
Description Yields control to other applications.
Comments This statement yields control to the operating system, allowing other applications to process mouse, keyboard, and other messages.
If a SendKeys statement is active, this statement waits until all the keys in the queue have been processed.
Examples 'This first example shows a script that takes a long time and hogs the 'system. The subroutine explicitly yields to allow other applications 'to execute.
Sub Main()
Open "test.txt" For Output As #1 For i = 1 To 10000
Print #1,"This is a test of the system and stuff."
DoEvents Next i Close #1 End Sub
'In this second example, the DoEvents statement is used to wait until 'the queue has been completely flushed.
Sub Main()
AppActivate "Notepad" 'Activate Notepad.
SendKeys "This is a test.",False 'Send some keys.
DoEvents 'Wait for the keys to play back.
End Sub
See Also DoEvents (function).
Platform(s) Windows and Macintosh.
DoKeys (statement)
Syntax DoKeys KeyString$ [,time]
Description Simulates the pressing of the specified keys.
Comments The DoKeys statement accepts the following parameters:
Parameter Description
KeyString$ String containing the keys to be sent. The format for KeyString$ is described under the SendKeys statement.
time Integer specifying the number of milliseconds devoted for the output of the entire KeyString$ parameter. It must be within the following range:
0 <= time <= 32767
For example, if time is 5000 (5 seconds) and the KeyString$ parameter contains ten keys, then a key will be output every 1/2 second. If unspecified (or 0), the keys will play back at full speed.
Example 'This code fragment plays back the time and date into Notepad.
Const crlf = Chr$(13) + Chr$(10) Sub Main()
id = Shell("Notepad",4) 'Run Notepad.
AppActivate "Notepad"
t$ = time$
d$ = date$
DoKeys "The time is: " & t$ & "." & crlf DoKeys "The date is: " & d$ & "."
End Sub
See Also SendKeys (statement); QueKeys (statement); QueKeyDn (statement); QueKeyUp
(statement).
Platform(s) Windows.
Platform Notes:
Windows
This statement uses the Windows journalizing mechanism to play keystrokes into the Windows environment.
Double (data type)
Syntax Double
Description A data type used to declare variables capable of holding real numbers with 15–
16 digits of precision.
Chapter 2 DropListBox (statement) 189