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:
Script |
What it does |
Object.Left |
Let you access (read/write) the Left property from
the Object namespace. |
Object.State(“Mouse
over”).Picture |
Let you read/write the Picture property for the
State(“Mouse over”) namespace, that is accessed from the Object
namespace. |
Object.Parent |
Let you access the root script namespace of the
parent object. From here on, you can do as above:
Object.Parent.Object.Left, Object.Parent.Object.State(“Mouse
over”).Picture
Important: It assumes the parent object actually has a script namespace,
i.e. it has a script associated. If this isn’t the case, you’ll get a
script error when trying to access the parent members. |
DesktopX.ScriptObject(“object01”) |
Let you access the root namespace for object01. This
means you can access all sub namespaces like Object and Control, global
variables and functions. |
DesktopX.ScriptObject(“object01”).Object.Name |
Name property for the “object01” object. |
DesktopX.ScriptObject(“object01”).myvariable1 |
Read/write myvariable1 declared in the “object01”
script. |
DesktopX.ScriptObject(“object01”).myfunc1
args |
Call myfunc1 declared in the “object01” script. |
DesktopX.Object(“object01”) |
Gives straight access to the plain Object namespace.
This is usually a shortcut and memory saving technique, because it let
you access the Object namespace without that “object01” actually has a
namespace associated. |
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.
|