dScope Series III Scripting and automation

Creating Custom Controls using ScriptDlg.DLL

Overview
Although VBScript is very powerful for many aspects of automation of dScope, it natively lacks any means of creating user controls. There are many instances when we would like to be able to control the settings of script, or view information in a different form. In order to be able to do this from a script, the dScope installation includes a special DLL (Dynamic Link Library) which provides the capability of creating custom controls from a dScope script.

The basics
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()

Note that you don't have to tell the dialogue where to put the controls, as it positions and sizes them automatically. It is possible to set where each control is positioned but if no position information is added, the script defaults to adding them next to each other. The whole script to do this if done in the dScope editor would look like this:

' TYPE          Automation
' LANGUAGE      VBScript
' DESCRIPTION

' *** Declarations ***
Option Explicit ' Must declare all variables before using them
Dim Form

' *** Main body of script ***
Sub dScope_Main

    ' *** TODO : Insert your code here ***
    Set form = CreateObject("ScriptDlg.Form")
    form.InitEventHandler(form)
    form.AddStatic "static1", "This is some text"
    form.AddPushButton "button1", "Click me"
    form.Display()

    ' Remove next line if script should
    ' continue responding to events
    Automation.AUT_StopScript()

End Sub ' dScope_Main


' *** Event handlers ***

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

While this looks nice, it's not actually very useful as the button doesn't do anything. To make the button do something, we need to tell the script what sub to call when it is clicked, and then define that sub. To do this we add the following line: (it goes just below the line in the script where the button has been defined)

form.button1.SetEvent_OnClick GetRef("button1_OnClick")

And then, at the end of the script in the "event handlers" section:

Sub button1_OnClick()
	MsgBox "You clicked the button!", vbinformation
End Sub

When this is done, when the button is clicked, the sub button1_OnClick() will execute and a message box will appear saying "You clicked the button!" - still not very exciting, but now the possibilities are open to do almost anything: the sub could contain dScope scripting to run a test, change dScope settings etc.

The Form
The tables below summarize the available properties and methods of the ScriptDlg form, and the available controls. Note that this is a guide to the available features rather than official documentation, for this reason the "options" listed in the controls section are not necessarily the actual names of the methods or properties, but an indication of what can be done. For details of how to use the methods and properties of the controls, please see the dScope Scripting Manual.

SCRIPTDLG FORM: PROPERTIES
XPos, YPos	X position (distance from left of screen in pixels), Y position (distance from top of screen in pixels)
Width, Height	Size of the form in pixels
Modal	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). By default the form is modeless.
IsActive	Specifies whether a modeless form (i.e. one with its Modal property set to False) is still active.
Title	The text that will appear in the title bar of the form
DynamicallyResize	Specifies whether the form should be dynamically resized as controls are added to it. By default, the form will be dynamically resizable.
VerticalSpacing	Specifies the vertical spacing between controls on the form in pixels. The default value for this property is 3 pixels.
HorizontalSpacing	Specifies the horizontal spacing between controls on the form, in pixels. The default value for this property is 3 pixels.
RunFromdScope	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.
BrowsePath	Used to set the file/folder path that the Browse dialogue box will use
BrowseTitle	Used to set the title of the Browse dialogue box
BrowseFileFilter	Used to set the file filter to use in the Browse dialogue box. This limits the types of files that will appear in the dialogue box, based on their file extensions.

SCRIPTDLG FORM: METHODS
InitEventHandler	Used to initialise the form's event handler. It must be called if the script is to respond to any button clicking, list-box selection changing, etc.
SetEvent_OnCreate	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.
SetEvent_OnClose	Used to specify the function that will be called when the form is closed.
Display	Once controls have been set up on a ScriptDlg form, this method actually displays the form.
Close	Can be called to close the form
NewRow	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.
SetFont	Set the default font for text on the form
StartButtonGroup	Start a new group of radio buttons - you will need to use this if you use more than one group of radio buttons.
Sleep	Causes the script to wait for the specified time (in milliseconds) allowing other threads to run (for example, any of the dScope program threads)
Minimize	Minimizes the form to the taskbar
Restore	Restores a minimized form
ShowHelpTopic	Opens a specified help file and displays a specified topic from it
ShowBrowseDlg	Opens a standard Windows dialogue box to allow selection of a file for opening or saving.
AddPushButton	Adds a pushbutton to the form
AddStatic	Adds a text label to the form
AddEdit	Adds an edit box for text entry to the form
AddCheckBox	Adds a checkbox to the form
AddRadioButton	Adds a radio button to the form
AddSlider	Adds a slider control to the form
AddDropList	Adds a drop list to the form
AddListBox	Adds a list box to the form
AddBitmap	Adds a bitmap to the form
AddProgress	Adds a progress bar to the form
AddScrollbar	Adds a scrollbar to the form

SCRIPTDLG FORM: EVENTS
OnCreate Event	This event fires when the form is created - it can be used to run additional steps such as populating drop lists, retrieving information etc.
OnClose Event	This event fires when the form is closed. It can be used to clean up after a test, closing files, setting objects to nothing etc.

ScriptDlg Controls
Below is a quick summary of the available controls and what they can do:

Note that this is a guide to the available features rather than official documentation, for this reason the "options" listed are not necessarily the actual names of the methods or properties, but an indication of what can be done. For details of how to use the methods and properties of the controls, please see the dScope Scripting Manual.

STATIC
Use it for:	adding text labels to forms. Despite its name, it can be dynamically updated so it is also good for showing readings and status displays.
Create it by:	AddStatic strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, visible, enabled, text, alignment, font, text colour, background colour
Example
Notes	As a script progresses, it is possible to update the text displayed by a static (this only works if the form is modeless). With the background set to black and the text colour to cyan (0, 255, 255) this makes an effective readout as above. The above example has three statics on it.

PUSH BUTTON
Use it for:	allowing the user to cause an action to happen upon the press of a button
Create it by:	AddPushButton strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, visible, enabled, text, alignment, font, text colour, background colour, tabstop, tooltip text, event, setfocus, setdefault
Example
Notes	Buttons can be enabled and disabled to prevent the user taking an inappropriate action depending on the status of the script.

EDIT BOX
Use it for:	allowing the user to enter data that can then be used in the script
Create it by:	AddPushButton strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, visible, enabled, text, alignment, font, text colour, background colour, tabstop, tooltip text, password style, read-only, multi-line, setfocus
Example
Notes	Text is read from the edit box by the script as a string (text), but it can be used to get numerical values. There is no event triggered when the contents of the edit control changes.

CHECKBOX
Use it for:	allowing the user select options that are used by the script
Create it by:	AddCheckBox strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, visible, enabled, text, font, text colour, background colour, tabstop, tooltip text, checked, set focus, set event onclick
Example
Notes	checkboxes can be set to trigger events which run when the box is checked or unchecked, or they can be read at some point in the execution of a script to determine what action to take

RADIO BUTTONS
Use it for:	allowing the user select from one of a group of mutually exclusive options
Create it by:	AddRadioButton strName, strText [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, visible, enabled, text, font, text colour, background colour, tabstop, tooltip text, checked, set focus, set event onclick
Example
Notes	Radio buttons are often used to select from a small list of mutually exclusive options. Each radio button is a separate item and has its own properties, but they are created in groups and only one of the group can be checked at a time. Radio buttons can be set to trigger events which run when the selection is changed, or they can be read at some point in the execution of a script to determine what action to take.

SLIDER
Use it for:	allowing the user to control a parameter using a sliding control
Create it by:	AddSlider strName, [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, visible, enabled, tabstop, tooltip text, vertical, current position, number of ticks, range, set focus, event on position change
Example
Notes	The position of a slider is used to determine a parameter, but it can also be changed by the script to keep up with a changing parameter.

DROP LIST
Use it for:	allowing the user to select from a longer list of options
Create it by:	AddDropList strName, [, sWidth [, sXPos [, sYPos] ] ]
Options	width, x position, y position, visible, enabled, tabstop, tooltip text, sorted, number of strings, cursel, add string, get string, delete string, remove all strings, set item data, get item data, set focus, event on selection change
Example
Notes	Drop lists can be populated by a script to dynamically create a list of options from available data such as files in a folder.

LIST BOX
Use it for:	allowing the user to select from a longer list of options while keeping more of the list visible
Create it by:	AddListBox strName, [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, visible, enabled, tabstop, tooltip text, sorted, number of strings, cursel, add string, get string, delete string, remove all strings, set item data, get item data, set focus, event on selection change
Example
Notes	List boxes are very similar to drop lists, but display more of their content continuously. Drop lists do not have a variable height property, whereas list boxes do

BITMAP
Use it for:	adding images to forms
Create it by:	AddBitmap strName, strFileName, [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, visible, set bitmap
Notes	With care can be used as a background, the path to the bitmap has to be specified as it is not embedded in the form. When distributing the form, the original bitmap must be included.

PROGRESS BAR
Use it for:	indicating the progress of a process
Create it by:	AddProgress strName, [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, visible, range, curpos, step
Example
Notes	can also be used for bargraphs to indicate the level of a parameter.

SCROLLBAR
Use it for:	controlling which subset of a large collection of data is visible
Create it by:	AddScrollBar strName, [, sWidth [, sHeight [, sXPos [, sYPos] ] ] ]
Options	height, width, x position, y position, vertical/horizontal, background colour, visible, enabled, curpos, page size, tooltip text
Example

Getting Help
The SciptDlg.dll documentation is included in the dScope help in the dScope Scripting Manual, in the "ScriptDlg ActiveX control" section. More general VBScript help is available from the Microsoft web site. The ScriptDlg methods and properties are not listed with the rest of the dScope methods and properties in the dScope edit window although they can be made available in some editors if you add ScriptDlg.DLL to the list of references. Note that there are numerous examples of ScriptDlg controls in the dScope installation as they are used for most of the applications such as AES17, Dolby and DTS tests. Any of these can be opened in the editor and the code copied or adapted. You can also email Prism Sound technical support for more assistance.