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.

n 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).

D