Stardock DXScript Tutorial
This is a tutorial for scripting in DesktopX using the DXScript module. I use VBScript as the language in this tutorial, but if you prefer javascript most of it is very easy to reapply. It assumes you have a small amount of knowledge of DesktopX already, namely creating objects and setting their properties. All code is in the color blue.
Table of Contents
Main
VBScript And JavaScript Basics
Addendum
Before you get started with scripting in DesktopX, you must learn the basics of a scripting language. If you feel that you already have a working knowledge of VBScript or JavaScript you can go ahead and skip this chapter.
Now is a good time to choose what language you will use. VBScript and JavaScript are both good choices, as they come with your operating system. Other languages such as Perl may be used if you feel that you are more comfortable with them. This tutorial however only covers these two languages, and at the moment all examples are written in VBScript, as it is the easier of the two.
How do you decide upon which language to use? As I stated above, VBScript is easier as it uses a subset of the Basic syntax, but if you’re more familiar with a C++ environment JavaScript might be more what you’re used to. They both do a fine job of scripting in DX.
General
Every command line in JS must have a ; at the end, whereas you do not need them in VBS. Everything that has a beginning and end in JS uses the braces {} to start and end, while VBS uses special end names for every type. Both languages are case sensitive, so be sure to always make sure your case is right.
Ex.
JavaScript:
function Yay()
{
X = 1;
if(x == 1)
{
Script.MsgBox(“Whee!”);
}
}
VBScript:
Function Yay()
X = 1
If X = 1 Then
Script.MsgBox(“Whee!”)
End If
End Function
Comments are lines that won’t be read as commands, so you can put comments throughout your code. In VBScript anything after Rem is a comment, and in JavaScript anything after // is a comment.
Ex.
Rem This adds 1 to X
X = X + 1
// This adds 1 to X
X++;
Variables
Variables are used to store information of some type, such as a number or text. Variables are declared the same way in both VBS and JS. Simply type the name of the variable, an = sign, and what you want to set it to. Numbers have nothing around them but you must put text in quotes.
Ex.
Name = “Ted”
Age = 25
After creating the variables, you can reassign them any time with an equal sign. The data stored in the variable can now be used in place of words or numbers by putting in the name of the variable, for instance:
X = 5
Y = 2
Z = X + Y + 4
In this instance Z would be equal to 11.
Operators
Operators are symbols that perform calculations, such as adding or checking to see if one number is the same as another. Both languages have the math operators +-*/%. / is for division and % is for modulus. In JS you can add or subtract one from a variable by using ++ and -- after the variable name. To compare variables, both have the operators != (Not equal to), >, <, >= (Greater or equal to), <= (Less or equal to). However the equal to operator is = in VBScript and == in JavaScript. Please check a reference for your language for other operators, as there are many more advanced operators.
Functions
Functions are separate pieces of code that can be reused or called upon from different parts of the program. VBS and JS differ greatly on functions.
VBScript:
In VBS there are two types of functions, Subroutines and Functions. Subroutines cannot return a value to what called it, where functions can. Subroutines are declared like this:
Sub MySub(<Passed variables>)
<Body>
End Sub
Functions are declared like this:
Function MyFunction(<Passed variables>)
<Body>
MyFunction = <Value to pass back>
End Function
To use a sub:
MySub(10)
To use a function:
Call MyFunction(10)
To get a value from a returning function:
X = MyFunction(10)
JavaScript:
In JavaScript there are only functions. You can make them return a value using the return <value> statement. They are declared like this:
function MyFunctions(<Passed variables>)
{
<Body>
return <Value>
}
To use a function:
MyFunction(10);
To get a value from a returning function:
X = MyFunction(10);
Examples of functions:
Rem Return the value passed in + 10
Function Add10(InVariable)
X = InVariable + 10
Add10 = X
End Function
// Return the value passed in + 10
function Add10(InVariable)
{
X = InVariable + 10;
return X;
}
Conditions
Conditions perform a different set of code according to conditions given. The main conditional statement is If, and it is all I cover in this guide. There are many other types of conditional statements that might interest you at www.w3schools.com.
An example of an if statement is: If an apple is red it goes to the left and if it is green it goes to the right.
VBScript:
If statements are declared like this in VBS:
If <variable> <operator> <what you’re checking against> Then
<What you want to do>
Else (this is optional)
<What you want to do if it’s false>
End If
For example:
If Apple = “red” Then
Call PutAppleLeft()
Else
Call PutAppleRight()
End If
JavaScript:
If statements are declared like this in JavaScript:
if (<variable> <operator> <what you’re checking against>)
{
<What you want to do>
}
else (this is optional)
{
<What you want to do if it’s false>
}
For example:
if (Apple == “Red”)
{
PutAppleLeft();
}
else
{
PutAppleRight();
}
Loops
One of the most useful functions in scripting languages, loops run commands over and over until certain conditions are met. There are two types of loops, the While loop and the For loop.
While Loops:
While loops loop While a condition is met. For instance, While the TV is on keep watching.
You must be very careful with while loops, as you can easily get things stuck in an endless loop if the condition is never met, and this can cause many things to crash.
VBScript:
In VBS, while loops are declared like this:
Do While <variable> <operator> <what you’re checking against>
<What to do>
Loop
For example:
Do While X < 5
X = X + 1
Loop
JavaScript:
In JS, while loops are declared like this:
while (<variable> <operator> <what you’re checking against>)
{
<What to do>
}
For Example:
while (X < 5)
{
X++;
}
Never do this:
X = 1;
while (x == 1)
{
}
For Loops:
For loops loop a certain amount of times by incrementing a variable and checking it every time.
VBScript:
In VBScript, for loops are declared like this:
For <Variable> = <Start Num> To <End Num>
<Stuff to do>
Next
For Example:
For I = 1 to 10
MsgBox(I)
Next
JavaScript:
In JavaScript, for loops are declared like this:
for (<Variable> = <StartNum>; <Variable> <Operator> <End Num>; <Variable>++)
{
<Stuff to do>
}
Note that you can change the variable++ at the end to variable = variable + 10 or – 3 or whatever you want, it will simply do that calculation every loop.
For Example:
for (I = 1; I <= 10; I++)
{
MsgBox(I);
}
Conclusion:
That was simply a quick overview of both languages to get you started. I highly suggest you read the tutorials on http://www.w3schools.com/ or elsewhere on the internet so that you can get the whole picture or to figure out anything that didn’t make sense above.
Phew! Now that we are familiar with one of the scripting languages, it’s time to learn how to apply this to a DXScript Object. We’ll start by creating a simple object that puts the text “Hello, World!” in a message box on the screen, as this is required by law when learning any language. The first thing you need to do is create a new object and make it scriptable. Do this by following these steps:
1. Right click on the DesktopX system tray icon, and press New Object. A blue circle should appear on your desktop, this is the object you created.
2. Right click on the object you created and press Properties.
3. Under Additional Modules in General, press the Add button.
4. Highlight DXScript and press OK.
5. Press Summary, and give you object a name under Object ID, then press OK.
Now you have created a scriptable object. Please note that every object you want to be scriptable or to be affected by scriptable objects must have the DXScript module added. Also always remember to name your objects.
Right click on the object and press Edit Script. This is where you’ll be doing all of your script editing on objects, so get used to it. In the top right hand corner is the language you want to use, I chose VBScript for this tutorial so keep it on that for now. The Control list box is for ActiveX controls, you don’t need to know about this yet. The 01 denotes the current line number. Now, lets make a simple script.
Type or copy (I suggest type) this code into the editor:
Sub Object_OnScriptEnter
Script.MsgBox “Hello, World!”
End Sub
Take a look at these lines. The Sub and End Sub commands start and end a Subroutine. This subroutine is called Object_OnScriptEnter. It is the sub that DesktopX runs whenever you start your script, so everything that you want to happen right when you start the script goes into this sub. Most Object related functions in DesktopX are done with subroutines/functions. If you wanted something to happen when you quit the script, you would use the sub Object_OnScriptExit.
Now that we have our script, it’s time to test it. There are two ways to do this. One is to use the Test button, but let’s try it the other way first. Go up to File, Exit in the menu on the script editor, and it should ask you if you want to save. Press Yes, then Press OK on the object properties window. Why hasn’t it done anything? This is because in DesktopX you have to enable the script after doing anything to it. Simply right click the object, and press Script Enabled. Now if all went well a box should pop up with “Hello, World!”
The debugger helps you figure out problems with your code and quickly fix them. To get to the debugger, go back to the script editor and press Test. This will run your script, and also pop up a Debugger window. The red button stops your script in action and the green button starts the script. The textbox is your Debug Output window. You can use this to check if variables are what they should be at, to see if your script gets to certain parts of code, and many other things. It works like the MsgBox function, except you type Script.MsgDbg to send a message to it.
For example:
Do While I < 10
I = I + 1
Script.MsgDbg(I)
Loop
Script.MsgDbg(“Got past the while loop”)
Now that we can create a simple script using the Object_OnScriptEnter sub, it’s time to learn a sub that allows user interactivity, Object_OnStateChange. This subroutine is called whenever any of an object’s states change. States can be any mouse input from the user, an objects visibility, if an objects command has been executed, or custom messages. Right now we will do a simple mouse input state. We’ll modify the existing script to do this, so go back into edit script on your object. Change the script so it looks like this:
Sub Object_OnStateChange(State)
If State = “Mouse up” then
Script.MsgBox “Oof”
End If
End Sub
Do you notice anything different about the subroutine? The Object_OnStateChange sub has a string passed into it telling you which state has been changed. I called it State, but you can call it anything you want. Then we use an If statement to see if State is “Mouse up”, and if it is we run our messagebox. The Mouse up state is set when you let up on the left mouse button after clicking the object. You can see all of the available states in the DXScript reference.
Go ahead and save the script and enable it. Try clicking on your object, and it should come up with the message box.
By now you’re probably sick of making message boxes, so let’s move on to one of the more useful functions of DXScript: Object properties. Object properties are variables that allow you to read and set the position, state, and visibility of objects, so they are obviously very useful. Object properties are modified and returned by using Object.<property>, for instance Object.Left.
Go ahead and create a dxscript object, and set the script to this:
Sub Object_OnStateChange(State)
If State = “Mouse up” then
Object.Left = Object.Left + 30
End If
End Sub
Save/enable and try clicking the object. It should shift 30 pixels every time. Neat, huh? Whenever you are modifying any of the properties of the object the script is running on, you type Object.<property>, regardless of the object’s name.
What if you want to modify the properties of other objects from this script? This is very simple. To do this we use the function DesktopX.ScriptObject(“object name”).Object.<property>. Go ahead and create another object and give it the object ID MoveMe. Make sure you add the DXScript module to it and Enable it, even though it doesn’t have any script. If you don’t do this DXScript won’t be able to find it. Now go back to your first object and edit the script. Change it to this:
Sub Object_OnStateChange(State)
If State = “Mouse up” then
DesktopX.ScriptObject(“MoveMe”).Object.Left = DesktopX.ScriptObject(“MoveMe”).Object.Left + 30
End If
End Sub
Save/enable and try it, clicking on your object should move the MoveMe object. If it says it can’t find the MoveMe object, you probably forgot to press enable script on MoveMe.
The properties for moving and position objects Left, Right, Top, and Bottom. Left gets the left most value of the object (X) and Top gets the topmost value of the object (Y). Right gets the right value of the object (X + Width), and Bottom obviously gets the Bottom value of the object (Y + Height). They can also all be used to set these values on an object.
For instance:
Sub Object_OnScriptEnter
For I = 1 to 10
Object.Left = Object.Left + I
Object.Top = Object.Top - I
Next
End Sub
State Property and Custom Messages
Custom messages are very simple to use. Create a new object named Object1, and in the appearances section add a state called Custom. Now enter this for it’s script:
Sub Object_OnStateChange(State)
If State = “Custom” then
Script.MsgBox “Yay”
End If
End Sub
Now create another object named Object2, and input this for it’s script:
Sub Object_OnStateChange(State)
If State = “Mouse up” then
DesktopX.ScriptObject(“Object1”).Object.State = “Custom”
End If
End Sub
This shows us the State property, which is simply used to change the state of an object. Remember that you must add the state to the objects properties before calling it, or else the object will ignore it. Now when you click on Object2, Object1 should output the message box. Another state property is StatePreempt, which allows you to change an objects state while it’s doing something for another state, such as an animation. This is useful when you need to immediately change the state of an object.
The Text property is used to change or get the text in a text only object. To use this, create a text object (By setting it’s appearance to Text in the object properties window), then simply put Object.Text = <string>
For instance:
Sub Object_OnScriptEnter
Object.Text = “Wheeeeeee”
End Sub
The Visible property is a Boolean value (True or False) that sets whether or not an object is hidden.
For instance, if you want to toggle the visibility of an object this function would do nicely:
Sub Toggle(ObjName)
If DesktopX.ScriptObject(ObjName).Object.Visible = True then
DesktopX.ScriptObject(ObjName).Object.Visible = False
Else
DesktopX.ScriptObject(ObjName).Object.Visible = True
End If
End Sub
The Name property simply sets and returns the name of the object.
Sub Object_OnScriptEnter
Object.Name = “Bill”
Script.MsgBox Object.Name
Object.Name = “Ted”
Script.MsgBox Object.Name
End Sub
Timers are a very important thing to learn, as they can be very useful in many situations. What a timer does is run a custom subroutine in your script at an interval you choose, so for instance you can have something check a web page every 10 seconds or have something constantly change animation frames every 30 millisecs.
In order to set up a timer, you first want to decide on the timer ID. This is a unique number that your timer answers to. Once you have your number, you create a subroutine called Object_OnTimer<number>, for instance Object_OnTimer10. Now to turn on this timer you simply run the Object method Object.SetTimer <timer ID>, <time in millisecs>, and likewise to turn it off you run Object.KillTimer <timer ID>
Here is an example:
Sub Object_OnStateChange(State)
If State = “Mouse up” then
Object.SetTimer 10,50
End If
End Sub
Sub Object_OnTimer10
Object.Left = Object.Left + 10
If Object.Left > 800 Then Object.KillTimer 10
End Sub
In this example, the object will move 10 pixels every 50 milliseconds until it hits 800 pixels, then it will stop. Go ahead and try it.
Sleeping is useful when you want an object to wait for a certain period of time before continuing. It is used by the method Object.Sleep <milliseconds>. To try this, make an object and set it’s script to this:
Sub Object_OnScriptEnter
Script.MsgBox “Sleeping”
Object.Sleep 5000
Script.MsgBox “Done”
End Sub
This will show you Sleeping, then sleep for 5 seconds, then say Done.
Controls are enclosed programs that DesktopX can interact with as if they were it’s own object. Windows comes with many different controls, they can be downloaded off of the internet, and DesktopX even comes with a few. Unfortunately you need the documentation for a control you’re going to use, and sometimes that very hard to find. For Microsofts controls, you can usually find the documentation by searching on MSDN. Another problem with controls is that if you use an odd one you must include it with your theme and other people must install it themselves, as they are not packaged like plugins.
Let’s start learning controls by creating a simple Web Browser control object. Create an object and bring up it’s script editor. In the top left hand corner of the editor there is a listbox that says Control. This shows your current Hosted control for the object. Go ahead and pull it down, it will show you all the controls in your system. Look for the control named Microsoft Web Browser and highlight it. Save it. Your object should change into a moveable/resizable box. Now open your editor again, enter this for the script:
Sub Object_ScriptEnter
Control.Navigate “http://www.stardock.com”
End Sub
As you can see, all control methods and properties are accessed using Control.<method or property>
Enable the script and voila, you now have a web page control on your desktop. If you need to edit/resize/move the control again, you must now hold down the Ctrl key on your keyboard and it will highlight.
Now let’s learn how to use one of the DesktopX controls, the Edit Control. Create an object and set it’s control to DesktopX Edit Control. This control allows you to input text into a text field and have DesktopX read it. The Edit Control includes what is called an Event. Events are essentially functions on the host that are called by the control. Whenever a key is pressed in the Edit Control, it fires the Event called OnKeyPress(<key>). <key> is a variable representing the ASCII code of the key just pressed. Events in DesktopX have Control_ in front of them. Now edit your object and input this for the Script:
Sub Control_OnKeyPress(Key)
Rem The enter key
If Key = 13 Then
Script.MsgBox Control.Text
Control.Text = “”
End If
End Sub
Now go ahead and enable the script and type something into the Text box. When you press enter, it will output what you typed and clear the controls text.
The system object allows you to get information from the system. Currently, you can only get the resolution in pixels of the screen (System.ScreenWidth, System.ScreenHeight), the resolution in pixels of a multimonitor system (System.VScreenWidth, System.VScreenHeight), and whether or not you are connected to the internet (System.InternetConnected).
The storage methods are used when you need to save data, such as configuration options, lists of names, etc. There are two types of storage, Local and Persistent. Local storage will save only on your local machine and only in your theme, where as Persistent storage will stay with an object when it is exported. Here is an example of a script using storage:
Sub Object_OnScriptEnter
If Object.LocalStorage(“RunOnce”) = “Yes” Then
Script.MsgBox “I have been run once.”
Else
Object.LocalStorage(“RunOnce”) = “Yes”
Script.MsgBox “I have not been run once”
End If
End Sub
Now when you enable this object, it will not have anything in the RunOnce variable and will set it to Yes. The next time you run it, the RunOnce variable will already be set so it will say it has been run once.
Objects interact with each other using DesktopX.ScriptObject(“<object name>”).*, where * is anything within the object, including variables, functions, and properties. To show interaction between two objects, we will create an object to be modified and an object that includes the functions to modify the other.
First create an object called Object1, and set it’s appearance type to Text. Put something in for the text so you don’t lose track of it. Now edit it’s script and put in:
Sub Object.OnScriptEnter
SetMyText( Script.InputBox(“Input new text for object”) )
End Sub
Rem Set my text to something else using TextObject’s SetText function
Sub SetMyText(NewText)
DesktopX.ScriptObject(“TextObject”).NewText = NewText
DesktopX.ScriptObject(“TextObject”).SetText(Object.Name)
End Sub
Don’t enable it’s script yet. Now create another object and call it TextObject. Give it this script:
Rem Create a variable to hold the text
Dim NewText
Rem Change Text of ObjName to NewText with dashes on the sides
Sub SetText(ObjName)
TextWithDashes = “ – “ + NewText + “ – “
DesktopX.ScriptObject(ObjName).Object.Text = TextWithDashes
End Sub
Go ahead and enable TextObject, then Object1. Now whatever you type into the input box should change Object1s text to it with some dashes on the sides. This is how objects interact in DesktopX. Also look at the above section for custom messages to make objects interact with each other.
DesktopX can also use type libraries, such as Windows Scripting Host or Dictionary. To use them, you simply type Set <variable name> = CreateObject(“<lib name>”). Then you can use the variable to call methods/properties in the library. For instance, to run an application with the Windows Scripting Host you would put:
Set WshShell = CreateObject(“WScript.Shell”)
WshShell.Run “Explorer.exe”
There are many useful type libraries, simply do a search for them.
Reference Documentation.
Excellent VBScript/JavaScript reference is http://www.w3schools.com/
Discussion: news://news.stardock.com/stardock.desktopx
Bouncing ball with orbiting ball (2 objects):
Object: Ball
Rem Globals
xshift = 2
yshift = 2
Rem Options
Rem Your screen resolution: (important!)
ScreenX = 1152
ScreenY = 864
Rem Startup
Sub Object_OnScriptEnter
Rem Set timer 10 to 30 millisecs
Object.SetTimer 10,30
End Sub
Rem Timer 10
Sub Object_OnTimer10
Rem Set shifts accord to where ball is on screen
If Object.Left < 0 Then xshift = 2
If Object.Right > ScreenX Then xshift = -2
If Object.Top < 0 Then yshift = 2
If Object.Bottom > ScreenY Then yshift = -2
Object.Left = Object.Left + xshift
Object.Top = Object.Top + yshift
End Sub
Rem Find the X pos in a circle
Function CircleX(Center,Radius,Angle)
CircleX = Cos(Angle)*Radius + Center
End Function
Rem Find the Y pos in a circle
Function CircleY(Center,Radius,Angle)
Rem Return Sin(Angle)*Radius + Center
CircleY = Sin(Angle)*Radius + Center
End Function
Rem Globals
Angle = 0
SizeX = Object.Right - Object.Left
SizeY = Object.Bottom - Object.Top
Rem Options
Rem The radius of the orbit
Radius = 150
Rem the Object you want to orbit
Obj = "Ball"
Rem the speed in millisecs of each update
Speed = 30
Rem the smoothness of the angle increment
AngInc = .05
Rem Startup
Sub Object_OnScriptEnter
Rem Set timer 11 to the speed
Object.SetTimer 11,Speed
End Sub
Rem Main code
Sub Object_OnTimer11
Rem Inc the angle
Angle = Angle + AngInc
Rem restart the angle if needed
If Angle > 360 Then Angle = 0
Rem Find the horiz center of the object
CenX = ((DesktopX.ScriptObject(Obj).Object.Right - DesktopX.ScriptObject(Obj).Object.Left) / 2) + DesktopX.ScriptObject(Obj).Object.Left
Rem Find the vertical center of the object
CenY = ((DesktopX.ScriptObject(Obj).Object.Bottom - DesktopX.ScriptObject(Obj).Object.Top) / 2) + DesktopX.ScriptObject(Obj).Object.Top
Rem Set the X pos
X = CircleX(CenX,Radius,Angle)
Rem Set the Y pos
Y = CircleY(CenY,Radius,Angle)
Rem Reposition the orbiter
Object.Left = X - SizeX/2
Object.Top = Y - SizeY/2
End Sub