DesktopX Scripting

By now you should realize just what amazing results can be achieved using DesktopX. DXScript takes things to an entirely new level!

Whilst DesktopX is flexible, DXScript allows a user with a hint of programming experience to really extend the possibilities of what you can do.

DXScript allows you to program in either VBScript and JScript, two of the most simple and common languages available. This document is not designed to teach you how to program these languages, we assume you know the basics. If not, I suggest you take a little time to learn and then you can join the fun. Before you recoil in fear at the works 'programming' and 'script', this is not a trip into the world of the uber-geek. Let me say this once and say it loud - "Learning DXScript is not hard!".

Adding script to objects is very easy. Simply open up the Object Properties dialogue of the object to which you want to add script and on the General tab you will see a button saying 'New' in the Script section. Clicking this brings up the dialogue you see on the left. You will note that the main window is prepared for you to start entering script, but before we do that let's look around the 'Script' menu. Under this there are three sections. The second one, 'Language' allows you to specify whether you want to program in VBScript or JScript.

Whilst both work in pretty much the same way, we will be using VBScript examples here. Once you have decided on a Scripting language you are ready to go. This is where you start to need a bit of scripting or programming knowledge. As with most programming languages, everything is based around a series of Events and then Methods and Properties are used to make things happen. By default two events are created. You will also see comment lines (starting with ' ) that explain when they occur. So lets get scripting straight away in the traditional way! Edit the script to display the following:

Sub Object_OnScriptEnter
MsgBox "Hello, World!"
End Sub

Sub Object_OnScriptExit
MsgBox "So Long, And Thanks For All The Fish!"
End Sub

Note that the indents on the code are just for clarity.

If you now close the script you will now have an object the pops up a message every time the script is enabled or disabled.

OK, so this is a bit fake because you're enabling the script and disabling script, but in the real world this will pop up a message when DesktopX loads (and the object's script is enabled), and a message when DesktopX unloads (and the object's script exits).

One of the other key Events is Object_OnStateChange(state). This identifies when an object switches from one state to another and allows script to be run at that time. By querying the state that has arisen, script can be run in response to that.

In the below example, the script pops up a message if the user activates the object (the 'Command executed' state).

Sub Object_OnStateChange(state)
If state = "Command executed" Then
MsgBox "You activated me!"
End If
End Sub

Note that you can also check for Custom Messages, and not just the default states that exist. The final state that needs discussing here is the Object_OnTimer event. DesktopX can create timers which mean that script can be run at set intervals. Although we will be discussing object methods later, we need to use one here. Before a timer event can run you need to define that timer by using an Object.SetTimer command. In this command you give the timer a unique numeric identifier and specify the interval (in milliseconds) at which the timer will run.

In the below example a timer with the identifier 12345 is set up when the script starts to run every 10 minutes (600000 milliseconds). Each time this timer occurs, the script flashes up the current time using the VBScript command Time().

Sub Object_OnScriptEnter
Object.SetTimer 12345, 600000
End Sub

Sub Object_OnTimer12345
MsgBox "The time is " & Time()
End Sub

Sub Object_OnScriptExit
Object.KillTimer 12345
End Sub

Now that we have discussed events, obviously you can use any VBScript or JavaScript within an event, but to properly interact with DesktopX you need specific Methods and Properties.

More detail and examples are also available in the DXScript Reference, but we will discuss some of the basics here to get you started. To start with you need to know how to refer to objects and then we'll move onto the things you can do with them. To refer to the current object (i.e. the one who's script you are editing), simply use Object.xxxx.

For example:

Object.Left = 200

To refer to another object in the theme you use DesktopX.Object("ObjectName").xxxx.

For example:

DesktopX.Object("Button").Left = 200

Note that some objects may have multiple states. Where this occurs, DXScript allows you to adjust parameters for some or all of these states. This is further explained in the Object Namespace reference.

Namespaces Introduction

Namespaces identify a “node” of properties and methods. When you create a new script for an object (“New” button in the General Properties page), you are actually creating an accessible “root” namespace for that object.  Sub-spaces group common functionality for the object. For instance:

Enumerators

DXScript has support for these object collections:
- DesktopX.Objects
- DesktopX.GroupObjects(“groupname”)
- Object.Children

They can be used like this:
- DesktopX.Objects.count – number of objects in the collection
- DesktopX.Objects.item(“obj1”) – returns the Object namespace of “obj1”
- DesktopX.Objects.item(3) – returns the Object namespace of the third object in the collection

You can also use the VB Script For Each method as shown in the following examples:

msgbox "Total objects:" & DesktopX.Objects.count
msgbox "First object name:" & DesktopX.Objects.item(1).name ' or .left or .ontop etc
msgbox "Test1 object name:" & DesktopX.Objects.item("Test1").name

For Each elem In DesktopX.Objects
msgbox "First object name:" & elem.name
elem.left = 50
'etc
Next

Simply put the returned item is identical to the references returned by DesktopX.Object("name"), NOT DesktopX.ScriptObject("name"). You can always do DesktopX.ScriptObject(elem.name) if you need.  DesktopX.GroupObjects(“groupname”) and Object.Children collections work in a similar way.

Script Threading

Starting version 2.40b[a].002 scripts run by default inside the DesktopX GUI thread. This is because scripts mostly work interactively, affect the object appearance, respond to user input etc. It make sense to do such things synchronously with the DesktopX thread.  If you need some long running scripts to be asynchronous, you can enable the menu option in the Script Editor “Run in separated thread”. For instance, if a script isn’t elaborating (downloading from internet etc) for several seconds, it will not lockup DesktopX until it returned.

There is only a caveat in running scripts in the secondary thread: scripts in one thread cannot access the script namespace of a script in another thread. For instance, you cannot use: DesktopX.ScriptObject(“object1”).* if “object1” is in a different thread. However, you can use the DesktopX.Object(“object1”).* shortcut as explained before, because it doesn’t hook into the actual script namespace. Of course you can only use Object properties and methods, not access script variables, functions and other sub-namespaces.

VBScript References

The best way to learn VBScript is via the various resources available online. Here are a few to help you get started:

Microsoft VBScript Reference - http://msdn.microsoft.com/library/en-us/script56/html/vtoriVBScript.asp
VBScript Introduction - http://wiht.link/vbscript-resources

ActiveX Controls in DXScript

The power of script is enhanced by the ability to display ActiveX controls on the desktop instead of using images or text. You can then manipulate these using scripts. For example, imagine an Excel spreadsheet, Windows Media Player, Combo box, Web Browser all embedded on your desktop. All are possible and very easy to create.

In the DesktopX Script Editor, the first option on the script menu is 'ActiveX Control' from which there is a 'Select Control' option. We'll look at how to create one of these controls now. From the list that appears when you click 'Select Control', choose a control and then click OK. In our examples below we will use the 'Microsoft Web Browser' control. As you will see below, the Script Editor immediately changes to reflect your choice. On the right of the editor you will see a preview of the object, and below that you will see the properties of that object.

Note that the ActiveX Control menu item now has a 'Properties' option where you can toggle to display of this extra information. If you close the editor via the close button top right or via 'File ... Exit' you will now see a control on your desktop. You will see that as you move your mouse over the object the cursor changes. You can move the control or resize it using the black handles at the edge. If you right click the object, you will notice a new item, 'Script Enabled' at the bottom of the list. This is the place where you can toggle the script between a 'running' and 'not running' state. At the moment it is not running which is why the resize handles are visible. Click 'Script Enabled' to toggle the running state and you will see these disappear.

OK, so at the moment it's a dull white box, not very exciting, but nevertheless it's a control and we're about to ramp up the excitement. Let's go back to the editor. If you right click the control you will note that nothing happens. This is because you are effectively right clicking the Web Browser control, not a DesktopX object. Hold down CTRL so the resize edges appear and right click. You will see that the script is enabled because of the check mark next to that item. Click the Edit Script item and the dialogue will reappear.

OK, try changing the script you see to the one below:

Sub Object_OnScriptEnter
Control.Navigate2 "www.wincustomize.com"
End Sub

OK, so exit out of here and enable the script. Caboom - all of a sudden you have a genuine webpage on your desktop! You will note from this that scripting is basically the same for Controls as it is for regular objects. The only real difference is that when referring to the ActiveX control you use the Control prefix. Note that you can also use Object methods and properties in the script but these refer to the host object. For example Object.Visible in an object containing an ActiveX control would hide that object and hence that control.

Each ActiveX control will expose it's own properties and these are displayed in the auto complete feature. This makes it really easy to start coding for a control. In addition to this it is useful to know which events are associated with a control. With this, we are able to react to events occurring in the control. DesktopX provides a tool to do just this. In the Script Editor, go to the Script Menu and select 'Event Wizard'.

Select the event you want to add and click OK to add it to your script. Click 'Done' when you have added all the events you want to. You can now add script to that event. For example:

Sub Control_DocumentComplete(pDisp, URL)
Msgbox "Finished downloading the page " & URL
End Sub

Now, you will be advised when the page is completely loaded.

One final thing you should know is that DesktopX installs three controls by default. There is an Edit control (to allow you to accept and react to user input), a Push Button control (which acts just like a regular button), and a Check Box control (to give you an on/off switch). Each of these controls have specific events and properties associated with them.

PushButton Control

The PushButton control allows you to use a regular push button 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 control 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
BGColor: The background color of the box
TextColor: The color of text in the control

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.

ComboBox Control

The ComboBox control allows you to create a drop-down list of options from which the user can select.

Properties

BackColor: Sets or queries the color of the control background (as OLE_COLOR)
ForeColor: Sets or queries the color of the control text color (as OLE_COLOR)
SelectionBackColor: Sets or queries the background color of the selected item in the control (as OLE_COLOR)
SelectionForeColor: Sets or queries the text color of the selected item in the Control (as OLE_COLOR)
BorderVisible: Sets or queries whether or not the border of the control is visible (as Boolean)
Enabled: Sets of queries whether an object can respond to user-generated events (as Boolean)
Item(Item As Long): Sets of queries the text of a specific item in the control (as String)
ItemCount: Queries the number of items in the control (as Long)
ListIndex: Sets or queries the currently selected item in the control (as Long)
Text: Queries the text of the currently selected item in the control (as String)
ListVisible: Sets or queries whether the control’s drop-down list is visible (as Boolean)

Events

OnSelect(Item As Long, string As String): Fired when an item in the list is selected
OnCloseUp(): Fired when the drop down menu is closed
OnDropDown(): Fired when the drop down menu is opened

Methods

AddItem (bstrItem As String): Inserts an item into the Control
ResetList(): Clears the Control

ListBox Control

The ListBox control allows you to display a box containing a list of options from which the user can select.

Properties

BackColor: Sets or queries the color of the control background (as OLE_COLOR)
ForeColor: Sets or queries the color of the control text color (as OLE_COLOR)
SelectionBackColor: Sets or queries the background color of the selected item in the control (as OLE_COLOR)
SelectionForeColor: Sets or queries the text color of the selected item in the Control (as OLE_COLOR)
BorderVisible: Sets or queries whether or not the border of the control is visible (as Boolean)
Enabled: Sets of queries whether an object can respond to user-generated events (as Boolean)
Item(Item As Long): Sets of queries the text of a specific item in the control (as String)
ItemCount: Queries the number of items in the control (as Long)
ItemHeight: Sets of queries the height of individual items in the ListBox (as Long)
ListIndex: Sets or queries the currently selected item in the control (as Long)
Text: Queries the text of the currently selected item in the control (as String)

Events

OnSelect(Item As Long, string As String): Fired when an item in the list is selected

Methods

AddItem (bstrItem As String): Inserts an item into the Control
ResetList(): Clears the Control

Scriptable Plug-ins

Scriptable E-Mail Notify Plug-in

DesktopX 3.0 supports scriptable plug-ins that simply add some custom functionality. In the case of the Scriptable Mail Notify plug-in, only the actual email check functionality is offered by the plug-in, while the account management, the preferences, the configuration and everything else is left to the DesktopX author to be implemented with DesktopX objects and scripts.

In order to use this plug-in, you should add both a script and the “Scriptable Mail notify” plug-in to an object. The plug-in exposes only one method and one notification event. The method is:

Mail.CheckMail requestID, sLogin, sPass, sServer, accountType

requestID is a string identifying the request. Since this method is asynchronous and returns immediately, if you are handling multiple accounts you need to match responses with requests. This value let you do that, since you get back the same identifier when the response is ready.
sLogin is the mail account user name, sPass is the password, sSever is the server name (i.e. “mail.stardock.com”).

AccountType can be 0 for POP3 or 1 for IMAP.

Use the event wizard to get the following event added to the script:

Sub Mail_OnMailEvent(requestID, newMails)

This event will be fired when a request has been accomplished. RequestID contains the identifier passed in the request and newMails is a number indicating the unread mails.