The ScriptDlg ActiveX control

dScope Series III ScriptDlg Manual

The ScriptDlg ActiveX control has been designed to improve the user-interface options of the dScope scripting language, VBScript. By default, VBScript simply allows a simple message box (MsgBox) or text input control (InputBox) which are not particularly flexible or tidy.

The ScriptDlg ActiveX control allows you to create simple dialogue boxes from within a script. These can contain edit controls, buttons, check boxes, and even slider controls and selection lists.

For a brief introduction to using the ScriptDlg ActiveX control, see the Introduction section.

For a full list of the controls, properties and methods available, see the ScriptDlg reference section.

The ScriptDlg ActiveX control


Introduction

A ScriptDlg object is created from a script using the standard methods for creating ActiveX controls - using "CreateObject". This function will return a reference to the object in question, which is then used in every further operation involving the ScriptDlg object.

Set form = CreateObject("ScriptDlg.Form")

Once the form object has been created, you will need to decide whether you want to handle events in your form (button clicks, list box selections, etc). This will usually be the case, so you will need to initialise the object's Event Handler. To do this, pass the object you just created to the InitEventHandler method:

form.InitEventHandler(form)

Now it's time to add some controls. To do this, you need to call Add... for each control that you want in your dialogue box:

form.AddStatic "static1", "This is some text"

form.AddPushButton "button1", "Click me"

Note that the first parameter to each of these Add... methods is the name of the button. This will be the name used when referring to the control throughout the script.

Finally, now our controls are set up, we need to tell the ActiveX control to actually display the dialogue box:

form.Display()

If you run the script, you should now see a dialogue box that looks something like the following:

Note that you didn't have to tell the dialogue where to put the controls, as it positions and sizes them automatically. You can set positions and sizes if you want to though - see the ScriptDlg reference for further details.

Introduction The ScriptDlg ActiveX Control


ScriptDlg reference

This reference section describes all of the ScriptDlg' s properties and methods. It also describes events that can be fired from the controls on a dialogue.

The following objects are described as part of this reference:

Form

Push buttons

Edit controls

Static (text) controls

Check boxes

Radio buttons

Slider controls

Drop-list controls

List box controls

Bitmap controls

Progress controls

ScriptDlg reference The ScriptDlg ActiveX Control


Form

The form is the main dialogue box for the ScriptDlg control.

Methods

InitEventHandler

SetEvent_OnCreate

SetEvent_OnClose

Display

Close

NewRow

SetFont

StartButtonGroup

Sleep

Minimize

Restore

ShowHelpTopic

ShowBrowseDlg

SetBackgroundColour

AddPushButton

AddStatic

AddEdit

AddCheckBox

AddRadioButton

AddSlider

AddDropList

AddBitmap

AddProgress

Properties

Title

XPos

YPos

Width

Height

Modal

DynamicallyResize

VerticalSpacing

HorizontalSpacing

RunFromdScope

BrowsePath

BrowseTitle

BrowseFileFilter

Events

Create

Close

Form ScriptDlg reference


XPos

Description

This property represents the X position of the form, in pixels.

If this property is not explicitly set, the form will be centred horizontally on the screen.

Values

Any numerical value can be used.

If the X position specified is greater than the current X range of the screen resolution, the form will be off the right edge of the screen and therefore unusable!

The same applies if the X position is less than zero, as it will cause the dialog to be started off the left of the screen.

XPos Form > See Also


YPos

Description

This property represents the Y position of the form, in pixels.

If this property is not explicitly set, the form will be centred vertically on the screen.

Values

Any numerical value can be used.

If the Y position specified is greater than the current Y range of the screen resolution, the form will be off the bottom of the screen and therefore unusable!

The same applies if the Y position is less than zero, as it will cause the dialog to be started off the top of the screen.

YPos Form > See Also


Width

Description

This property represents the width of the form, in pixels.

If this property is not explicitly specified, then the form will be resized automatically according to the controls on it. Note that this may make it larger than the screen.

Values

Any numerical value greater than 0 can be used.

If the width specified is greater than the current X range of the screen resolution, the form will be larger than the screen. This may cause controls on the form to be lost at the edges.

Width Form > See Also


Height

Description

This property represents the height of the form, in pixels.

If this property is not explicitly specified, then the form will be resized automatically according to the controls on it. Note that this may make it larger than the screen.

Values

Any numerical value greater than 0 can be used.

If the width specified is greater than the current Y range of the screen resolution, the form will be larger than the screen. This may cause controls on the form to be lost at the top and bottom.

Height Form > See Also


Modal

Description

This property specifies whether the form should be modal (i.e. no actions can be taken on other applications while the dialogue box is shown), or modeless (other applications can be used while the dialogue box is open)

If the script containing the ScriptDlg form must process events while the ScriptDlg is open, then the Modal property MUST be set to False.

By default, the form will be modal.

If the ScriptDlg form is modeless (i.e. the Modal property is set to False) then the script MUST contain code after the Display method is called, to ensure that the script does not end before the ScriptDlg form is closed.

It does this by using the IsActive property.

Values

True | Sets the form to be modal
False | Sets the form to be modeless

Modal Form


IsActive

Description

This read-only property specifies whether a modeless form (i.e. one with its Modal property set to False) is still active.

If the form is set to modeless, this property MUST be checked to ensure that the script does not end before the form has been closed.

For example :

' Create and set up parts of the form, including:

form.Modal = False

' Display the form

form.Display()

' Wait until the user has closed the form

While form.IsActive

  ' Wait around until finished.

  ' This will allow events to happen, controls on the

  ' form to be updated, etc.

Wend

If the ScriptDlg is modeless, and it is NOT run from within the dScope, the RunFromdScope property MUST be set to False. Otherwise, the ScriptDlg will not respond to any mouse clicks or other Windows events, and will appear to hang.

Values

True | Returned if the form is still active
False | Returned if the form is no longer active

IsActive


Title

Description

This property represents the title of the form, i.e. the text that will appear in the title bar.

Values

Any string can be used as the form's title.

Title Form


DynamicallyResize

Description

This property specifies whether the form should be dynamically resized as controls are added to it.

By default, the form will be dynamically resizable.

If you do not specify a Width for the form, the form will be dynamically resized regardless of the value of this property.

Values

True | Sets the form to be dynamically resizable
False | Sets the form to be statically sized, i.e. the form will have the width specified by the Width property.

DynamicallyResize Form > See Also


VerticalSpacing

Description

This property specifies the vertical spacing between controls on the form, in pixels.

The default value for this property is 3 pixels.

This value is also used for the vertical margins on the form, i.e. the distance that controls will be positioned from the top and bottom of the form.

Values

Any numerical value greater than 0 and less than 100 is allowed.

VerticalSpacing Form > See Also


HorizontalSpacing

Description

This property specifies the horizontal spacing between controls on the form, in pixels.

The default value for this property is 3 pixels.

This value is also used for the horizontal margins on the form, i.e. the distance that controls will be positioned from the left and right hand sides of the form.

Values

Any numerical value greater than 0 and less than 100 is allowed.

HorizontalSpacing Form > See Also


RunFromdScope

Description

This property can be set to specify whether the ScriptDlg form has been instantiated from within the dScope Series III software.

This property is only currently useful in the following situation: when a script that is run from within the dScope stops, it automatically closes down any ScriptDlg forms that are open. If a ScriptDlg's RunFromdScope property is set to False, then it will not be shut down automatically.

Note that if this property is set to True, then any function key that is pressed (F1..F12, or <Ctrl>, <Alt> or <Shift> together with F1..F12) will be passed on the running dScope program. This allows function keys to work even if a ScriptDlg form has the focus instead of the dScope program.

Values

True | Specifies that this ScriptDlg form has been created from within a dScope script (default).
False | Specifies that this ScriptDlg form has been created as a standalone entity, i.e. from outside the dScope.

RunFromdScope Form


BrowsePath

Description

This property can be used to set the foile/folder path that the Browse dialogue box will use (See ShowBrowseDlg).

This property should be set before calling ShowBrowseDlg to the path that the Browse dialog box should be opened in. If a file is selected and [OK] is pressed, this property will be overwritten with the full path name of the file selected.

Values

Any valid file path can be used. If a folder is specified, then the Browse dialogue box will open in that folder; if a full file path is specified, then the file name will be selected by default in the dialogue box.

BrowsePath Form > See Also


BrowseTitle

Description

This property can be used to set the title of the Browse dialogue box (See ShowBrowseDlg).

By default, the title of the Browse dialogue box will be "Open" or "Save As", depending on the bOpen parameter passed to ShowBrowseDlg.

Values

Any valid string can be used as the title of the Browse dialogue box. If set to a null string ("") then the default title will be used ("Open" or "Save As", depending on the bOpen parameter passed to ShowBrowseDlg).

BrowseTitle Form > See Also


BrowseFileFilter

Description

This property can be used to set the file filter to use in the Browse dialogue box (See ShowBrowseDlg). This limits the types of files that will appear in the dialogue box, based on their file extensions.

By default, the file filter is all files (*.*).

This property must be specified as one or more pairs of strings, separated by the '|' character. The first string in the string pair describes the filter; the second string indicates the file extension to use. Multiple extensions may be specified using ';' as the delimiter. The string ends with two '|' characters.

For example, to allow two selectable filters: for dScope script files, or "All files", you should specify the following string:

strFilter = "Scripts (*.dss; *.vbs)|*.dss; *.vbs|"

strFilter = strFilter & "All files (*.*)|*.*||"

Values

Any string containing a valid set of file filters as described above can be used. If set to a null string ("") then the default file filter will be used ("All files (*.*)").

BrowseFileFilter Form > See Also


InitEventHandler

InitEventHandler (formobject)

This method is used to initialize the part of the form that handles events. It must be called if the script is to respond to any button clicking, list-box selection changing, etc.

Parameters

formobject

The form object that has been created. This will be the value returned by the CreateObject function.

Return value

This method has no return value.

Example

The following code will create a form object called "form1" and initialize the object so that events will be fired.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

InitEventHandler Form > See Also


SetEvent_OnCreate

SetEvent_OnCreate (eventref)

This method is used to specify the function that will be called when the form is initially created. The form will be initialized with all the controls on it, and then this event will be fired in case the script needs to do any further processing.

See OnCreate event for details of the event function.

The form's event handler MUST have been initialised using InitEventHandler before any events will fire.

Parameters

eventref

A reference to the event function to be called when the form is created. This must be passed in the form GetRef ("form_OnCreate").

Return value

This method has no return value.

Example

The following code will create a form object called "form1", initialize the object so that events will be fired, and set an event that is fired when the dialogue box is created.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

form1.SetEvent_OnClose GetRef("form1_OnCreate")

form1.Display()

Sub form1_OnCreate()

MsgBox "The form has been created"

End Sub

SetEvent_OnCreate Form > See Also


SetEvent_OnClose

SetEvent_OnClose (eventref)

This method is used to specify the function that will be called when the form is closed.

See OnClose event for details of the event function.

The form's event handler MUST have been initialised using InitEventHandler before any events will fire.

Parameters

eventref

A reference to the event function to be called when the form is closed. This must be passed in the form GetRef ("form_OnClose").

Return value

This method has no return value.

Example

The following code snippet will create a form object called "form1", initialize the object so that events will be fired, and set an event that is fired when the dialogue box is closed.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

form1.SetEvent_OnClose GetRef("form1_OnClose")

form1.Display()

Sub form1_OnClose(sValue)

MsgBox "The form has been closed"

End Sub

SetEvent_OnClose Form > See Also


Display

Display ()

Once controls have been set up on a ScriptDlg form, this method actually displays the form.

If the ScriptDlg form has been set up as Modal, the script will not return from this method until the ScriptDlg has been closed.

This is the point at which all controls' automatic sizes and positions are calculated, so ALL controls must have been added to the form before this method is used.

Parameters

This method has no parameters

Return value

This method has no return value.

Display Form


Close

Close (sValue)

This method can be called to close the form.

Parameters

sValue

A value associated with the closing of the form. For example, you could use this parameter to determine which button was used to close the form.

This parameter is passed as a parameter to the OnClose event.

Return value

This method has no return value.

Close Form > See Also


NewRow

NewRow ()

This method can be called to start a new row in the form.

By default, automatic positioning of controls will add them across the form from left to right. If this methods is called, the next control will revert to being on the next row down, starting on the left hand side of the form.

Starting a new row will set the position of the next control to be HorizontalSpacing pixels from the left hand side of the form, and VerticalSpacing pixels below the bottom of the largest control in the previous row.

Parameters

This method has no parameters.

Return value

This method has no return value.

NewRow Form


SetFont

SetFont (strFontName, sSize, sStyle)

This method can be called to set the font on the form.

Parameters

strFontName | The name of the font. This can be any one of the standard Windows font names, such as "Arial", "Courier", etc.
sSize | The size of the font, in points. The default font size is the same as the system font (usually 10 points).
sStyle | The style of the font to set. It can have any combination of the styles listed under Font Styles below.

Return value

This method has no return value.

Font Styles

The following font styles, or combinations of styles, are allowed for the sStyle parameter:

fontBold | 1 | Sets the font to be Bold.
fontItalic | 2 | Sets the font to be italic.

Example

Use the following line to set the font of the form to a 12-point, bold and italic, Arial font.

form.SetFont "Arial", 12, 3

SetFont Form


StartButtonGroup

StartButtonGroup ()

This method can be called to start a group of radio buttons.

When radio buttons are put on a form, by default they will all be in the same group. This means that when any radio button is the group is selected, all other radio buttons will automatically be un-selected.

This method allows creation of more than one set of selection criteria on a form.

This method does not have to be on the line before the first radio button in the group; in fact a radio button group can also contain other controls. All non-radio-button controls will be ignored for purposes of determining the buttons in a group.

Parameters

This method has no parameters.

Return value

This method has no return value.

Example

Use the following code to start two groups of radio buttons, each containing three buttons.

form.AddStatic "static1", "First set of buttons"

form.NewRow

' Note that 'StartButtonGroup' is not necessary here

' because they are all in the same group until we

' call StartButtonGroup to start a new one.

form.AddRadioButton "radio1", "selection 1"

form.AddRadioButton "radio2", "selection 2"

form.AddRadioButton "radio3", "selection 3"

form.NewRow

form.AddStatic "static2", "Second set of buttons"

form.NewRow

form.StartButtonGroup

form.AddRadioButton "radio4", "selection 4"

form.AddRadioButton "radio5", "selection 5"

form.AddRadioButton "radio6", "selection 6"

StartButtonGroup Form > See Also


Sleep

Sleep (lNumMilliseconds)

This method causes the script to wait for the specified time, in the meantime allowing other threads to run (for example, any of the dScope program threads).

If the script simply sits in a loop to wait (for example, in a while loop), then Windows will keep the script thread running continuously and so no other software used with the script will be able to run. The Sleep function ensures that other software can run while the script containing the ScriptDlg form is waiting.

Parameters

lNumMilliseconds

This specifies the time to wait, in milliseconds. Note that this time is approximate, as Windows will wait for at least this amount of time before returning control to the script.

A value of 0 can be used to simply ask other threads to process before returning.

The Windows timer is only accurate to around the nearest 50ms.

Return value

This method has no return value.

Sleep Form


Minimize

Minimize ()

This method can be called to minimize the ScriptDlg form. This will cause the form to be displayed as an icon in the Windows toolbar at the bottom of the screen.

Once minimized, the ScriptDlg form can be restored to its original position using the Restore method.

Parameters

This method has no parameters.

Return value

This method has no return value.

Minimize Form > See Also


Restore

Restore ()

This method can be called to restore a minimized ScriptDlg form to its original position.

Parameters

This method has no parameters.

Return value

This method has no return value.

Restore Form > See Also


ShowHelpTopic

ShowHelpTopic (strHelpFile, strHelpTopic)

This method opens a help file, and displays the specified help topic from it.

Parameters

strHelpFile

Full path of the help file, enclosed in double quotation marks ("..."). This will usually have the extension ".chm".

strHelpTopic

The name of the help topic to display, enclosed in double quotation marks ("..."). This will usually have the extension ".htm".

You can open the help topic at a specific "Anchor" point by appending "#Anchor" to the help topic name, where "Anchor" is the name of the anchor or bookmark in the topic.

Return value

This method has no return value.

ShowHelpTopic Form


ShowBrowseDlg

ShowBrowseDlg (bOpen)

This method opens a standard Windows dialogue box to allow selection of a file for opening or saving. If a file is selected, the BrowsePath property will contain the full path and filename of the file selected.

The BrowsePath property is also used to determine the folder in which the Browse dialogue box opens; if a file is selected and the OK button is pressed, it will be overwritten with the details of the selected file.

Parameters

bOpen

True to show an "Open" dialogue box; False to show a "Save As" dialogue box.

Return value

This method has no return value.

ShowBrowseDlg Form > See Also


SetBackgroundColour

SetBackgroundColour (sRed, sGreen, sBlue)

This method is used to set the background colour of this form.

Parameters

sRed | The red component of the colour to set the background to (0 - 255).
sGreen | The green component of the colour to set the background to (0 - 255).
sBlue | The blue component of the colour to set the background to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set a form's background colour to red.

form1.SetBackgroundColour 255, 0, 0

SetBackgroundColour Form


AddPushButton

AddPushButton strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]

This method can be called to add a push-button to the form.

The sWidth, sHeight, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See Push buttons for the properties and methods available to the button once it has been added to the form.

Parameters

strName | The name of the button. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
strText | The text to put on the button.
sWidth | (optional) The width of the button, in pixels. Use -1 to automatically size the button to the width of the text.
sHeight | (optional) The height of the button, in pixels. Use -1 to automatically size the button to the height of the text.
sXPos | (optional) The X position of the button, in pixels from the left-hand side of the form. Use -1 to automatically position the button to the right of the previous control.
sYPos | (optional) The Y position of the button, in pixels from the left-hand side of the form. Use -1 to automatically position the button at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add a push-button, at an X position of 150 pixels and 20 pixels high (but automatically sized to the width of the text).

form.AddPushButton "Button1", "Select Me!", -1, 20, 150

AddPushButton Form > See Also


AddStatic

AddStatic strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]

This method can be called to add a static text control to the form.

The sWidth, sHeight, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See Static (text) Controls for the properties and methods available to the static control once it has been added to the form.

Parameters

strName | The name of the static control. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
strText | The text to put on the static control.
sWidth | (optional) The width of the static control, in pixels. Use -1 to automatically size the static control to the width of the text.
sHeight | (optional) The height of the static control, in pixels. Use -1 to automatically size the static control to the height of the text.
sXPos | (optional) The X position of the static control, in pixels from the left-hand side of the form. Use -1 to automatically position the static control to the right of the previous control.
sYPos | (optional) The Y position of the static control, in pixels from the left-hand side of the form. Use -1 to automatically position the static control at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add a static control, at an X position of 100 pixels and 14 pixels high (but automatically sized to the width of the text).

form.AddStatic "static2", "This is some text", -1, 14, 100

AddStatic Form > See Also


AddEdit

AddEdit strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]

This method can be called to add an edit control to the form.

The sWidth, sHeight, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See Edit Controls for the properties and methods available to the edit control once it has been added to the form.

Parameters

strName | The name of the edit control. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
strText | The text to put on the edit control.
sWidth | (optional) The width of the edit control, in pixels. Use -1 to automatically size the edit control to the width of the text.
sHeight | (optional) The height of the edit control, in pixels. Use -1 to automatically size the edit control to the height of the text.
sXPos | (optional) The X position of the edit control, in pixels from the left-hand side of the form. Use -1 to automatically position the edit control to the right of the previous control.
sYPos | (optional) The Y position of the edit control, in pixels from the left-hand side of the form. Use -1 to automatically position the edit control at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add an edit control, at an X position of 30 pixels and 50 pixels high (but automatically sized to the width of the text).

form.AddEdit "edit3", "Type some text here...", -1, 50, 30

AddEdit Form > See Also


AddCheckBox

AddCheckBox strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]

This method can be called to add a check box to the form.

The sWidth, sHeight, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See Check boxes for the properties and methods available to the check box once it has been added to the form.

Parameters

strName | The name of the check box. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
strText | The text to put on the check box.
sWidth | (optional) The width of the check box, in pixels. Use -1 to automatically size the control to the width of the text and the check box.
sHeight | (optional) The height of the check box, in pixels. Use -1 to automatically size the control to the height of the text.
sXPos | (optional) The X position of the check box, in pixels from the left-hand side of the form. Use -1 to automatically position the check box to the right of the previous control.
sYPos | (optional) The Y position of the check box, in pixels from the left-hand side of the form. Use -1 to automatically position the check box at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add a check box, at an X position of 5 pixels, but automatically sized to the width and height of the text.

form.AddCheckBox "CheckBox5", "Click to turn on/off!",

-1, -1, 5

AddCheckBox Form > See Also


AddRadioButton

AddRadioButton strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]

This method can be called to add a radio button to the form.

The sWidth, sHeight, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See Radio buttons for the properties and methods available to the radio button once it has been added to the form.

Radio buttons can be grouped. When a radio button is selected, all other radio buttons in the same group will automatically be un-selected. For details of how to group radio buttons, see StartButtonGroup.

Parameters

strName | The name of the radio button. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
strText | The text to put on the radio button.
sWidth | (optional) The width of the radio button, in pixels. Use -1 to automatically size the control to the width of the text and the radio button.
sHeight | (optional) The height of the radio button, in pixels. Use -1 to automatically size the control to the height of the text.
sXPos | (optional) The X position of the radio button, in pixels from the left-hand side of the form. Use -1 to automatically position the radio button to the right of the previous control.
sYPos | (optional) The Y position of the radio button, in pixels from the left-hand side of the form. Use -1 to automatically position the radio button at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add two radio buttons, at X positions of 35 pixels, but automatically sized to the width and height of the text.

form.AddRadioButton "Radio1", "This one's for kids",

-1, -1, 35

form.AddRadioButton "Radio2", "What Radio1 used to be",

-1, -1, 35

AddRadioButton Form > See Also


AddSlider

AddSlider strName, [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]

This method can be called to add a slider control to the form.

The sWidth, sHeight, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See Slider Controls for the properties and methods available to the slider control once it has been added to the form.

Parameters

strName | The name of the slider control. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
sWidth | (optional) The width of the slider control, in pixels. Use -1 to automatically size the control to a width based on the number of ticks in the slider control.
sHeight | (optional) The height of the slider control, in pixels. Use -1 to automatically size the control's height.
sXPos | (optional) The X position of the slider control, in pixels from the left-hand side of the form. Use -1 to automatically position the slider control to the right of the previous control.
sYPos | (optional) The Y position of the slider control, in pixels from the left-hand side of the form. Use -1 to automatically position the slider control at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add a slider control, at an X position of 40 pixels and a Y position of 20, but automatically sized.

form.AddSlider "Slider1", -1, -1, 40, 20

AddSlider Form > See Also


AddDropList

AddDropList strName, [, sWidth [, sXPos [, sYPos] ] ]

This method can be called to add a drop-list control to the form.

The sWidth, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See Drop-list controls for the properties and methods available to the drop-list control once it has been added to the form.

The height of the drop-list will always be set automatically to the height of one line of text, in the drop-list's font.

Parameters

strName | The name of the drop-list control. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
sWidth | (optional) The width of the drop-list control, in pixels. Use -1 to automatically size the control to a width based on the width of the longest text in the drop-list.
sXPos | (optional) The X position of the drop-list control, in pixels from the left-hand side of the form. Use -1 to automatically position the drop-list control to the right of the previous control.
sYPos | (optional) The Y position of the drop-list control, in pixels from the left-hand side of the form. Use -1 to automatically position the drop-list control at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add a drop-list control, 250 pixels wide, at an X position of 40 pixels and a Y position of 20, but automatically sized.

form.AddDropList "DropList1", 250, -1, 40, 20

AddDropList Form > See Also


AddListBox

AddListBox strName, [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]

This method can be called to add a list box control to the form.

The sWidth, sHeight, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See List box controls for the properties and methods available to the list box control once it has been added to the form.

Parameters

strName | The name of the list box control. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
sWidth | (optional) The width of the list box control, in pixels. Use -1 to automatically size the control to an arbitrary width (around 200 pixels)
sHeight | (optional) The height of the list box control, in pixels. Use -1 to automatically size the control to an arbitrary height (enough for 10 items)
sXPos | (optional) The X position of the list box control, in pixels from the left-hand side of the form. Use -1 to automatically position the list box control to the right of the previous control.
sYPos | (optional) The Y position of the list box control, in pixels from the left-hand side of the form. Use -1 to automatically position the list box control at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add a drop-list control, 200 pixels wide and 150 pixels high, at an X position of 10 pixels and a Y position of 20.

form.AddListBox "MyListBox", 200, 150, 10, 20

AddListBox Form > See Also


AddBitmap

AddBitmap strName, strFileName, [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]

This method can be called to add a bitmap control to the form.

The sWidth, sHeight, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See Bitmap controls for the properties and methods available to the bitmap control once it has been added to the form.

Parameters

strName | The name of the bitmap control. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
strFileName | The file name of the bitmap to insert into this control.
sWidth | (optional) The width of the bitmap control, in pixels. Use -1 to automatically size the control to the width of the bitmap specified with strFileName.
sHeight | (optional) The height of the bitmap control, in pixels. Use -1 to automatically size the control to the height of the bitmap specified with strFileName.
sXPos | (optional) The X position of the bitmap control, in pixels from the left-hand side of the form. Use -1 to automatically position the bitmap control to the right of the previous control.
sYPos | (optional) The Y position of the bitmap control, in pixels from the left-hand side of the form. Use -1 to automatically position the bitmap control at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add a bitmap control, at an X position of 40 pixels and a Y position of 20, automatically sized to the size of the bitmap. The bitmap to display in the control is stored in "C:\My Documents\Bitmap1.bmp".

form.AddBitmap "Slider1",

"C:\My Documents\Bitmap1.bmp",

-1, -1, 40, 20

AddBitmap Form > See Also


AddProgress

AddProgress strName, [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]

This method can be called to add a progress control to the form.

The sWidth, sHeight, sXPos and sYPos are optional parameters - however if any are specified, then all the parameters to the left must also be specified (see Example section below).

Any parameters not specified will be passed as -1, to denote "automatic".

See Progress controls for the properties and methods available to the progress control once it has been added to the form.

Parameters

strName | The name of the progress control. This name does not appear on the form, but is used to refer to this control to set further properties of the control itself.
sWidth | (optional) The width of the progress control, in pixels. Use -1 to automatically size the control to a nominal width.
sHeight | (optional) The height of the progress control, in pixels. Use -1 to automatically size the progress to a nominal height.
sXPos | (optional) The X position of the progress control, in pixels from the left-hand side of the form. Use -1 to automatically position the progress control to the right of the previous control.
sYPos | (optional) The Y position of the progress control, in pixels from the left-hand side of the form. Use -1 to automatically position the progress control at the same height as the previous control (or the row below, if NewRow has been called in-between).

Return value

This method has no return value.

Example

Use the following line to add a progress control, automatically positioned after the previous control, with a width of 150 pixels and an automatic height.

form.AddProgress "Progress", 150

AddProgress Form > See Also


OnCreate event

The OnCreate event will be fired when the form is created. This will be after all controls have been added to the form, but after it is actually displayed.

To tell the form which event function to call on creation, use the SetEvent_OnCreate method.

The OnCreate event function may have any name, but must have the following format:

Sub form_OnCreate()

' Do your processing here

End Sub

Parameters

This event function has no parameters.

Return value

This event function has no return value.

OnCreate event Form > See Also


OnClose event

The OnClose event will be fired when the form is closed. This may be from the Close method, or simply by the user clicking on the "X" in the top-right corner of the form.

To tell the form which event function to call on closing the form, use the SetEvent_OnClose method.

The OnClose event function may have any name, but must have the following format:

Sub form_OnClose (sValue)

' Do your processing here

End Sub

A parameter (e.g. sValue, as shown above) must be included in this event, or it will not get called.

Parameters

sValue

Indicates the value passed to the Close function. This can be used by the script to determine, for example, which button was used to close the form.

Return value

This event function has no return value.

OnClose event Form > See Also


Push buttons

Push buttons allow the user to perform some action by clicking on the button.

Creation

A push button can be created using the form's AddPushButton method. This method takes as one of its parameters the name of the button, which is then used throughout the script when referring to this button.

For example

form.AddPushButton "Button1", "Click me!", 100, 12, 5, 5

would mean that all properties and methods of this button would be called by simply prefixing them with

form.Button1.

Properties

Visible

Enabled

XPos

YPos

Width

Height

Text

TabStop

Alignment

Methods

SetTextColour

SetBackgroundColour

SetFont

SetDefault

SetEvent_OnClick

Events

OnClick

Push buttons ScriptDlg reference > See Also


Visible

Description

This property specifies whether the button should be visible or invisible.

This can be useful if different selections in other controls (for example, drop-lists or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

A button is visible by default.

An invisible button cannot fire events.

Values

True | Sets the button to be visible.
False | Sets the button to be invisible.

Visible Push buttons > See Also


Enabled

Description

This property specifies whether the button should be enabled or disabled.

A button is enabled by default.

A disabled button cannot fire any events.

Values

True | Sets the button to be enabled.
False | Sets the button to be disabled.

Enabled Push buttons > See Also


XPos

Description

This property represents the X position of the button, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddPushButton is used, then the button will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos Push buttons > See Also


YPos

Description

This property represents the Y position of the button, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddPushButton is used, then the button will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos Push buttons > See Also


Width

Description

This property represents the width of the button, in pixels.

If this property is not explicitly specified, either using this property or when AddPushButton is used, then the button will be sized to fit the current text (specified using Text, or originally with AddPushButton). In this case, any changes to the text may result in the button changing size.

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width Push buttons > See Also


Height

Description

This property represents the height of the button, in pixels.

If this property is not explicitly specified, either using this property or when AddPushButton is used, then the button will be sized to fit the current text (specified using Text, or originally with AddPushButton). In this case, any changes to the text may result in the button changing size.

Values

Any numerical value greater than 0 can be used.

If the height specified will take this control beyond the bottom of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Height Push buttons > See Also


Text

Description

This property represents the text on the button.

Values

Any string can be used as the button's text.

Text Push buttons > See Also


TabStop

Description

This property specifies whether the button should have the "TabStop" property.

A button with the TabStop property will get the focus as the TAB key is used to move through the controls on the form.

By default, buttons have the TabStop property set to True.

Values

True | Sets the button to have the TabStop property.
False | Specifies that the button should not have the TabStop property.

TabStop Push buttons


Alignment

Description

This property represents the alignment of the text within the button control.

It can be any of the alignments detailed below. Note that if more than one alignment is specified, the first one from the list below will be used.

The default alignment for the text on a button is in the centre.

Values

alignLeft | 1 | Sets the text on the button to be horizontally aligned to the left of the control.
alignHCentre | 2 | Sets the text on the button to be horizontally aligned in the centre of the control.
alignRight | 4 | Sets the text on the button to be horizontally aligned to the right of the control.

Alignment Push buttons


TooltipText

Description

This property represents the Tooltip text for the button. This is text displayed in a small pop-up window when the mouse pointer is held over the button. It is usually used to contain a brief description of the purpose of the button.

Values

Any string can be used as the Tooltip text, up to a maximum of 80 characters.

TooltipText Push buttons


SetTextColour

SetTextColour (sRed, sGreen, sBlue)

This method is used to set the text colour of this button.

Parameters

sRed | The red component of the colour to set the text to (0 - 255).
sGreen | The green component of the colour to set the text to (0 - 255).
sBlue | The blue component of the colour to set the text to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two buttons' text colours to blue and green, respectively.

form1.button1.SetTextColour 0, 0, 255

form1.button2.SetTextColour 0, 255, 0

SetTextColour Push buttons > See Also


SetBackgroundColour

SetBackgroundColour (sRed, sGreen, sBlue)

This method is used to set the background colour of this button.

Parameters

sRed | The red component of the colour to set the background to (0 - 255).
sGreen | The green component of the colour to set the background to (0 - 255).
sBlue | The blue component of the colour to set the background to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two buttons' background colours to black and white, respectively.

form1.button1.SetBackgroundColour 0, 0, 0

form1.button2.SetBackgroundColour 255, 255, 255

SetBackgroundColour Push buttons > See Also


SetFont

SetFont (strFontName, sSize, sStyle)

This method can be called to set the font of the text on a button.

Parameters

strFontName | The name of the font. This can be any one of the standard Windows font names, such as "Arial", "Courier", etc.
sSize | The size of the font, in points. The default font size is the same as the system font (usually 10-points).
sStyle | The style of the font to set. It can have any combination of the styles listed under Font Styles below.

Return value

This method has no return value.

Font Styles

The following font styles, or combinations of styles, are allowed for the sStyle parameter:

fontBold | 1 | Sets the font to be Bold.
fontItalic | 2 | Sets the font to be italic.

Example

Use the following line to set the font of a button to a 10-point, bold and italic, "MS Sans Serif" font.

form.button3.SetFont "MS sans Serif", 10, 3

SetFont Push buttons


SetFocus

SetFocus ()

This method can be called to set the focus to this button (i.e. make it the control that currently handles keyboard input). This means that pressing the Enter key, or the space bar, will act as a click on the button.

Giving the focus to a control will remove the focus from any control which has previously been given it.

Parameters

This method has no parameters.

Return value

This method has no return value.

Example

Use the following line to set the focus to a previously-created push button.

form.MyButton1.SetFocus()

SetFocus Push buttons > See Also


HasFocus

HasFocus ()

This method can be called to determine whether a control currently has the focus.

Parameters

This method has no parameters.

Return value

This method returns True .

Example

Use the following line to determine whether a previously-created push button has the focus. This can be used in an OnClick event handler, for example, to determine which button was actually clicked.

If form.MyButton1.HasFocus() Then

' Do something here

End If

HasFocus Push buttons > See Also


SetDefault

SetDefault ()

This method is used to set this button to be the default selected button. This means that if the <Enter> key is pressed, it will behave like a click on this button.

Parameters

This method has no parameters.

If a button is set as the default button, then all other buttons on the form will have their default property set to False.

Return value

This method has no return value.

Example

The following code will set a button to be the default for a form.

form1.OKbutton.SetDefault()

SetDefault Push buttons


SetEvent_OnClick

SetEvent_OnClick (eventref)

This method is used to specify the function that will be called when a button is clicked.

See OnClick event for details of the event function.

The form's event handler MUST have been initialised using InitEventHandler before any events will fire.

Parameters

eventref

A reference to the event function to be called when the button is clicked. This must be passed in the form GetRef ("button3_OnClick").

Return value

This method has no return value.

Example

The following code snippet will create a form, initialize it so that events will be fired, create a button called "button1", and set an event that is fired when the button is clicked.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

form1.AddPushButton "button1", "Click me!"

form1.button1.SetEvent_OnClick GetRef("button1_OnClick")

form1.Display()

Sub button1_OnClick()

MsgBox "You clicked the button!"

End Sub

SetEvent_OnClick Push buttons > See Also


OnClick event

The OnClick event will be fired when a button is clicked.

To tell the button which event function to call when it is clicked, use the SetEvent_OnClick method.

The OnClick event function may have any name, but must have the following format:

Sub button_OnClick()

' Do your processing here

End Sub

Parameters

This event function has no parameters.

Return value

This event function has no return value.

OnClick event Push buttons > See Also


Edit controls

Edit controls allow the user to enter text on the form. They can be single or multiple lines.

Creation

An edit control can be created using the form's AddEdit method. This method takes as one of its parameters the name of the edit control, which is then used throughout the script when referring to this edit control.

For example

form.AddEdit "Edit1", "Enter text here...", 200, 12, 5, 5

would mean that all properties and methods of this edit control would be called by simply prefixing them with

form.Edit1.

Properties

Visible

Enabled

XPos

YPos

Width

Height

Text

TabStop

Alignment

PasswordStyle

ReadOnly

TooltipText

Methods

SetTextColour

SetBackgroundColour

SetFont

Events

Edit controls do not fire events.

Edit controls ScriptDlg reference > See Also


Visible

Description

This property specifies whether the edit control should be visible or invisible.

This can be useful if different selections in other controls (for example, drop-lists or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

An edit control is visible by default.

Values

True | Sets the edit control to be visible.
False | Sets the edit control to be invisible.

Visible Edit controls > See Also


Enabled

Description

This property specifies whether the edit control should be enabled or disabled.

An edit control is enabled by default.

A disabled edit control stops the user from entering text.

Values

True | Sets the edit control to be enabled.
False | Sets the edit control to be disabled.

Enabled Edit controls > See Also


XPos

Description

This property represents the X position of the edit control, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddEdit is used, then the edit control will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos Edit controls > See Also


YPos

Description

This property represents the Y position of the edit control, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddEdit is used, then the edit control will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos Edit controls > See Also


Width

Description

This property represents the width of the edit control, in pixels.

If this property is not explicitly specified, either using this property or when AddEdit is used, then the edit control will be sized to fit the current text (specified using Text, or originally with AddEdit). In this case, any changes to the text may result in the edit control changing size.

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width Edit controls > See Also


Height

Description

This property represents the height of the edit control, in pixels.

If this property is not explicitly specified, either using this property or when AddEdit is used, then the edit control will be sized to fit the current text (specified using Text, or originally with AddEdit). In this case, any changes to the text may result in the edit control changing size.

Values

Any numerical value greater than 0 can be used.

If the height specified will take this control beyond the bottom of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Height Edit controls > See Also


Text

Description

This property represents the text in the edit control.

Values

Any string can be used as the edit control's text.

Text Edit controls > See Also


TabStop

Description

This property specifies whether the edit control should have the "TabStop" property.

An edit control with the TabStop property will get the focus as the TAB key is used to move through the controls on the form.

By default, edit controls have the TabStop property set to True.

Values

True | Sets the edit control to have the TabStop property.
False | Specifies that the edit control should not have the TabStop property.

TabStop Edit controls


Alignment

Description

This property represents the alignment of the text within the button control.

It can be any of the alignments detailed below. Note that if more than one alignment is specified, the first one from the list below will be used.

The default alignment for the text on a button is in the centre.

Values

alignLeft | 1 | Sets the text in the edit control to be horizontally aligned to the left of the control.
alignHCentre | 2 | Sets the text in the edit control to be horizontally aligned in the centre of the control.
alignRight | 4 | Sets the text in the edit control to be horizontally aligned to the right of the control.

Alignment Edit controls


PasswordStyle

Description

This property specifies whether the edit control should be a password-style control. This means that any character typed into the control will appear as an asterisk ( * ).

An edit control does not have the password style by default.

Values

True | Sets the edit control to be a password-style control.
False | Sets the edit control to be a non-password-style control.

PasswordStyle Edit controls


ReadOnly

Description

This property specifies whether the edit control should be read-only. This means that the edit control will not accept any keyboard input. Note that the contents of a read-only edit control can still be selected using the mouse, and copied to the clipboard.

An edit control allows editing (i.e. it is not read-only) by default.

Values

True | Sets the edit control to be read-only.
False | Sets the edit control to allow editing.

ReadOnly Edit controls


TooltipText

Description

This property represents the Tooltip text for the edit control. This is text displayed in a small pop-up window when the mouse pointer is held over the control. It is usually used to contain a brief description of the purpose of the control.

Values

Any string can be used as the Tooltip text, up to a maximum of 80 characters.

TooltipText Edit controls


MultiLine

Description

This property specifies whether the edit control should be a multi-line edit control. If the MultiLine property is set to True, then the user can enter multiple lines in the control, and can advance on to the next line using the Enter key. If it is set to False, then the Enter key is ignored and only a single line of text can be entered.

An edit control is multi-line by default.

If an edit control is multi-line, and it currently has the Focus (i.e. the keyboard input), then the Enter key will move to the next line in the control. Setting the MultiLine property to False will mean that the parent Form will handle the Enter key instead, allowing it to be used for (for example) the default button (See Push Button's SetDefault function).

Values

True | Sets the edit control to be a multi-line control.
False | Sets the edit control to be a multi-line control.

MultiLine Edit controls


SetTextColour

SetTextColour (sRed, sGreen, sBlue)

This method is used to set the text colour of this edit control.

Parameters

sRed | The red component of the colour to set the text to (0 - 255).
sGreen | The green component of the colour to set the text to (0 - 255).
sBlue | The blue component of the colour to set the text to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two edit controls' text colours to red and green, respectively.

form1.edit1.SetTextColour 255, 0, 0

form1.edit2.SetTextColour 0, 255, 0

SetTextColour Edit controls > See Also


SetBackgroundColour

SetBackgroundColour (sRed, sGreen, sBlue)

This method is used to set the background colour of this edit control.

Parameters

sRed | The red component of the colour to set the background to (0 - 255).
sGreen | The green component of the colour to set the background to (0 - 255).
sBlue | The blue component of the colour to set the background to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two edit controls' background colours to black and white, respectively.

form1.edit1.SetBackgroundColour 0, 0, 0

form1.edit2.SetBackgroundColour 255, 255, 255

SetBackgroundColour Edit controls > See Also


SetFont

SetFont (strFontName, sSize, sStyle)

This method can be called to set the font of the text in an edit control.

Parameters

strFontName | The name of the font. This can be any one of the standard Windows font names, such as "Arial", "Courier", etc.
sSize | The size of the font, in points. The default font size is the same as the system font (usually 10-points).
sStyle | The style of the font to set. It can have any combination of the styles listed under Font Styles below.

Return value

This method has no return value.

Font Styles

The following font styles, or combinations of styles, are allowed for the sStyle parameter:

fontBold | 1 | Sets the font to be Bold.
fontItalic | 2 | Sets the font to be italic.

Example

Use the following line to set the font of an edit control to a 10-point, italic, "MS Sans Serif" font.

form.edit2.SetFont "MS sans Serif", 10, 2

SetFont Edit controls


SetFocus

SetFocus ()

This method can be called to set the focus to this edit control (i.e. make it the control that currently handles keyboard input).

Giving the focus to a control will remove the focus from any control which has previously been given it.

Parameters

This method has no parameters.

Return value

This method has no return value.

Example

Use the following line to set the focus to a previously-created edit control.

form.Edit1.SetFocus()

SetFocus Edit controls > See Also


HasFocus

HasFocus ()

This method can be called to determine whether a control currently has the focus.

Parameters

This method has no parameters.

Return value

This method returns True .

Example

Use the following line to determine whether a previously-created edit control has the focus.

If form.MyEdit1.HasFocus() Then

' Do something here

End If

HasFocus Push buttons > See Also


Static (text) controls

Static controls are simple controls that display single or multiple lines of text.

Creation

A static control can be created using the form's AddStatic method. This method takes as one of its parameters the name of the static, which is then used throughout the script when referring to this control.

For example

form.AddStatic "static1",

"This is a line of informative text"

would mean that all properties and methods of this edit control would be called by simply prefixing them with

form.static1.

Properties

Visible

Enabled

XPos

YPos

Width

Height

Methods

SetTextColour

SetBackgroundColour

SetFont

Events

Static controls do not fire events.

Static (text) controls ScriptDlg reference > See Also


Visible

Description

This property specifies whether the static control should be visible or invisible.

This can be useful if different selections in other controls (for example, drop-lists or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

A static control is visible by default.

Values

True | Sets the static control to be visible.
False | Sets the static control to be invisible.

Visible Static (text) controls > See Also


Enabled

Description

This property specifies whether the static control should be enabled or disabled.

A static control is enabled by default.

Values

True | Sets the static control to be enabled.
False | Sets the static control to be disabled.

Enabled Static (text) controls > See Also


XPos

Description

This property represents the X position of the static control, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddStatic is used, then the static control will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos Static (text) controls > See Also


YPos

Description

This property represents the Y position of the static control, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddStatic is used, then the static control will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos Static (text) controls > See Also


Width

Description

This property represents the width of the static control, in pixels.

If this property is not explicitly specified, either using this property or when AddStatic is used, then the static control will be sized to fit the current text (specified using Text, or originally with AddStatic). In this case, any changes to the text may result in the static control changing size.

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width Static (text) controls > See Also


Height

Description

This property represents the height of the static control, in pixels.

If this property is not explicitly specified, either using this property or when AddStatic is used, then the static control will be sized to fit the current text (specified using Text, or originally with AddStatic). In this case, any changes to the text may result in the static control changing size.

Values

Any numerical value greater than 0 can be used.

If the height specified will take this control beyond the bottom of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Height Static (text) controls > See Also


Text

Description

This property represents the text of the static control.

Values

Any string can be used as the static control's text.

Text Static (text) controls > See Also


Alignment

Description

This property represents the alignment of the text within the static control.

It can be any combination of horizontal alignments, and vertical alignments. Note that if more than one horizontal alignment is specified, the first one from the list below will be used. Similarly, if more than one vertical alignment is specified, the first one will be used.

The default alignment for the text in a static control is at the top left.

Values

alignLeft | 1 | Sets the text in the static control to be horizontally aligned to the left of the control.
alignHCentre | 2 | Sets the text in the static control to be horizontally aligned in the centre of the control.
alignRight | 4 | Sets the text in the static control to be horizontally aligned to the right of the control.
alignTop | 8 | Sets the text in the static control to be vertically aligned at the top of the control.
alignVCentre | 16 | Sets the text in the static control to be vertically aligned in the centre of the control.
alignBottom | 32 | Sets the text in the static control to be vertically aligned at the bottom of the control.

Alignment Static (text) controls


SetTextColour

SetTextColour (sRed, sGreen, sBlue)

This method is used to set the text colour of this static control.

Parameters

sRed | The red component of the colour to set the text to (0 - 255).
sGreen | The green component of the colour to set the text to (0 - 255).
sBlue | The blue component of the colour to set the text to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two static controls' text colours to red and green, respectively.

form1.static1.SetTextColour 255, 0, 0

form1.static2.SetTextColour 0, 255, 0

SetTextColour Static (text) controls > See Also


SetBackgroundColour

SetBackgroundColour (sRed, sGreen, sBlue)

This method is used to set the background colour of this static control.

Parameters

sRed | The red component of the colour to set the background to (0 - 255).
sGreen | The green component of the colour to set the background to (0 - 255).
sBlue | The blue component of the colour to set the background to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two static controls' background colours to blue and red, respectively.

form1.static1.SetBackgroundColour 0, 0, 255

form1.static2.SetBackgroundColour 255, 0, 0

SetBackgroundColour Static (text) controls > See Also


SetFont

SetFont (strFontName, sSize, sStyle)

This method can be called to set the font of the text in an edit control.

Parameters

strFontName | The name of the font. This can be any one of the standard Windows font names, such as "Arial", "Courier", etc.
sSize | The size of the font, in points. The default font size is the same as the system font (usually 10-points).
sStyle | The style of the font to set. It can have any combination of the styles listed under Font Styles below.

Return value

This method has no return value.

Font Styles

The following font styles, or combinations of styles, are allowed for the sStyle parameter:

fontBold | 1 | Sets the font to be Bold.
fontItalic | 2 | Sets the font to be italic.

Example

Use the following line to set the font of an edit control to a 10-point, italic, "MS Sans Serif" font.

form.edit2.SetFont "MS sans Serif", 10, 2

SetFont Static (text) controls


Check boxes

Check boxes give the user an On/Off or True/False type of selection.

Creation

A check box can be created using the form's AddCheckBox method. This method takes as one of its parameters the name of the check box, which is then used throughout the script when referring to this check box.

For example

form.AddCheckBox "checkbox2", "On/Off"

would mean that all properties and methods of this check box would be called by simply prefixing them with

form.checkbox2.

Properties

Visible

Enabled

XPos

YPos

Width

Height

Text

TabStop

Checked

Methods

SetTextColour

SetBackgroundColour

SetFont

SetEvent_OnClick

Events

OnClick

Check boxes ScriptDlg reference > See Also


Visible

Description

This property specifies whether the check box should be visible or invisible.

This can be useful if different selections in other controls (for example, drop-lists or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

A check box is visible by default.

An invisible check box cannot fire events.

Values

True | Sets the check box to be visible.
False | Sets the check box to be invisible.

Visible Check boxes > See Also


Enabled

Description

This property specifies whether the check box should be enabled or disabled.

A check box is enabled by default.

A disabled check box cannot fire any events.

Values

True | Sets the check box to be enabled.
False | Sets the check box to be disabled.

Enabled Check boxes > See Also


XPos

Description

This property represents the X position of the check box, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddCheckBox is used, then the check box will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos Check boxes > See Also


YPos

Description

This property represents the Y position of the check box, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddCheckBox is used, then the check box will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos Check boxes > See Also


Width

Description

This property represents the width of the check box, in pixels.

If this property is not explicitly specified, either using this property or when AddCheckBox is used, then the control will be sized to fit the current text and check box (specified using Text, or originally with AddCheckBox).

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width Check boxes > See Also


Height

Description

This property represents the height of the check box, in pixels.

If this property is not explicitly specified, either using this property or when AddCheckBox is used, then the check box will be sized to fit the current text (specified using Text, or originally with AddCheckBox).

Values

Any numerical value greater than 0 can be used.

If the height specified will take this control beyond the bottom of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Height Check boxes > See Also


Text

Description

This property represents the text on the check box.

Values

Any string can be used as the check box's text.

Text Check boxes > See Also


TabStop

Description

This property specifies whether the check box should have the "TabStop" property.

A check box with the TabStop property set to True will get the focus as the TAB key is used to move through the controls on the form.

By default, check boxes have the TabStop property set to True.

Values

True | Sets the check box to have the TabStop property.
False | Specifies that the check box should not have the TabStop property.

TabStop Check boxes


Checked

Description

This property sets or returns the current checked state of the check box.

Values

True | The check box is enabled.
False | The check box is disabled.

Checked Check boxes


TooltipText

Description

This property represents the Tooltip text for the check box. This is text displayed in a small pop-up window when the mouse pointer is held over the control. It is usually used to contain a brief description of the purpose of the control.

Values

Any string can be used as the Tooltip text, up to a maximum of 80 characters.

TooltipText Check boxes


SetTextColour

SetTextColour (sRed, sGreen, sBlue)

This method is used to set the text colour of this check box.

Parameters

sRed | The red component of the colour to set the text to (0 - 255).
sGreen | The green component of the colour to set the text to (0 - 255).
sBlue | The blue component of the colour to set the text to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two check boxes' text colours to blue and green, respectively.

form1.checkbox1.SetTextColour 0, 0, 255

form1.checkbox2.SetTextColour 0, 255, 0

SetTextColour Check boxes > See Also


SetBackgroundColour

SetBackgroundColour (sRed, sGreen, sBlue)

This method is used to set the background colour of this check box.

Parameters

sRed | The red component of the colour to set the background to (0 - 255).
sGreen | The green component of the colour to set the background to (0 - 255).
sBlue | The blue component of the colour to set the background to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two check boxes' background colours to white and black, respectively.

form1.checkbox1.SetBackgroundColour 255, 255, 255

form1.checkbox2.SetBackgroundColour 0, 0, 0

SetBackgroundColour Check boxes > See Also


SetFont

SetFont (strFontName, sSize, sStyle)

This method can be called to set the font of the text on a check box.

Parameters

strFontName | The name of the font. This can be any one of the standard Windows font names, such as "Arial", "Courier", etc.
sSize | The size of the font, in points. The default font size is the same as the system font (usually 10-points).
sStyle | The style of the font to set. It can have any combination of the styles listed under Font Styles below.

Return value

This method has no return value.

Font Styles

The following font styles, or combinations of styles, are allowed for the sStyle parameter:

fontBold | 1 | Sets the font to be Bold.
fontItalic | 2 | Sets the font to be italic.

Example

Use the following line to set the font of a check box to a 10-point, italic, "MS Sans Serif" font.

form.checkbox3.SetFont "MS sans Serif", 12, 3

SetFont Check boxes


SetFocus

SetFocus ()

This method can be called to set the focus to this check box (i.e. make it the control that currently handles keyboard input). This means that pressing the space bar will toggle whether the check box is currently checked.

Giving the focus to a control will remove the focus from any control which has previously been given it.

Parameters

This method has no parameters.

Return value

This method has no return value.

Example

Use the following line to set the focus to a previously-created check box.

form.SelectedCheckBox.SetFocus()

SetFocus Check boxes > See Also


HasFocus

HasFocus ()

This method can be called to determine whether a control currently has the focus.

Parameters

This method has no parameters.

Return value

This method returns True .

Example

Use the following line to determine whether a previously-created check box has the focus.

If form.MyCheckBox.HasFocus() Then

' Do something here

End If

HasFocus Check boxes > See Also


SetEvent_OnClick

SetEvent_OnClick (eventref)

This method is used to specify the function that will be called when a check box is clicked.

See OnClick event for details of the event function.

The form's event handler MUST have been initialised using InitEventHandler before any events will fire.

Parameters

eventref

A reference to the event function to be called when the check box is clicked. This must be passed in the form GetRef ("button3_OnClick").

Return value

This method has no return value.

Example

The following code snippet will create a form, initialize it so that events will be fired, create a check box, and set an event that is fired when the check box is clicked.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

form1.AddCheckBox "checkbox1", "Checked or not?"

form1.checkbox1.SetEvent_OnClick GetRef("checkbox1_OnClick")

form1.Display()

Sub checkbox1_OnClick()

If form1.checkbox1.Checked Then

MsgBox "The check box is now checked!"

Else

MsgBox "The check box is now unchecked!"

End If

End Sub

SetEvent_OnClick Check boxes > See Also


OnClick event

The OnClick event will be fired when a check box is clicked.

To tell the check box which event function to call when it is clicked, use the SetEvent_OnClick method.

The OnClick event function may have any name, but must have the following format:

Sub checkbox_OnClick()

' Do your processing here

End Sub

Parameters

This event function has no parameters.

Return value

This event function has no return value.

OnClick event Check boxes > See Also


Radio buttons

Radio buttons give the user the ability to select one of a number of choices.

All the choices in a group of radio buttons are mutually exclusive.

By default, all the radio buttons on a form are in the same group. To find out how to specify more groups, see StartButtonGroup.

Creation

A radio button can be created using the form's AddRadioButton method. This method takes as one of its parameters the name of the control, which is then used throughout the script when referring to this radio button.

For example

form.AddRadioButton "radio2", "On/Off"

would mean that all properties and methods of this radio button would be called by simply prefixing them with

form.radio2.

Properties

Visible

Enabled

XPos

YPos

Width

Height

Text

TabStop

Checked

Methods

SetTextColour

SetBackgroundColour

SetFont

SetEvent_OnClick

Events

OnClick

Radio buttons ScriptDlg reference > See Also


Visible

Description

This property specifies whether the radio button should be visible or invisible.

This can be useful if different selections in other controls (for example, drop-lists or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

A radio button is visible by default.

An invisible radio button cannot fire events.

Values

True | Sets the radio button to be visible.
False | Sets the radio button to be invisible.

Visible Radio buttons > See Also


Enabled

Description

This property specifies whether the radio button should be enabled or disabled.

A radio button is enabled by default.

A disabled radio button cannot fire any events.

Values

True | Sets the radio button to be enabled.
False | Sets the radio button to be disabled.

Enabled Radio buttons > See Also


XPos

Description

This property represents the X position of the radio button, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddRadioButton is used, then the radio button will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos Radio buttons > See Also


YPos

Description

This property represents the Y position of the radio button, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddRadioButton is used, then the radio button will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos Radio buttons > See Also


Width

Description

This property represents the width of the radio button, in pixels.

If this property is not explicitly specified, either using this property or when AddRadioButton is used, then the control will be sized to fit the current text and radio button part (specified using Text, or originally with AddCheckBox). In this case, any changes to the text may result in the radio button changing size.

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width Radio buttons > See Also


Height

Description

This property represents the height of the radio button, in pixels.

If this property is not explicitly specified, either using this property or when AddRadioButton is used, then the radio button will be sized to fit the current text (specified using Text, or originally with AddRadioButton). In this case, any changes to the text may result in the radio button changing size.

Values

Any numerical value greater than 0 can be used.

If the height specified will take this control beyond the bottom of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Height Radio buttons > See Also


Text

Description

This property represents the text on the radio button.

Values

Any string can be used as the check box's text.

Text Radio buttons > See Also


TabStop

Description

This property specifies whether the radio button should have the "TabStop" property.

A radio button with the TabStop property will get the focus as the TAB key is used to move through the controls on the form.

By default, radio buttons have the TabStop property set to True.

Values

True | Sets the radio button to have the TabStop property.
False | Specifies that the radio button should not have the TabStop property.

TabStop Radio buttons


Checked

Description

This property sets or returns the current checked state of the radio button.

Only one radio button in a group acn be checked at once. To find out how to group radio buttons, see StartButtonGroup.

Values

True | The radio button is enabled.
False | The radio button is disabled.

Checked Radio buttons


TooltipText

Description

This property represents the Tooltip text for the radio button. This is text displayed in a small pop-up window when the mouse pointer is held over the control. It is usually used to contain a brief description of the purpose of the control.

Values

Any string can be used as the Tooltip text, up to a maximum of 80 characters.

TooltipText Radio buttons


SetTextColour

SetTextColour (sRed, sGreen, sBlue)

This method is used to set the text colour of this radio button.

Parameters

sRed | The red component of the colour to set the text to (0 - 255).
sGreen | The green component of the colour to set the text to (0 - 255).
sBlue | The blue component of the colour to set the text to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two radio buttons' text colours to blue and green, respectively.

form1.radio1.SetTextColour 0, 0, 255

form1.radio2.SetTextColour 0, 255, 0

SetTextColour Radio buttons > See Also


SetBackgroundColour

SetBackgroundColour (sRed, sGreen, sBlue)

This method is used to set the background colour of this radio button.

Parameters

sRed | The red component of the colour to set the background to (0 - 255).
sGreen | The green component of the colour to set the background to (0 - 255).
sBlue | The blue component of the colour to set the background to (0 - 255).

To get the red/green/blue components of colours, you can use any program that allows colour changing. For example, open the Paint program that comes with Windows, double-click on a colour from the palette at the bottom of the screen, and select "Define Custom Colors".

Return value

This method has no return value.

Example

The following code will set two radio buttons' background colours to white and black, respectively.

form1.radio1.SetBackgroundColour 255, 255, 255

form1.radio2.SetBackgroundColour 0, 0, 0

SetBackgroundColour Radio buttons > See Also


SetFont

SetFont (strFontName, sSize, sStyle)

This method can be called to set the font of the text on a radio button.

Parameters

strFontName | The name of the font. This can be any one of the standard Windows font names, such as "Arial", "Courier", etc.
sSize | The size of the font, in points. The default font size is the same as the system font (usually 10-points).
sStyle | The style of the font to set. It can have any combination of the styles listed under Font Styles below.

Return value

This method has no return value.

Font Styles

The following font styles, or combinations of styles, are allowed for the sStyle parameter:

fontBold | 1 | Sets the font to be Bold.
fontItalic | 2 | Sets the font to be italic.

Example

Use the following line to set the font of a radio button to a 12-point, bold and italic, "Arial" font.

form.radio3.SetFont "Arial", 12, 3

SetFont Radio buttons


SetFocus

SetFocus ()

This method can be called to set the focus to this radio button (i.e. make it the control that currently handles keyboard input). This means that pressing the space bar will toggle whether the radio button is currently checked.

Giving the focus to a control will remove the focus from any control which has previously been given it.

Parameters

This method has no parameters.

Return value

This method has no return value.

Example

Use the following line to set the focus to a previously-created radio button.

form.Radio2.SetFocus()

SetFocus Radio buttons > See Also


HasFocus

HasFocus ()

This method can be called to determine whether a control currently has the focus.

Parameters

This method has no parameters.

Return value

This method returns True .

Example

Use the following line to determine whether a previously-created radio button has the focus. This can be used in an OnClick event handler, for example, to determine which radio button was actually clicked.

If form.MyRadioButton.HasFocus() Then

' Do something here

End If

HasFocus Radio buttons > See Also


SetEvent_OnClick

SetEvent_OnClick (eventref)

This method is used to specify the function that will be called when a radio button is clicked.

See OnClick event for details of the event function.

The form's event handler MUST have been initialised using InitEventHandler before any events will fire.

Parameters

eventref

A reference to the event function to be called when the check box is clicked. This must be passed in the form GetRef ("radio3_OnClick").

Return value

This method has no return value.

Example

The following code snippet will create a form, initialize it so that events will be fired, create two radio buttons, and set an event that is fired when the first radio button is clicked.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

form1.AddRadioButton "radio1", "Square"

form1.AddRadioButton "radio2", "Circle"

form1.radio1.SetEvent_OnClick GetRef("radio1_OnClick")

form1.Display()

Sub radio1_OnClick()

MsgBox "All squared up!"

End Sub

SetEvent_OnClick Radio buttons > See Also


OnClick event

The OnClick event will be fired when a radio button is clicked.

To tell the radio button which event function to call when it is clicked, use the SetEvent_OnClick method.

The OnClick event function may have any name, but must have the following format:

Sub radiobutton_OnClick()

' Do your processing here

End Sub

Parameters

This event function has no parameters.

Return value

This event function has no return value.

OnClick event Radio buttons > See Also


Slider controls

Slider controls allow the user to make a selection by sliding a pointer along a scale.

Creation

A slider control can be created using the form's AddSlider method. This method takes as one of its parameters the name of the slider, which is then used throughout the script when referring to this control.

For example

form.AddSlider "slider", 100, 20

would mean that all properties and methods of this slider control would be called by simply prefixing them with

form.slider.

Properties

Visible

Enabled

XPos

YPos

Width

Height

TabStop

Vertical

CurPos

NumTicks

Methods

SetEvent_OnPosChanged

Events

OnPosChanged

Slider controls ScriptDlg reference > See Also


Visible

Description

This property specifies whether the slider control should be visible or invisible.

This can be useful if different selections in other controls (for example, drop-lists or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

A slider control is visible by default.

An invisible slider control cannot fire events.

Values

True | Sets the slider control to be visible.
False | Sets the slider control to be invisible.

Visible Slider controls > See Also


Enabled

Description

This property specifies whether the slider control should be enabled or disabled.

A slider control is enabled by default.

A disabled slider control cannot fire any events.

Values

True | Sets the slider control to be enabled.
False | Sets the slider control to be disabled.

Enabled Slider controls > See Also


XPos

Description

This property represents the X position of the slider control, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddSlider is used, then the slider will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos Slider controls > See Also


YPos

Description

This property represents the Y position of the slider control, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddSlider is used, then the slider will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos Slider controls > See Also


Width

Description

This property represents the width of the slider control, in pixels.

If this property is not explicitly specified, either using this property or when AddSlider is used, then the slider control will be sized automatically. If the slider is horizontal (see Vertical property), the size will depend on the current range (see SetRange) and the number of ticks.

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width Slider controls > See Also


Height

Description

This property represents the height of the slider control, in pixels.

If this property is not explicitly specified, either using this property or when AddSlider is used, then the slider control will be sized automatically. If the slider is vertical (see Vertical property), the size will depend on the current range (see SetRange) and the number of ticks.

Values

Any numerical value greater than 0 can be used.

If the height specified will take this control beyond the bottom of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Height Slider controls > See Also


TabStop

Description

This property specifies whether the slider control should have the "TabStop" property.

A slider control with the TabStop property will get the focus as the TAB key is used to move through the controls on the form.

By default, slider controls have the TabStop property set to True.

Values

True | Sets the slider control to have the TabStop property.
False | Specifies that the slider control should not have the TabStop property.

TabStop Slider controls


Vertical

Description

This property specifies whether the slider control should be vertical or horizontal.

A slider is horizontal by default.

Values

True | Sets the slider to be vertical
False | Sets the slider to be horizontal.

Vertical Slider controls


CurPos

Description

This property sets or returns the current position of the slider control.

Values

Any whole number within the limits specified by SetRange is allowed.

CurPos Slider controls > See Also


NumTicks

Description

This property sets or returns the number of ticks on the slider control.

Values

Any whole number between 2 and 1000 is allowed.

NumTicks Slider controls


TooltipText

Description

This property represents the Tooltip text for the slider control. This is text displayed in a small pop-up window when the mouse pointer is held over the control. It is usually used to contain a brief description of the purpose of the control.

Values

Any string can be used as the Tooltip text, up to a maximum of 80 characters.

TooltipText Slider controls


SetRange

SetRange (sMin, sMax)

This method is used to set the range of values for a slider control.

Parameters

sMin | The start of the range to set
sMax | The end of the range to set.

Return value

This method has no return value.

SetRange Slider controls > See Also


GetRange

GetRange (sMin, sMax)

This method is used to get the current range of values of a slider control.

Parameters

sMin | After this method is called, this parameter will hold the slider control's current minimum value.
sMax | After this method is called, this parameter will hold the slider control's current maximum value.

Return value

This method has no return value.

GetRange Slider controls > See Also


SetFocus

SetFocus ()

This method can be called to set the focus to this slider (i.e. make it the control that currently handles keyboard input). This means that using the arrow keys, or Page Up and Page Down, will cause the slider control's position to change.

Giving the focus to a control will remove the focus from any control which has previously been given it.

Parameters

This method has no parameters.

Return value

This method has no return value.

Example

Use the following line to set the focus to a previously-created slider control.

form.FrequencySlider.SetFocus()

SetFocus Check boxes


SetEvent_OnPosChanged

SetEvent_OnPosChanged (eventref)

This method is used to specify the function that will be called when the slider's position is changed..

See OnPosChanged event for details of the event function.

The form's event handler MUST have been initialised using InitEventHandler before any events will fire.

Parameters

eventref

A reference to the event function to be called when the slider's position changes. This must be passed in the form GetRef ("button3_OnClick").

Return value

This method has no return value.

Example

The following code snippet will create a form, initialize it so that events will be fired, create a slider, and set an event that is fired when the slider's position changes.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

form1.AddSlider "slider1", 300, 40, 5, 5

form1.slider1.SetEvent_OnPosChanged

GetRef("slider1_OnPosChanged")

form1.slider1.SetRange 0, 50

form1.slider1.CurPos = 25

form1.Display()

Sub slider1_OnPosChanged()

MsgBox "Current slider position is " &

form1.slider1.CurPos

End Sub

SetEvent_OnPosChanged Slider controls > See Also


OnPosChanged event

The OnPosChanged event will be fired when a slider's position changes.

To tell the slider control which event function to call when its position changes, use the SetEvent_OnPosChanged method.

The OnPosChanged event function may have any name, but must have the following format:

Sub slider_OnPosChanged()

' Do your processing here

End Sub

Parameters

This event function has no parameters.

Return value

This event function has no return value.

OnPosChanged event Slider controls > See Also


Drop-list controls

Drop-list controls allow the user to make a selection by choosing an item from a list that drops down to reveal the choices available.

Creation

A drop-list control can be created using the form's AddDropList method. This method takes as one of its parameters the name of the drop-list, which is then used throughout the script when referring to this control.

For example

form.AddDropList "Selection1", 100, -1

would mean that all properties and methods of this drop-list control would be called by simply prefixing them with

form.Selection1.

Properties

Visible

Enabled

XPos

YPos

Width

TabStop

Sorted

NumStrings

CurSel

TooltipText

Methods

SetEvent_OnSelChanged

AddString

GetString

RemoveAllStrings

DeleteString

SetItemData

GetItemData

Events

OnSelChanged

Drop-list controls ScriptDlg reference > See Also


Visible

Description

This property specifies whether the drop-list control should be visible or invisible.

This can be useful if different selections in other controls (for example, other drop-lists or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

A drop-list control is visible by default.

Values

True | Sets the drop-list control to be visible.
False | Sets the drop-list control to be invisible.

Visible Drop-list controls > See Also


Enabled

Description

This property specifies whether the drop-list control should be enabled or disabled.

A drop-list control is enabled by default.

Values

True | Sets the drop-list control to be enabled.
False | Sets the drop-list control to be disabled.

Enabled Drop-list controls > See Also


XPos

Description

This property represents the X position of the drop-list control, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddDropList is used, then the drop-list control will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos Drop-list controls > See Also


YPos

Description

This property represents the Y position of the drop-list control, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddDropList is used, then the drop-list control will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos Drop-list controls > See Also


Width

Description

This property represents the width of the drop-list control, in pixels.

If this property is not explicitly specified, either using this property or when AddDropList is used, then the drop-list control will be sized to fit the widest text entered in the drop-list. In this case, adding or deleting strings (using AddString, DeleteString or RemoveAllStrings) may result in the drop-list control changing size.

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width Drop-list controls > See Also


TabStop

Description

This property specifies whether the drop-list control should have the "TabStop" property.

A drop-list control with the TabStop property will get the focus as the TAB key is used to move through the controls on the form.

By default, drop-list controls have the TabStop property set to True.

Values

True | Sets the drop-list control to have the TabStop property.
False | Specifies that the drop-list control should not have the TabStop property.

TabStop Drop-list controls


Sorted

Description

This property specifies whether the drop-list control should be sorted.

If the drop-list control is sorted, then strings added to the control will be displayed in alphabetical order in the drop-list, regardless of the order in which they are added. Otherwise, strings will be displayed in the order that they were added.

By default, drop-list controls are not sorted..

Values

True | Sets the drop-list control to be sorted.
False | Specifies that the drop-list control should not be sorted.

Sorted Drop-list controls


NumStrings

Description

This read-only property can be used to find out the number of strings in the drop-list control.

The index of the last string in the drop-list will be (NumStrings-1).

NumStrings Drop-list controls


CurSel

Description

This property represents the zero-based index of the currently selected string in a drop-list.

Values

Any numerical value is valid, between 0 and NumStrings-1 inclusive..

CurSel Drop-list controls


TooltipText

Description

This property represents the Tooltip text for the drop-list control. This is text displayed in a small pop-up window when the mouse pointer is held over the control. It is usually used to contain a brief description of the purpose of the control.

Values

Any string can be used as the Tooltip text, up to a maximum of 80 characters.

TooltipText Drop-list controls


AddString

AddString (strString [, ItemData])

This method is used to add a string to a drop-list.

If the drop-list is sorted, this string will be inserted into the list in alphabetical order once the control has been created. Otherwise, it will be added at the end of the list.

Parameters

strString | The string to add to the drop-list.
lItemData | Optional parameter specifying a long integer which can be associated with this string in the list. For example, in a list of sample rates, you may wish to associate the sample rate itself with the string containing its description (see example below).

Return value

This method has no return value.

Example

The following example creates a drop-list and adds a series of sample rate selections to it. Each entry contains the actual sample rate as its item data.

form1.AddDropList "SampleRate", 120

form1.SampleRate.SetEvent_OnSelChanged GetRef ("SampleRate_OnSelChanged")

form1.SampleRate.AddString "32kHz", 32000

form1.SampleRate.AddString "44.1kHz", 44100

form1.SampleRate.AddString "48kHz", 48000

form1.SampleRate.AddString "88.2kHz", 88200

form1.SampleRate.AddString "96kHz", 96000

Sub SampleRate_OnSelChanged

sCurSel = form1.SampleRate.CurSel

form1.SampleRate.GetItemData sCurSel, lSampleRate

MsgBox "You selected a sample rate of " & lSampleRate

End Sub

AddString Drop-list controls > See Also


GetString

GetString (sIndex, strString)

This method is used to get the string at the given index in a drop-list.

If the drop-list is sorted, this string will be inserted into the list in alphabetical order once the control has been created. Otherwise, it will be added at the end of the list.

Parameters

sIndex | The zero-based index into the drop-list to get the string at. This must be a number between 0 and NumStrings-1.
strString | After this method is called, this parameter will hold the string at the given index in the drop-list.

Return value

This method has no return value.

GetString Drop-list controls > See Also


DeleteString

DeleteString (sIndex)

This method is used to delete the string at the given index in the drop-list.

If the string deleted is the currently selected string, the next string in the drop-list will be selected automatically (or the previous string, if it was the last one in the list).

Parameters

sIndex

The zero-based index into the drop-list to delete the string at. This must be a number between 0 and NumStrings-1.

Return value

This method has no return value.

DeleteString Drop-list controls > See Also


RemoveAllStrings

RemoveAllStrings ()

This method is used to delete all strings from a drop-list.

Parameters

This method has no parameters.

Return value

This method has no return value.

RemoveAllStrings Drop-list controls > See Also


SetItemData

SetItemData (sIndex, lItemData)

This method is used to set the item data for a given entry in the drop-list.

Item data is a four-byte long integer value that can be associated with a string in the drop-list. You may wish to use it to store further details about the entry referred to by the string.

Parameters

sIndex | The zero-based index into the drop-list to set the item data for. This must be a number between 0 and NumStrings-1.
lItemData | After this method is called, this parameter will hold the string at the given index in the drop-list.

Return value

This method has no return value.

SetItemData Drop-list controls > See Also


GetItemData

GetItemData (sIndex, lItemData)

This method is used to get the item data for a given entry in the drop-list.

Parameters

sIndex | The zero-based index into the drop-list to set the item data for. This must be a number between 0 and NumStrings-1.
lItemData | After this method is called, this parameter will hold the item data for the string at the given index in the drop-list.

Return value

This method has no return value.

GetItemData Drop-list controls > See Also


SetFocus

SetFocus ()

This method can be called to set the focus to this drop-list (i.e. make it the control that currently handles keyboard input). This means that using the arrow keys, or Page Up and Page Down, will cause the current selection in the drop-list to change.

Giving the focus to a control will remove the focus from any control which has previously been given it.

Parameters

This method has no parameters.

Return value

This method has no return value.

Example

Use the following line to set the focus to a previously-created drop-list control.

form.MyCombo1.SetFocus()

SetFocus Drop-list controls > See Also


HasFocus

HasFocus ()

This method can be called to determine whether a control currently has the focus.

Parameters

This method has no parameters.

Return value

This method returns True .

Example

Use the following line to determine whether a previously-created drop-list has the focus.

If form.MyDropList.HasFocus() Then

' Do something here

End If

HasFocus Drop-list controls > See Also


SetEvent_OnSelChanged

SetEvent_OnSelChanged (eventref)

This method is used to specify the function that will be called when the selection in the drop-list is changed.

See OnSelChanged event for details of the event function.

The form's event handler MUST have been initialised using InitEventHandler before any events will fire.

Parameters

eventref

A reference to the event function to be called when the drop-list's selection is changed. This must be passed in the form GetRef ("DropList1_OnSelChange").

Return value

This method has no return value.

Example

The following code snippet will create a form, initialize it so that events will be fired, create a drop-list, add some strings to it, and set an event that is fired when the current selection changes.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

form1.AddDropList "DropList1", 200, 5, 5

form1.DropList1.SetEvent_OnSelChanged

GetRef("DropList1_OnSelChanged")

form1.DropList1.AddString "item 1"

form1.DropList1.AddString "item 2"

form1.DropList1.AddString "item 3"

form1.Display()

Sub DropList1_OnPosChanged()

MsgBox "Current selection is " &

form1.DropList1.CurSel

End Sub

SetEvent_OnSelChanged Drop-list controls > See Also


OnSelChanged event

The OnSelChanged event will be fired when the user changes the selection in a drop-list control. The item selected can be found using the CurSel property

To tell the drop-list control which event function to call when its position changes, use the SetEvent_OnSelChanged method.

The OnSelChanged event function may have any name, but must have the following format:

Sub droplist_OnSelChanged()

' Do your processing here

End Sub

Parameters

This event function has no parameters.

Return value

This event function has no return value.

OnSelChanged event Slider controls > See Also


List box controls

List box controls allow the user to make a selection by choosing an item from a list.

Creation

A list box control can be created using the form's AddListBox method. This method takes as one of its parameters the name of the list box, which is then used throughout the script when referring to this control.

For example

form.AddListBox "MyListBox", 200, 100

would mean that all properties and methods of this list box control would be called by simply prefixing them with

form.MyListBox.

Properties

Visible

Enabled

XPos

YPos

Width

TabStop

Sorted

NumStrings

CurSel

TooltipText

Methods

SetEvent_OnSelChanged

SetEvent_OnDoubleClick

AddString

GetString

RemoveAllStrings

DeleteString

SetItemData

GetItemData

Events

OnSelChanged

OnDoubleClick

List box controls ScriptDlg reference > See Also


Visible

Description

This property specifies whether the list box control should be visible or invisible.

This can be useful if different selections in other controls (for example, other list boxes or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

A list box control is visible by default.

Values

True | Sets the list box control to be visible.
False | Sets the list box control to be invisible.

Visible List box controls > See Also


Enabled

Description

This property specifies whether the list box control should be enabled or disabled.

A list box control is enabled by default.

Values

True | Sets the list box control to be enabled.
False | Sets the list box control to be disabled.

Enabled List box controls > See Also


XPos

Description

This property represents the X position of the list box control, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddListBox is used, then the list box control will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos List box controls > See Also


YPos

Description

This property represents the Y position of the list box control, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddListBox is used, then the list box control will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos List box controls > See Also


Width

Description

This property represents the width of the list box control, in pixels.

If this property is not explicitly specified, either using this property or when AddListBox is used, then the list box control will be sized to fit the widest text entered in the list box. In this case, adding or deleting strings (using AddString, DeleteString or RemoveAllStrings) may result in the list box control changing size.

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width List box controls > See Also


TabStop

Description

This property specifies whether the list box control should have the "TabStop" property.

A list box control with the TabStop property will get the focus as the TAB key is used to move through the controls on the form.

By default, list box controls have the TabStop property set to True.

Values

True | Sets the list box control to have the TabStop property.
False | Specifies that the list box control should not have the TabStop property.

TabStop List box controls


Sorted

Description

This property specifies whether the list box control should be sorted.

If the list box control is sorted, then strings added to the control will be displayed in alphabetical order in the list box, regardless of the order in which they are added. Otherwise, strings will be displayed in the order that they were added.

By default, list box controls are not sorted..

Values

True | Sets the list box control to be sorted.
False | Specifies that the list box control should not be sorted.

Sorted Drop-list controls


NumStrings

Description

This read-only property can be used to find out the number of strings in the list box control.

The index of the last string in the list box will be (NumStrings-1).

NumStrings List box controls


CurSel

Description

This property represents the zero-based index of the currently selected string in a list box.

Values

Any numerical value is valid, between 0 and NumStrings-1 inclusive..

CurSel List box controls


TooltipText

Description

This property represents the Tooltip text for the list box control. This is text displayed in a small pop-up window when the mouse pointer is held over the control. It is usually used to contain a brief description of the purpose of the control.

Values

Any string can be used as the Tooltip text, up to a maximum of 80 characters.

TooltipText List box controls


SetEvent_OnSelChanged

SetEvent_OnSelChanged (eventref)

This method is used to specify the function that will be called when the selection in the list box is changed.

See OnSelChanged event for details of the event function.

The form's event handler MUST have been initialised using InitEventHandler before any events will fire.

Parameters

eventref

A reference to the event function to be called when the list box's selection is changed. This must be passed in the form GetRef ("ListBox1_OnSelChange").

Return value

This method has no return value.

Example

The following code snippet will create a form, initialize it so that events will be fired, create a list box, add some strings to it, and set an event that is fired when the current selection changes.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

form1.AddListBox "MyList1", 200, 5, 5

form1.MyList1.SetEvent_OnSelChanged

GetRef("MyList1_OnSelChanged")

form1.MyList1.AddString "item 1"

form1.MyList1.AddString "item 2"

form1.MyList1.AddString "item 3"

form1.Display()

Sub MyList1_OnPosChanged()

MsgBox "Current selection is " &

form1.MyList1.CurSel

End Sub

SetEvent_OnSelChanged List box controls > See Also


SetEvent_OnDoubleClick

SetEvent_OnDoubleClick (eventref)

This method is used to specify the function that will be called when an item in the list box is double-clicked.

See OnSelChanged event for details of the event function.

The form's event handler MUST have been initialised using InitEventHandler before any events will fire.

Parameters

eventref

A reference to the event function to be called when the list box's selection is changed. This must be passed in the form GetRef ("MyList1_OnSelChange").

Return value

This method has no return value.

Example

The following code snippet will create a form, initialize it so that events will be fired, create a list box, add some strings to it, and set an event that is fired when an item is double-clicked.

Set form1 = CreateObject ("ScriptDlg.Form")

form1.InitEventHandler(form1)

form1.AddDropList "MyList1", 200, 5, 5

form1.MyList1.SetEvent_OnDoubleClick

GetRef("MyList1_OnDoubleClick")

form1.MyList1.AddString "item 1"

form1.MyList1.AddString "item 2"

form1.MyList1.AddString "item 3"

form1.Display()

Sub MyList1_OnPosChanged()

MsgBox "Current selection is " &

form1.MyList1.CurSel

End Sub

SetEvent_OnDoubleClick List box controls > See Also


AddString

AddString (strString [, ItemData])

This method is used to add a string to a list box.

If the list box is sorted, this string will be inserted into the list in alphabetical order once the control has been created. Otherwise, it will be added at the end of the list.

Parameters

strString | The string to add to the list box.
lItemData | Optional parameter specifying a long integer which can be associated with this string in the list. For example, in a list of sample rates, you may wish to associate the sample rate itself with the string containing its description (see example below).

Return value

This method has no return value.

Example

The following example creates a list box and adds a series of sample rate selections to it. Each entry contains the actual sample rate as its item data.

form1.AddListBox "SampleRate", 120

form1.SampleRate.SetEvent_OnSelChanged GetRef ("SampleRate_OnSelChanged")

form1.SampleRate.AddString "32kHz", 32000

form1.SampleRate.AddString "44.1kHz", 44100

form1.SampleRate.AddString "48kHz", 48000

form1.SampleRate.AddString "88.2kHz", 88200

form1.SampleRate.AddString "96kHz", 96000

Sub SampleRate_OnSelChanged

sCurSel = form1.SampleRate.CurSel

form1.SampleRate.GetItemData sCurSel, lSampleRate

MsgBox "You selected a sample rate of " & lSampleRate

End Sub

AddString List box controls > See Also


GetString

GetString (sIndex, strString)

This method is used to get the string at the given index in a list box.

If the list box is sorted, this string will be inserted into the list in alphabetical order once the control has been created. Otherwise, it will be added at the end of the list.

Parameters

sIndex | The zero-based index into the list box to get the string at. This must be a number between 0 and NumStrings-1.
strString | After this method is called, this parameter will hold the string at the given index in the list box.

Return value

This method has no return value.

GetString List box controls > See Also


DeleteString

DeleteString (sIndex)

This method is used to delete the string at the given index in the list box.

If the string deleted is the currently selected string, the next string in the list box will be selected automatically (or the previous string, if it was the last one in the list).

Parameters

sIndex

The zero-based index into the list box to delete the string at. This must be a number between 0 and NumStrings-1.

Return value

This method has no return value.

DeleteString List box controls > See Also


RemoveAllStrings

RemoveAllStrings ()

This method is used to delete all strings from a list box.

Parameters

This method has no parameters.

Return value

This method has no return value.

RemoveAllStrings List box controls > See Also


SetItemData

SetItemData (sIndex, lItemData)

This method is used to set the item data for a given entry in the list box.

Item data is a four-byte long integer value that can be associated with a string in the list box. You may wish to use it to store further details about the entry referred to by the string.

Parameters

sIndex | The zero-based index into the list box to set the item data for. This must be a number between 0 and NumStrings-1.
lItemData | After this method is called, this parameter will hold the string at the given index in the list box.

Return value

This method has no return value.

SetItemData List box controls > See Also


GetItemData

GetItemData (sIndex, lItemData)

This method is used to get the item data for a given entry in the list box.

Parameters

sIndex | The zero-based index into the list box to set the item data for. This must be a number between 0 and NumStrings-1.
lItemData | After this method is called, this parameter will hold the item data for the string at the given index in the list box.

Return value

This method has no return value.

GetItemData List box controls > See Also


SetFocus

SetFocus ()

This method can be called to set the focus to this list box (i.e. make it the control that currently handles keyboard input). This means that using the arrow keys, or Page Up and Page Down, will cause the current selection in the list box to change.

Giving the focus to a control will remove the focus from any control which has previously been given it.

Parameters

This method has no parameters.

Return value

This method has no return value.

Example

Use the following line to set the focus to a previously-created list box control.

form.List1.SetFocus()

SetFocus List box controls > See Also


HasFocus

HasFocus ()

This method can be called to determine whether a control currently has the focus.

Parameters

This method has no parameters.

Return value

This method returns True .

Example

Use the following line to determine whether a previously-created list box has the focus.

If form.MyListBox.HasFocus() Then

' Do something here

End If

HasFocus List box controls > See Also


OnSelChanged event

The OnSelChanged event will be fired when the user changes the selection in a list box control. The item selected can be found using the CurSel property.

To tell the drop-list control which event function to call when its position changes, use the SetEvent_OnSelChanged method.

The OnSelChanged event function may have any name, but must have the following format:

Sub slider_OnSelChanged()

' Do your processing here

End Sub

Parameters

This event function has no parameters.

Return value

This event function has no return value.

OnSelChanged event List box controls > See Also


OnDoubleClick event

The OnDoubleClick event will be fired when the user double-clicks on an item in a list box control. The item that is clicked on will be the current selection and can be found using the CurSel property.

To tell the list box control which event function to call when its position changes, use the SetEvent_OnDoubleClick method.

The OnDoubleClick event function may have any name, but must have the following format:

Sub list_OnDoubleClick()

' Do your processing here

End Sub

Parameters

This event function has no parameters.

Return value

This event function has no return value.

OnDoubleClick event List box controls > See Also


Bitmap controls

Bitmap controls are simple controls that display a picture specified by a bitmap (*.bmp) file.

Creation

A bitmap control can be created using the form's AddBitmap method. This method takes as one of its parameters the name of the bitmap control, which is then used throughout the script when referring to this control.

For example

form.AddBitmap "bitmap1",

"C:\My Documents\MyPicture.bmp"

would mean that all properties and methods of this bitmap control would be called by simply prefixing them with

form.bitmap1.

Properties

Visible

XPos

YPos

Width

Height

Methods

SetBitmap

Events

Bitmap controls do not fire events.

Bitmap controls ScriptDlg reference > See Also


Visible

Description

This property specifies whether the bitmap control should be visible or invisible.

This can be useful if different selections in other controls (for example, drop-lists or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

A bitmap control is visible by default.

Values

True | Sets the bitmap control to be visible.
False | Sets the bitmap control to be invisible.

Visible Bitmap controls


XPos

Description

This property represents the X position of the bitmap control, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddBitmap is used, then the bitmap control will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos Bitmap controls > See Also


YPos

Description

This property represents the Y position of the bitmap control, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddBitmap is used, then the bitmap control will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos Bitmap controls > See Also


Width

Description

This property represents the width of the bitmap control, in pixels.

If this property is not explicitly specified, either using this property or when AddBitmap is used, then the bitmap control will be sized to fit the bitmap. In this case, selecting a different bitmap in this control may result in the bitmap control changing size.

If this property is specified, then the bitmap will be stretched or shrunk to fit into the width specified.

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width Bitmap controls > See Also


Height

Description

This property represents the height of the bitmap control, in pixels.

If this property is not explicitly specified, either using this property or when AddBitmap is used, then the bitmap control will be sized to fit the bitmap. In this case, selecting a different bitmap in this control may result in the bitmap control changing size.

If this property is specified, then the bitmap will be stretched or shrunk to fit into the height specified.

Values

Any numerical value greater than 0 can be used.

If the height specified will take this control beyond the bottom of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Height Bitmap controls > See Also


SetBitmap

SetBitmap (strBitmapFile)

This method is used to change the bitmap in this control.

Parameters

strBitmapFile

The bitmap file to show in this control.

Return value

This method has no return value.

SetBitmap Bitmap controls


Progress controls

Progress controls are simple controls that show the progress of an operation.

Creation

A progress control can be created using the form's AddProgress method. This method takes as one of its parameters the name of the progress control, which is then used throughout the script when referring to this control.

For example

form.AddProgress "Progress1"

would mean that all properties and methods of this progress control would be called by simply prefixing them with

form.Progress1.

Properties

Visible

XPos

YPos

Width

Height

Vertical

Range

CurPos

Methods

Step

Events

Progress controls do not fire events.

Progress controls ScriptDlg reference > See Also


Visible

Description

This property specifies whether the progress control should be visible or invisible.

This can be useful if different selections in other controls (for example, drop-lists or radio buttons) require a different set of controls - the unwanted controls can be hidden, and the required controls shown, depending on the selection.

A progress control is visible by default.

Values

True | Sets the progress control to be visible.
False | Sets the progress control to be invisible.

Visible Progress controls


XPos

Description

This property represents the X position of the progress control, in pixels from the left hand side of the form.

If this property is not explicitly set, either using this property or when AddProgress is used, then the progress control will be positioned to the right of the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the X position specified is greater than the current width of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the X position is less than zero, the control's X position will start beyond the left-hand side of the form.

XPos Progress controls > See Also


YPos

Description

This property represents the Y position of the progress button, in pixels from the top of the form (not including the title bar of the form).

If this property is not explicitly set, either using this property or when AddProgress is used, then the progress control will be positioned at the same Y position as the previous control, unless the NewRow method has been called since the previous control was added.

Values

Any numerical value can be used.

If the Y position specified is greater than the current height of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

If the Y position is less than zero, the control's X position will start above the top of the form.

YPos Progress controls > See Also


Width

Description

This property represents the width of the progress control, in pixels.

If this property is not explicitly specified, either using this property or when AddProgress is used, then the button will be set to a nominal size.

Values

Any numerical value greater than 0 can be used.

If the width specified will take this control beyond the right hand side of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Width Progress controls > See Also


Height

Description

This property represents the height of the progress control, in pixels.

If this property is not explicitly specified, either using this property or when AddProgress is used, then the progress control will be set to a nominal size.

Values

Any numerical value greater than 0 can be used.

If the height specified will take this control beyond the bottom of the form, and the form is set to be automatically sizeable, then the form will be resized to include this control.

Height Progress controls > See Also


Vertical

Description

This property specifies whether the progress control should be vertical or horizontal.

A progress control is horizontal by default.

Values

True | Sets the progress control to be vertical
False | Sets the progress control to be horizontal.

Vertical Progress controls


Range

Description

This property sets or returns the range of the progress control. The current position of the control (see CurPos) can be any number between 0 and this value.

The default range of the progress control is 10.

Values

Any whole number between 1 and 1000 is allowed.

Range Progress controls > See Also


CurPos

Description

This property sets or returns the current position of the progress control. It can be any number between 0 and the range of the control (see Range).

The default position of the progress control is 0.

Values

Any whole number between 0 and the range of the control is allowed.

CurPos Progress controls > See Also


Step

Step()

This method is used to step the progress control by a single step. If this would take it beyond the range specified by the Range property, the current position (See CurPos) is set to 0.

Parameters

This method has no parameters.

Return value

This method has no return value.

Example

The following code will step the progress of the progress control to the next step.

form1.Progress1.Step()

Step Progress controls


Colours

Various methods in the dScope allow you to set colours by passing a red, green and blue component. These combine to make a single colour.

Here are some examples of how these components combine to make common colours:

Colour | Red | Green | Blue
White | 255 | 255 | 255
Black | 0 | 0 | 0
Red | 255 | 0 | 0
Green | 0 | 255 | 0
Blue | 0 | 0 | 255
Magenta | 255 | 0 | 255
Yellow | 255 | 255 | 0
Cyan | 0 | 255 | 255
Light Grey | 192 | 192 | 192
Dark Grey | 128 | 128 | 128
Orange | 255 | 128 | 0

For further colours, you can use the windows colour palette. This palette is used in several programs, including the dScope, and can be accessed by right-clicking on the trace legend, selecting "Trace colour" and clicking on "Define Custom Colours". This will give you a palette of colours; clicking on any one of these will show you the red, green and blue components of that colour.


!! Example !!

Enter topic text here.

Noteworthy items are indicated like this.

 | Important warnings are designated like this.
warnflsh | This symbol designates warnings of risk of electric shock.

.

!! Example !! Scripting and OLE Automation > See Also


EXAMPLE_HEADER

Example page with Parent Link and See Also

EXAMPLE_HEADER Scripting and OLE Automation > See Also


Manual revisions

The revision history of the ScriptDlg ActiveX control is as follows:

1 | April 2002 | L. R. Elliott | Basic control descriptions
2 | 26th June 2002 | L. R. Elliott | Removed from dScope help.
3 | 3rd January 2003 | L. R. Elliott | To accompany V1.00

Manual revisions Scripting and OLE Automation > See Also


!! Method Example !!

RetVal = FunctionExample (param1, param2, param3)

This method does something wizzy in the dscope script.

Parameters

param1 | This is a parameter
param1 | This is a parameter
param2 | This is also a parameter

param1 | This is a parameter
param2 | This is also a parameter
param3 | This is another parameter

Return value

This method has no return value.

!! Method Example !! dScope Scripting Reference > See Also


!! Property Example !!

Description

This property represents the Digital Input selection.

This read-only property indicates ...

Values

DI_SOURCE_XLR | Selects the digital input to be analyzed to be the XLR input.
DI_SOURCE_BNC | Selects the digital input to be analyzed to be the BNC input.
DI_SOURCE_TOSLINK | Selects the digital input to be analyzed to be the TOSLINK (optical) input.
DI_SOURCE_GENXLR | Selects the digital input to be a direct-relay connection from the XLR digital output.
DI_SOURCE_GENBNC | Selects the digital input to be a direct-relay connection from the BNC digital output.

!! Property Example !!