Syntax
|
Function
DlgProc(ControlName$, Action, SuppValue)
[As Integer]
|
Description
|
Describes the syntax, parameters, and return value for dialog functions.
|
Comments
|
Dialog functions are called by a script during the processing of a custom dialog box. The name of a dialog function (DlgProc) appears in the
Begin Dialog
statement as the .DlgProc parameter.
Dialog functions require the following parameters:
|
|
Parameter
|
Description
|
|
ControlName$
|
String containing the name of the control associated with Action.
|
|
Action
|
Integer containing the action that called the dialog function.
|
|
SuppValue
|
Integer of extra information associated with Action. For some actions, this parameter is not used.
|
|
When a script displays a custom dialog box, the user may click on buttons, type text into edit fields, select items from lists, and perform other actions. When these actions occur, the Basic Control Engine calls the dialog function, passing it the action, the name of the control on which the action occurred, and any other relevant information associated with the action.
The following table describes the different actions sent to dialog functions:
|
|
Action
|
Description
|
|
1
|
This action is sent immediately before the dialog box is shown for the first time. This gives the dialog function a chance to prepare the dialog box for use. When this action is sent, ControlName$ contains a zero-length string, and SuppValue is 0.
The return value from the dialog function is ignored in this case.
Before Showing the Dialog Box
After action 1 is sent, the Basic Control Engine performs additional processing before the dialog box is shown. Specifically, it cycles though the dialog box controls checking for visible picture or picture button controls. For each visible picture or picture button control, the Basic Control Engine attempts to load the associated picture.
In addition to checking picture or picture button controls, the Basic Control Engine will automatically hide any control outside the confines of the visible portion of the dialog box. This prevents the user from tabbing to controls that cannot be seen. However, it does not prevent you from showing these controls with the DlgVisible statement in the dialog function.
|
|
2
|
This action is sent when:
- A button is clicked, such as OK, Cancel, or a push button. In this case, ControlName$ contains the name of the button. SuppValue contains 1 if an OK button was clicked and 2 if a Cancel button was clicked; SuppValue is undefined otherwise.
If the dialog function returns 0 in response to this action, then the dialog box will be closed. Any other value causes the Basic Control Engine to continue dialog processing.
- A check box's state has been modified. In this case, ControlName$ contains the name of the check box, and SuppValue contains the new state of the check box (1 if on, 0 if off).
- An option button is selected. In this case, ControlName$ contains the name of the option button that was clicked, and SuppValue contains the index of the option button within the option button group (0-based).
- The current selection is changed in a list box, drop list box, or combo box. In this case, ControlName$ contains the name of the list box, combo box, or drop list box, and SuppValue contains the index of the new item (0 is the first item, 1 is the second, and so on).
|
|
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 the Basic Control Engine 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.
Note: Not returning zero will cause your application to use all available CPU time and may adversely affect your CIMPLICITY System.
|
|
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 statements and functions. These statements allow you to manipulate the dialog box controls dynamically.
DlgVisible DlgText$ DlgText
DlgSetPicture DlgListBoxArray DlgFocus
DlgEnable DlgControlId
|
|
The dialog function can optionally be declared to return a
Variant
. When returning a variable, the Basic Control Engine 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).
|