Stardock DXScript 1.0 Reference
March 23, 2002
General Information
DXScript is a plug-in for DesktopX that allows the user to give scripted logic to an object. It goes even further than that by allowing you to use ActiveX controls with DesktopX objects, the end result being a truely object oriented, scripted desktop. DXScript makes use of Microsoft® Windows® Script Interfaces to accomplish this, so any ActiveX scripting engines installed, such as ActiveState’s ActivePerl or ActiveTCL, can be used. This also includes support for the languages included with systems that have IE 4 or above: VBScript and JScript.
Script Event Functions
In the previous example, you declared “Object_OnScriptEnter”, and “Object_OnScriptExit”, and they were called without your ever calling them from another area of code. This is because they are script event functions. Script event functions are functions in your script that DXScript calls in order to let it know what’s going on with the object or hosted control:
Object_OnScriptEnter
This event function is called on the start of a script. Initialization of globals, loading activex controls, etc, should be done here.
Object_OnScriptExit
This event function is called when DesktopX is unloaded, or an object is configured or deleted. Unloading of activex controls, stopping of timers, etc, should be done here.
Object_OnStateChange
Parameter: State [ie sub Object_OnStateChange(state)]
This event function is called when the state of the object hosting the script. The state parameter(a string) is the new state of the object. DesktopX internally has 7 states:
Left mouse button down: "Mouse down"
Left mouse button up: "Mouse up"
Mouse over: "Mouse over"
Mouse away: "Mouse away"
Object is being shown: "Show"
Object is being hidden: "Hide"
Object is a command object and has been clicked and released: "Command executed"
Also, custom states pass through here.
Object_OnTimer
Declared based on ID of timer set. For example if Object.SetTimer 500, 1000 was called, this function would need to be declared as Sub Object_OnTimer500
This event function is called when a timer that was set is fired. Timers are set using Object.SetTimer, and killed using Object.KillTimer. See the Object methods for more information.
Control_*
Control_DocumentComplete, Control_TitleChange…
Control_* events are fired by the control the script is hosting. See the documentation of the control for a list of supported events.
Methods and Properties
DXScript has Object, DesktopX, Script, System,and Control methods and properties, which allow you to interact with the object the script is a plugin of, and other objects on the system.
Object:
Object.Left
Object.Left = Object.Left + 10 ‘Will move the object 10 pixels to the left.
This property is used to set and retrieve the left side of the object.
Object.Right
Object.Right = Object.Right + 10 ‘Will move the object 10 pixels to the Right.
This property is used to set and retrieve the Right side of the object.
Object.Top
Object.Top = Object.Top + 10 ‘Will move the object 10 pixels vertically.
This property is used to set and retrieve the Top of the object.
Object.Bottom
Object.Bottom = Object.Bottom + 10 ‘Will move the object 10 pixels vertically.
This property is used to set and retrieve the Bottom of the object.
Object.Sleep
Object.Sleep 100 ‘sleeps for 100 milliseconds
This method is used to cause the object’s script to pause/sleep. The parameter is in milliseconds. This should be used in loops if you are checking something several times.
Object.SetTimer
Object.SetTimer 555, 10000 ‘Creates a timer with ID 555, that fires every 10 seconds
This method is used to create an event timer. For example, calling the above would cause DXScript to call the Object_OnTimer555 method of your script (see Script Event Functions for more information).
Object.KillTimer
Object.KillTimer 555 ‘Kills the timer that has the ID 555
This method is used to kill a timer that has been set. Timers should be killed when you don’t need the event to be called anymore, for example on Object_OnScriptExit.
Object.Name
Object.Name =
“Name”
MsgBox Object.Name ‘ Pops up a message box with the name of the
object
This method is used to
set and retrieve the name of the object.
Object.State
Object.State(“TheObjectName”) = “Foo” ‘Sets the state of the object to “Foo”.
MsgBox Object.State ‘ Pops a message box with the state of the object
This method is used to set and retrieve DesktopX state of the object.
Object.StatePreempt
Object.StatePreempt(“TheObjectName”) = “Foo” ‘Sets the state of the object to “Foo”.
This method is used to set the DesktopX state of the object, interrupting any other state it is currently in.
Object.Text
Object.Text = “Blah” ‘Sets the text of the object to “Blah”.
MsgBox Object.Text ‘ Pops a message box with the text of the object
This method is used to set and retrieve the text of a text based object.
Object.TextColor
Object.TextColor = RGB(0,0,0) ‘Sets the text color of the object to black.
MsgBox Object.TextColor ‘ Pops a message box with the text color of the object
This method is used to set and retrieve the text color of a text based object.
Object.Visible
Object.Visible = False ‘hide object
Object.Visible = True ‘show object
This method sets the visibility of the object.
Object.PersistStorage
Object.PersistStorage(“MyValue”) = “Foo”
MyValue = Object.PersistStorage(“MyValue”)
This method is used to save and retrieve values from the script’s dedicated storage bin. Script storage bins are used to persist data between script lifetimes (for an example, see the weather object).
Object.LocalStorage
Object.PersistStorage(“Password”) = InputBox(“Please enter the password you would like to use”)
StoredPassword = Object.PersistStorage(“Password”)
This method is the same as above, except data stored in this bin is not exported with the object the script is attached to. It should be used for data that should not be public.
Script.MsgBox
Script.MsgBox "Hello, World!"
This method is used to pop a MsgBox with scripting engines that do not support windowing themselves.
Script.MsgDbg
Script.MsgDbg "Hello, Debugger!"
This method is used to send text output to the script debugger. It can be quite useful when debugging scripts.
Control.*
Control.Navigate http://www.stardock.com/
Control.Filename = “c:\home movies\Easter Sunday.mpg”
This method allows you to access the object model of the hosted control. See the documentation of the control you are hosting for information on the control’s object model.
DesktopX.ScriptObject(phasing out, see DesktopX.ObjectByName below)
DesktopX.ScriptObject(“AnotherObjectThatHasDXScriptModule”).Visible = False
DesktopX.ScriptObject(“AnotherObjectThatHasDXScriptModule”).Control.Navigate “http://www.stardock.com”
DesktopX.ScriptObject(“SomeOtherObjectThatUsesDXScript”).State = “Animated”
This method is used to access the object model of other scripted objects. The name used to identify the script is the name the DesktopX object is given.
DesktopX.ObjectByName(to be implemented soon)
DesktopX.ObjectByName(“AnyObjectName”).Visible = False
DesktopX.ObjectByName(“AnyDXScriptObjectName”).Control.Navigate “http://www.stardock.com”
DesktopX.ObjectByName(“SomeObjectsName”).State = “Animated”
This method is used to access the object model of other objects. If the object has DXScript, the model of the script, as well as any hosted ActiveX controls will be accessible.
System.ScreenWidth
if Object.Right > System.ScreenWidth then Object.right = System.ScreenWidth
This method is used to query the screen width, in pixels.
System.ScreenHeight
if Object.Bottom > System.ScreenHeight then Object.bottom = System.ScreenHeight
This method is used to query the screen height, in pixels.
System.VScreenWidth
if Object.Right > System.VScreenWidth then Object.right = System.VScreenWidth
This method is used to query the screen width, in pixels, in a multi monitor situation.
System.VScreenHeight
if Object.Bottom > System.VScreenHeight then Object.bottom = System.VScreenHeight
This method is used to query the screen height, in pixels, in a multi monitor situation.
System.InternetConnected
if System.InternetConnected then Control.Navigate "http://www.stardock.com"
This method is used to query whether the system is currently connected to the internet, without bringing a dialup-networking request up.
DesktopX ActiveX Controls
PushButton Control
The PushButton control allows
you to use a regular pushbutton for interaction
with your
scripts.
Properties:
Caption: The text caption of the
button.
Enabled: Whether or not the button is
disabled.
Events:
OnClick: Fired when the button is
clicked
CheckBox Control
The CheckBox control allows you to use
a regular checkbox for interaction
with your
scripts.
Properties:
Caption: The text caption of the
checkbox.
Enabled: Whether or not the checkbox is disabled.
Checked:
Whether or not the checkbox is checked.
Events:
OnCheck(variant checked):
Fired when the checkbox is checked or unchecked
Edit
Control
The Edit controll allows you to support text-based user input
without dependency
on 3rd party controls.
Properties:
Text: The
text of the control.
MultiLine: Whether the control is single line or multi,
with scrollbars
ClientEdge: Whether the control has a client edge
Border:
Whether the control has a border
Events:
OnKeyPress(key): Fired when a key is entered, returns the ASCII value of the key.
Methods:
ScrollToEnd(): Scrolls to the bottom of the text.
Quick Q&A
Q: What is the difference between DXScript and DesktopX NG?
A: DXScript is an early preview of some of the features that will be showing up in DesktopX NG. DesktopX NG, however, includes support for scriptable object classes, custom script dialogs, full ActiveX control property lists, access to the appearance attributes of the object from script, and many other features.
Q: How difficult is it to write a DXScript?
A: Very simple, if you know some VBScript or JavaScript.
Introduction
DXScript brings the possibility of having script logic behind every DesktopX object. With DXScript, objects can inform you that websites have been updated, give weather reports, report information on disk usage, give you the latest news headlines, monitor stocks, and even dance around the screen with just a little scripting.
Getting Started
DXScripts run as a DesktopX module. The quickest way to get up and running is to create a new object, bring up it’s properties, select “Add” in the additional modules section, and add DXScript. Then click select it from the Additional Modules box and click ‘Configure’.
The most visible part of DXScript is the script editor. All of the scripting for a DXScript object is done in the script editor. As can be seen from the screenshot above, you can select the language of your script, edit your script, and test your script. Knowledge of VBScript or JavaScript (or another installed language, such as Perl) is required to get started.
Here’s a sample “Hello, World!” VBScript:
Sub Object_OnScriptEnter
MsgBox “Hello, World!”
End Sub
Sub Object_OnScriptExit
MsgBox “So Long, And Thanks For All The Fish!”
End Sub
Here’s the same in JavaScript:
function Object_OnScriptEnter()
{
Script.MsgBox(“Hello, World!”);
}
function Object_OnScriptExit()
{
Script.MsgBox(“So Long, And Thanks For All The Fish!”);
}
As you can see, this is quite a simple script. When you click ok, and then also ok out of the Object Properties, you’ll get a small message box of “Hello, World!”. The reason JavaScript uses Script.MsgBox is because it's a scripting language that does not have windowing methods, such as VBScript's MsgBox, so DXScript is called instead to do the task. If you delete the object, or unload DesktopX, you’ll get a message box of “So Long, And Thanks For All The Fish!” Quite simple.
Questions and bug reports
Feel free to post questions on the Stardock.desktopx.binaries.plugins newsgroup on our news server, and they will be answered as soon as conveniently possible. Bug reports should be sent to ian@stardock.com with ‘DXScript’ in the subject line.