Previous Page  Developer's Guide: Scripting Reference  5.2 Next Page

Object Namespace

This section defines the scripting commands that can be applied to objects in DesktopX.

Object.States namespace
From the object namespace you can access the States namespace to read/write state specific properties. States properties also exist in the Object namespace. There are basically three different methods you can use to read/write: – it’ll read/write the state property for the current state
Object.States(“mystate1”).property - it’ll read/write the state property for the “mystate1” state
Object.States(“”).property – it’ll write the property to all states in the object

Unless the object has only one state, it is usually better to use the second method.

All properties which can be applied in the States namespace as well as in the Object namespace are suffixed with *


Through use of these commands you can set an objects name, though it is more likely you will want to retrieve the name of an object or its parent. Object.Parent is used to retrieve the entire object model of the parent, so you can refer to the object. In addition to this, you can also set an object’s parent using this property. The 'Visible' property is most useful allowing you to show or hide an object without the use of popups or messaging.

1) MsgBox "This object is called " & Object.Name
2) Msgbox "This object's parent is " & Object.Parent.Object.Name
3) Object.Parent = DesktopX.Object("Some object")
4) DesktopX.Object("AnObject").Parent = DesktopX.ScriptObject("anotherobject")
5) Object.Visible = False


This allows you to either duplicate or delete the specified object. When duplicating an object you need to provide the name for the new object and the x and y coordinates where it will be placed. Deleting objects may be useful for things like deleting temporary objects such as instructions once the user has taken note of them.


Object.Clone "myobject", 300, 200
If Msgbox("Delete object", vbYesNo) = vbYes Then Object.Delete

Object.Top, Object.Bottom, Object.Left, Object.Right, Object.Move, Object.Rotation (and Object.States("name").Rotation)

With these positioning properties, you can explicitly set or retrieve the location of one side of the object.
If you want to reposition an object, the most efficient was to do it is via 'Move' To do this you specify x and y coordinates in pixels of where you want to place the object. You can also rotate an object using Object.Rotation.


Object.Top = 500
Object.Move 500,200

For x = 1 To 10
Object.Rotation = x*36
Object.Sleep 200

Object.Height, Object.Width

With this command you can retrieve or redefine the actual height and width of the object. Obviously this will stretch the graphic used until it reaches this size.


Object.Height = 120
Object.Width = Object.Width * 2


With this command you can quickly and easily resize an object in one command rather than setting width and height individually.


Object.Resize 100,300
Object.Resize Object.Width + 10, Object.Height + 10

Object.Hue, Object.Brightness, Object.Contrast, Object.Opacity
also Object.States("name").Hue, Object.States("name").Brightness,
Object.States("name").Contrast, Object.States("name").Opacity)

If you want to dynamically change the color, hue or brightness of an object, it is easy to do with these commands. Simply set a value of 1-255 for hue, -255 – 255 for brightness and -100 – 100 for contrast. Set it to 0 to remove any previously made changes. You can also set or retrieve the level of opacity that an object has in a range from 0 (totally invisible) to 100 (totally visible).


For x = 0 To 255
Object.Hue = x

Object.Brightness = -30

DesktopX.Object("anotherobject").Contrast = 40

Object.Opacity = 60

Object.State, Object.StatePreempt

Through use of Object.State you can change or retrieve the state of an object. This is one of the most common commands used in script as it is used to trigger objects to act certain ways. Object.StatePreempt should be used when you want to set a state immediately without waiting for any animations etc to complete.

If Object.State = "Command executed" Then ...

x = DesktopX.Object("anotherobject).State

DesktopX.ScriptObject("scr_object).Object.StatePreempt = "Hide"

Object.Text, Object.TextColor, Object.TextBorder, Object.TextBorderColor
also Object.States("name").Text, Object.States("name").TextColor, Object.States("name").TextBorder, Object.States("name").TextBorderColor

If your object is a text object rather than an image, you can manipulate it using script changing either the text itself or the appearance. You can set/retrieve the text or it's color and well as defining whether the text has a border, and if so what color it is.
The colors are most easily set using an RGB value separated via commas.

If Instr(Object.Text, "Data") Then Msgbox "String found"

Object.TextColor = RGB(120,200,255)

Object.TextBorder = True

Object.TextBorderColor = RGB(255,0,0)

Object.SetTimer, Object.KillTimer, Object.Sleep

As discussed earlier, the Object.SetTimer sets an event and an interval to which you can then add code to run at the predefined interval. If you need to stop a timer running you can use KillTimer to stop it. e.g. Object.KillTimer 12345 will stop any code in the Object_OnTimer12345 event from running.
Object.Sleep stops code running temporarily for a defined period of time. For example Object.Sleep 1000 will wait for 1 second before continuing to run.

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


This executed any command associated with the object in it’s Object Type. This is particularly useful for doing things at set intervals or events, such as when DesktopX exits.

Sub Object_OnScriptExit
End Sub

Object.LocalStorage, Object.PersistStorage

When coding it is often useful to store persistent information which can be retrieved and used as required across multiple executions of the same object or widget. To store data you need to give the data a unique reference (for that object) and set it's value. For example Object.LocalStorage("MyZip") = 48152 would place the value 48152 in a storage variable called MyZip. "MyZip"=48152 will be automatically saved and restored when the object is unloaded and reloaded.

The difference between the two types is in its persistence across object packaging and distribution. LocalStorage will NOT be saved when the object is saved as .dxpack or a widget is built. PersistStorage instead will save its value. LocalStorage is useful to store personal information, like a passwork or a ZIP code. Infact, you don’t want such information to be preserved when you export and redistribute the object to other people. However, you want these values to be preserved across multiple run of the same object/widget.


Sub Object_OnScriptEnter
If Object.LocalStorage("MyZip") = "" Then
Object.LocalStorage("MyZip") = "48152"
End If
Object.SetTimer12346, 3600000
End Sub

Sub Object_OnTimer12346
End Sub

Sub Object_OnScriptExit
Object.KillTimer 12346
End Sub

Function GetWeather(zip)
End Function


The object pushes an object to the top of the z-order which obviously makes it more visible. The below example makes an object appear above other objects when you move the mouse over it.

Sub Object_OnStateChange(state)
If state = "Mouse over" Then
End If
End Sub


The simply sets an objects focus so it can respond to events. For example all objects have an Object_OnSetFocus so this will be triggered if this command is used. Also, where a text based DesktopX object responds to functions based on keyboard or mouse activity (e.g. Function Object_OnChar(dwKeyCode, flag), Function Object_OnLButtonDown(x, y)) then it will respond when these events occur. You can also apply this to ActiveX controls, so for example if an object contains a DesktopX Edit Control then setting its focus will prepare it to accept text input.

Sub Object_OnStateChange(state)
If state = "Command executed" Then
Msgbox "Ready for input"
End If
End Sub


This allows you to set the tooltip of the object which is particularly useful to provide additional information to the user. You can also use this to provide different information depending on different circumstances.

If Object.Text = "New mail" Then
Object.TooltipText = "Click to launch mail software"
Object.TooltipText = " "
End If


An AppBar is an object that is designed to be attached to the edge of the screen like the Taskbar. Also like the taskbar it can be set to autohide, but beyond this you can undock it as well so it can be moved on the screen. When an appbar is set to Autohide, then moving the mouse over the edge of the screen will cause the AppBar to smoothly appear.
Note that Object.AppBar can only be written, not read, so if you need to check the mode at any time you need to set a variable when you set the mode, and then query the value of this variable. Example 1 shows how you may set a variable in this manner.
The values for Object.AppBar are as follows:
0 = Disabled
1 = Docked
2 - Autohide

Sub Object_OnScriptEnter
Object.AppbarMode = 1
appmode = 1
End Sub

If state = "Command executed" Then
DesktopX.Object("maindock").AppbarMode = 2
End If


This tells you the directory within which the object is located. This will point to the user’s theme directory.

Object.Sound *

This allows you to set the sound associated with the object either globally or specific to certain states. The sound file targeted can either be a WAV or MP3 format file.

Object.Sound = "c:\mydirectory\mytune.mp3"
Object.State("Mouse down").Sound = "ding.wav"


This allows you to set the volume of the sound played by an object. The range is 0 (muted) to 100 (full system volume)

Object.Volume = 80
Object.Volume = Object.Volume + 10

also Object.States("name").Picture

This allows you to get/set the picture of an object or state.

Object.Picture = “image01.png”
Object.States(“Mouse away”).Picture = “C:\images\image01.png”
Object.Picture =

- You can use the following modes:
- File names: DX will check into the current theme or widget folder. Note that files must be registered as custom files or bound to at least one state for them to be packed into a .dxtheme, .dxpack or .exe.
- Full path: this can be useful for totally dynamic things like a Picture viewer widget in that you can simply do:

Sub Object_OnDropFiles(files)
Object.picture = files
End Sub

- Full path images are not exported.
- Remote paths: you can use this to easily make a webcam object.
- Remote path files are not exported.

also Object.States("name").SetPicture

This method let you set the picture of an object or state AND its other properties in one call.

Object.SetPicture fileName, frames, interval, flags
For fileName see Object.Picture.
Frames is the number of frames in the picture.
Interval is the number of milliseconds between each frame.
Flags is a combination of the following flags:
&H00000001 – Loop
&H00000002 – Reverse
&H00000004 – Alternate
&H00000008 – Interruptable
&H00000010 – Static


Gets/sets the current frame of the animation. In order to use this, the animation should be set “Scripted” in the Properties panel.


Returns true if the object is a contained child. If it has a parent but it is only “owned” (Child = No in Summary page) , it will return false.
Contained children coordinates are relative to the parent’s top/left corner.

also Object.States("name").SetMargins

This allows you to assign the image margins and tile/stretch settings of a state or all states of an object.
Object.SetMargins leftMargin, topMargin, rightMargin, bottomMargin, boolStretchX, boolStretchY

Values are distance from each edge. Set boolStretchX and boolStretchY to true to configure stretching mode. Leave false for tiling mode.

Object.Command and Object.CommandParams

Gets/sets the object command and parameters for Shortcut and URL object types.


Gets/sets the object group name.

Object.RegisterHotkey and Object.UnregisterHotkey

Let you register an hotkey combination. A special event is called when the user hits the hotkey.
Object.RegisterHotkey hotkeyID, hotkeyValue

hotkeyValue is defined as a long in the same way the HKM_GETHOTKEY returns (
The virtual key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the following values:

&H00000001 - shift
&H00000002 - control
&H00000004 - alt
&H00000008 - extended key

Once the hotkey is set, the object script will be notified through:

Sub Object_OnHotkey(id)

where id is the first parameter that is passed to RegisterHotkey.

To unregister the hotkey call:

Object.UnregisterHotkey id


Gets/sets the object comments field

also Object.States("name").SetFont

Let you assign all font settings at once.
Object.SetFont fontName, size, boolBold, boolItalic, boolUnderline, boolStrikeOut, lfCharSet

You can leave the last parameter = 0

Object.FontName, Object.FontSize, Object.FontBold, Object.FontItalic, Object.FontUnderline, Object.FontStrikeout
also Object.States("name").FontName, Object.States("name").FontSize, Object.States("name").FontBold, Object.States("name").FontItalic, Object.States("name").FontUnderline, Object.States("name").FontStrikeout

Let you get/set individual font options.

also Object.States("name").SetShadow

This allows you to assign the shadow options of a state or all states of an object.
Object.SetShadow boolEnabled, sharpness, darkness, offsetX, offsetY, sdwColor

Sharpness ranges from 0 to 100.
Darkness can take values greater than 255.


  • It let change script at runtime. This has a couple of rules:

    Path can be either relative to local path (CurrentTheme) or full path. Files pointed to relative paths are automatically saved into .dxpack/.desktop/.exe packages.
  • ActiveX dynamic scripting is not yet supported.
  • An object must be first configured as scripted and eventually have a blank script if no real script is initially needed.
  • The default script, edited from DesktopX GUI will not be used, if overridden by an external script, unless the external script is "unlinked" by calling Object.SetScript("").


Let you get/set the current cursor.

0 = Normal select
1 = Help select
2 = Working in background
3 = Busy
4 = Precision select
5 = Text select
6 = Handwriting
7 = Unavailable
8 = Vertical resize
9 = Horizontal resize
10 = Diagonal resize 1 (NW-SE)
11 = Diagonal resize 2 (NE-SW)
12 = Move
13 = Alternate select
14 = Hand


Object Callbacks

These are events to which an object can respond. Script can be placed within these Subroutines and Functions to perform actions when these events occur.

For functions, you should also return True or False at the end of the function as a clean coding practice. Returning True stops DesktopX processing additional events, which means that you can use functions like Object_OnRButtonDown to perform actions other that displaying the DesktopX right click menu (if enabled). You should return False otherwise.

Object callbacks and scripts

Starting with 3.0 release, you don’t need a script just to respond to an Object callback. Child objects events will be automatically notified to the parent script, if one exists. It means you only need one script in the root parent object to get all events from its descendants, for instance Object_OnLButtonUp.
To support this new style of coding and support pre-3.0 scripts at the same time, all callbacks described in this chapter, except for Object_OnScriptEnter and Object_OnScriptExit, also exist in *Ex form. *Ex callbacks have an additional first parameter of type Object.

Standard callback:

Sub Object_OnLButtonDown(x,y) ‘only called if the object has a script associated

Ex callback:

Sub Object_OnLButtonDownEx(obj,x,y) ‘receives events from the object and all its children
Select case
Case “mybutton01”
‘do something
Case “mybutton02”
End Select
End Sub

Sub Object_OnScriptEnter

Occurs as soon as the script is enabled, which usually occurs when an object is loaded.

Sub Object_OnScriptEnter
Object.Text = Object.PersistStorage("mytext")
End Sub

Sub Object_OnScriptExit

Occurs as soon as the script is disabled, which usually occurs when an object is unloaded.

Sub Object_OnScriptExit
Object.PersistStorage("mytext") = Object.Text
End Sub

Sub Object_OnStateChange(state), Sub Object_OnStateChanged(state)

When the state of the object changes state these events are called and the variable (state) is identified allowing this one event to deal with all states.
The differentiating factor is that OnStateChange is called as the change commences, and the OnStateChanged event occurs when the state change has completed. OnStateChanged is particularly useful for the synchronization of animated objects and effects.

Note: Setting Object.StatePreempt inside Object_OnStateChange will actually have the special effect of switching the state being changed to the specified state. For instance you can hijack "Mouse over" messages to "MyMover1" and "MyMover2" depending on some state information.
Note: You can usually more effectively use Object_OnMouseEnter and Object_OnMouseLeave notifications instead of checking for “Mouse over” and “Mouse away” states in Object_OnStateChange. It is more efficient because those events are direct and don’t rely on animation delays and queued animated states completitions.

Note: Any references to states should be case sensitive.


Sub Object_OnStateChange(state)
If state = "Mouse over" Then
Object.Opacity = 100
ElseIf state = "Mouse away" Then
Object.Opacity = 50
End If
End Sub

Sub Object_OnMouseEnter, Sub Object_OnMouseLeave

This is the cleaner way to check for user mouse interaction with an object. By using this you can avoid your code for these events being combined with other the state change code. You can use the OnMouseButton functions described later in combination with these very effectively.

Sub Object_OnMouseEnter
Object.Opacity = 100
End Sub
Sub Object_OnMouseLeave
Object.Opacity = 50
End Sub

Sub Object_OnShow(IsVisible)

This function is triggered whenever the visibility of an object changes. A single variable is respond which is “True” or “False” depending on whether the object is being shown or hidden.

Sub Object_OnShow(IsVisible)
If IsVisible = True Then
msgbox "Showing object"
msgbox "Hiding object"
End If
End Sub

Sub Object_OnMove(x, y)

This function is triggered whenever the position of an object changes, but it via mouse or keyboard movement, or by script manipulation. The coordinates of it’s new position are returned.

Sub Object_OnMove(x,y)
If x < 100 Then Object.Left = 100
End Sub

Sub Object_OnSize(width, height)

If the objects size is adjusted then you can react to this event using this subroutine. In the following example the event ensures that the proportions of the object are constrained if the object gets resized.

Sub Object_OnSize(width, height)
Object.Height = Object.Width / 2
End Sub

Sub Object_OnDropFiles (files)

This event is triggered if the user drags one or more files onto the object and releases the mouse. A variable is returned containing the full path of all the files separates by a pipe (“|”) character.

Dim filelist
Sub Object_OnDropFiles(files)
filelist = Split(files,"|")
For x = 0 To UBound(filelist)
outputmsg = outputmsg & filelist(x) & vbNewLine
msgbox outputmsg
End Sub

Sub Object_OnDrag(x, y, newX, newY)

This event is fired as the object is dragged. The x and the y coordinates correspond the where on the object the click occurred and the “newPos” coordinated specify the top left position of the object in the position it has been dragged to. If the object’s position is locked then the x,y coordinated report a position relative to where the object was originally clicked. You can get the position of the object before it was dragged using Object.Left and Object.Top
The example below allows you to drag an object to within 100 pixels of the primary monitor screen edge but no further.


Sub Object_OnDrag(x, y, newX, newY)
If newX < 100 Then Object.Left = 100
If (newX + Object.Width) > System.ScreenWidth - 100 Then
Object.Right = System.ScreenWidth - 100
End If
If newY < 100 Then Object.Top = 100
If (newY + Object.Width) > System.ScreenHeight - 100 Then
Object.Bottom = System.ScreenHeight - 100
End If
End Sub

Sub Object_OnDragFinish

This event occurs when you finish dragging the object so you can react to the new position of the object. For example, the script below ensures that after an object has been moved then a second object is placed directly underneath it wherever it is placed.

Sub Object_OnDragFinish
DesktopX.Object("obj2").Top = Object.Bottom
DesktopX.Object("obj2").Left = Object.Left
End Sub

Sub Object_OnSetFocus, Sub Object_OnKillFocus

These events occur when an object receives or loses the focus. This means that you can react to a user starting to interact with or ending interaction with an object. You may just want to draw attention to the fact that the object has the focus of do something more like validate the input of a DesktopX Edit control if the user tries to leave it.

Sub Object_OnSetFocus
Object.state = "FocusON"
End Sub

Sub Object_OnKillFocus
Object.state = "FocusOFF"
End Sub

Function Object_OnChar(key, extended)

If an object has the focus then this function is called when a key is depressed and the ASCII character code is returned in the variable. Note that ‘a’ and ‘A’ return different values so this event is well suited to responding to a user typing. It also returns a code to represent extended variables. These are not really necessary to interpret and can be ignored.

Function Object_OnChar(key, extended)
Msgbox "You pressed the " & Asc(key) " key which has the ASCII value of " & key
Object_OnChar = False
End Sub

Function Object_OnKeyDown(key, flags), Function Object_OnKeyUp(key, flags)

This returns the actual key pressed rather than the ASCII value of the character returned. As such it is better suited to when you want to return the actual key such as an arrow key or Shift key. Note that in Edit mode certain keys such as the arrow key will move the object rather than respond to your code, but when in User mode as you should be whenever possible it will work fine.

You can get a list of the valid key values here:

You need to define the constant at the beginning of the script if you want to use a textual name for clarity.
There is only really one useful extended value which will stop a character from repeating. This is shown in the second example.

Const VK_SHIFT = &H10 'Shift Key
Function Object_OnKeyDown(key, extended)
If key = VK_SHIFT Then
Msgbox "Shift pressed"
End If
Object_OnKeyDown = False
End Function

The below example will move an object when it is selected and the enter key is pressed, but will not repeat the movement if the key is help; so the user must actively click the key again to do this.

Const EnterKey = &H0D
Const Repeat = &H40000000
Function Object_OnKeyDown(key, flags)
If key = EnterKey Then
If Repeat <> (flags And Repeat) Then
Object.Move Object.Left + 10, Object.Top
End If
End If
End Function

Function Object_OnLButtonDown(x, y), Function Object_OnRButtonDown(x, y), Function
Object_OnLButtonUp(x, y, Dragged), Function Object_OnRButtonUp(x, y, Dragged)

These functions are called as soon as the corresponding mouse button is pressed or released. In all cases two variables are returned which are the x and y coordinates within the object (i.e. not the screen position). In the ButtonUp functions, a third is returned True or False depending on whether the object has been dragged or not.

Function Object_OnLButtonDown(x, y)
Object.PersistStorage("x") = Object.Left
Object.PersistStorage("y") = Object.Top
Object_OnLButtonDown = False
End Function

Function Object_OnLButtonUp(x, y, Dragged)
If Dragged = True Then
Msgbox "You moved the object " & Object.Left - Object.PersistStorage("x") & " pixels horizontally and " _
& Object.Top - Object.PersistStorage("y") & " pixels vertically"
End If
Object_OnLButtonUp = False
End Function


System Namespace

System.CursorX, System.CursorY

These returns the current coordinates of the mouse cursor.

Object.Text = "X:" & System.CursorX & " Y:" & System.CursorY


This returns the color of the pixel at the specified coordinates.

Sub Object_OnTimer1
hexcolor = Hex(System.PixelColor(System.CursorX, System.CursorY))
red = Right(hexcolor, 2)
green = Mid(hexcolor, 2,2)
blue = Left(hexcolor, 2)
Object.Text = CStr(CLng("&H" & red)) & ", " & CStr(CLng("&H" & green)) & ", " & CStr(CLng("&H" & blue))
End Sub

System.InternetConnected, System.Ping

Many good examples of DXScript objects make use of the Internet, so it makes sense to detect whether access to the Internet is available. You can also check the speed of access to a web address (ping) by using System.Ping.

1) If System.InternetConnected = False Then Msgbox "Go online"
2) x = System.Ping("")


This allows you to specify the Windows wallpaper. You need to provide a full path to the wallpaper and then an option to feine how to display the wallpaper.

0 = use default wallpaper
1 = Center wallpaper
2 = Tile wallpaper
3 = Stretch wallpaper


System.SetWallpaper "C:\temp\wall1.bmp", 1
System.SetWallpaper Object.Directory & "wall1.jpg", 1
System.SetWallpaper "", 0 This will restore the original wallpaper.

System.ScreenWidth, System.ScreenHeight

System.ScreenHeight and System.ScreenWidth return the height and width of the primary monitor. This is mostly kept for backward compatibility. New objects should use System.Vscreen* properties instead, since these are multimonitor compatible (see the next chapter).

Msgbox "Primary monitor resolution: " & System.ScreenHeight & "x" & System.ScreenWidth

System.VscreenLeft, System.VScreenTop, System.VScreenWidth, System.VScreenHeight

These are the suggested properties to use when checking the monitor coordinates, since they take in consideration the whole virtual screen area, and not only the primary monitor. This will still work in a single monitor setup but will also support multi-monitor setups.
Note that the virtual screen origin is NOT generally (0,0), but it is (VscreenLeft, VscreenTop). Because of this .VscreenWidth returns the WIDTH of the virtual screen, not the right border! To calculate the right and bottom borders use the following code:

VirtualScreenRight = System.VScreenLeft + System.VScreenWidth
VirtualScreenBottom = System.VScreenTop + System.VScreenHeight

System.WorkareaLeft, System.WorkareaRight, System.WorkareaTop, System.WorkareaBottom

These properties retrieve the boundaries of the desktop workarea. This is usually even better than System.Vscreen* properties to base calulations for moving and keeping objects in the wanted position, since it represents the actual “available” working area.

System.FolderDialog (info, initialDir, flags)

This shows a dialog that allows the user to select a specific folder which can then be acted upon. The parameters to provide are a string which places information at the top of the dialog, the path where browsing should commence from, and then a range of customization flags. The full list of the flags is shown below:

'Only file system directories
'No network folders below domain level
'Allows user to rename selection
'Insist on valid edit box result (or CANCEL)
'Allow URLs To be displayed Or entered
'Only returns computers
'Only returns printers
'Browse for everything
'Sharable resources displayed


x = System.FolderDialog ("Please select your image folder:", "c:\", BIF_RETURNONLYFSDIRS)
Const BIF_EDITBOX = &H10
x = System.FolderDialog ("", "", BIF_EDITBOX)
x = System.FolderDialog ("Please select the directory:", DesktopX.ExecutableDirectory, BIF_BROWSEINCLUDEFILES)

System.FileOpenDialog (title, defaultFile, intialDir, extensions, flags), System.FileSaveDialog (title, defaultFile, intialDir, extensions, flags)

This shows a dialog that allows the user to select a specific folder which can then be acted upon. The parameters are a title for the dialog, the default file name, the path where browsing should commence from. You then specific the file types to select in the dialog in a series of pipe (‘|’) separated description/extention pairs such as Text files|*.txt|All files|*.* .
Finally, you can provide a range of customization flags. The full list of the flags is shown below:

'Causes the Read Only check box to be selected when the dialog is created
'Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file
'Hides the read only check box
'Restores the current directory if the user changes directory while searching
'Allow invalid characters in the returned file name
'Specifies that the user typed a file name extension that differs from the default extension specified
'Specifies that the user can type only valid paths and file names
'User can type only names of existing files in the File Name entry field
'If a file that doesn’t exist is selected ask for confirmation to create it
'If the command fails because of a network sharing violation, error is ignored
'Specifies that the returned file does not have the Read Only check box selected and is not in a write-protected directory
'Specifies that the file is not created before the dialog box is closed
'Hides and disables the Network button
'Directs the dialog box to return the path and file name of the selected shortcut (.LNK) file. If this value is not specified, the dialog box returns the path and file name of the file referenced by the shortcut


x = System.FileSaveDialog("My title", "new.txt", "c:\", "Text files|*.txt|All files|*.*",0)
x = System.FileOpenDialog("Select document ...", "", Desktopx.ExecutableDirectory & "docs", "DesktopX Help|*.pdf", 0)


This allows to establish the state of any given key from the list available here:

The value returned is either 0 (), 1 (), or 2 () depending on the key state.

Function Object_OnLButtonUp(x,y,dragged)
Const VK_NUMLOCK = &H90
x = System.KeyState(VK_NUMLOCK)
If x = 0 Then
msgbox "NumLock is Off"
ElseIf x = 1 Then
msgbox "NumLock is being pressed"
ElseIf x = 2 Then
msgbox "NumLock is On"
End If
End Function


Property to get and set the text content of the system clipboard.

System.Clipboard = Object.text


Property to get the percentage of current CPU activity.

Object.text = “CPU usage: “ & System.CPUActivity & “%”


Property to get/set the system audio volume level (0-100).


Property to get/set the system audio muting (boolean).


Sets the current desktop solid color.

System.DesktopColor = RGB(128, 128, 128)

System.DownloadFile(remoteUrl, localPath, bAsync)

Downloads a remote file.

RemoteUrl points to the remote file location.
LocalPath points to the local postition to save the file.
bAsync is a boolean value that tells the host to download the file synchronously (the function return only when the file is downloaded) or asynchronously (the function returns immediately and a System_OnDownloadFinish(url) callback is used to notify when the download has finished.


System.DownloadFile "", "c:\temp\", True

Sub System_OnDownloadFinish(url)
'url equals ""
End Sub

System.SendRequest(remoteUrl, postParams, bAsync)

Sends an HTTP request (POST or GET).

RemoteUrl points to the remote page location.
PostParams can contain a string to pass POST parameters. If no parameters are passed there, GET is used. You can also pass GET parameters in remoteUrl using standard conventions.
bAsync is a boolean value that tells the host to request the page synchronously (the function return only when the page is completely downloaded) or asynchronously (the function returns immediately and a System_OnRequestFinish(url, pagecontent) callback is used to notify when the download has finished.


strPage = System.SendRequest("", "param1=123&param2=456", false

strPage = System.SendRequest("", "param1=123&param2=456", true

Sub System_OnRequestFinish(url, pagecontent)
If instr(szurl, "page2.asp") > 0 Then
'parse pagecontent...
End if
end sub

System.SimpleWrite(path, content, param)

It writes a file to disk with passed content.
Only param=1 is currently supported.


System.SimpleWrite baseDir & "Data/mylog.txt", logString, 1

System.SimpleRead(path, param)

It reads a file from disk to a string variable.

Only param=1 is currently supported.


txtLog = System.SimpleRead(baseDir & "Data\mylog", 1)


System Callbacks

Sub System_OnScreenChange

If the screen resolution changes then you may wish to resize or reposition the objects accordingly.
Since this is supposed to be a custom repositioning code, depending of particular wanted behaviours, it is recommended that you set the automatic repositioning in the “Relation” tab to “Disabled” for both horizontal and vertical axis.


Sub System_OnScreenChange
Object.Width = System.ScreenWidth - 350
End Sub

Sub System_OnWorkareaChange

If the workarea changes (as result of screen resolution changes or taskbar resize) you may want to resize or reposition the objects accordingly.
Since this is supposed to be a custom repositioning code, depending of particular wanted behaviours, it is recommended that you set the automatic repositioning in the “Relation” tab to “Disabled” for both horizontal and vertical axis.


Sub System_OnScreenChange
Object.Width = System.ScreenWidth - 350
End Sub


DesktopX Namespace

These allow you to refer to the DesktopX environment, the objects within in and also the DesktopX application itself.

DesktopX.Object, DesktopX.ScriptObject

You use these two items to refer to objects other than the current one. You should use the first for non scripted objects.


DesktopX.Object("mytextobject").Text = “Hello”
DesktopX.Object("otherobject").Top = Object.Bottom

If the object is scripted however, you need to identify whether you are referring to the object itself or the control contained within.


DesktopX.ScriptObject("scr_textobject").Object.Text = “Hello”
DesktopX.ScriptObject("scr_textcontrol").Object.Left = 300
DesktopX.ScriptObject("scr_textcontrol").Control.Text = “Type”


This allows you to query the existence of another object in the theme which you may choose to do before you interact with it, because it could have been deleted.


Sub Object_OnScriptEnter
If DesktopX.IsObject("textobj") = False Then
Msgbox "Sorry – important data is missing!"
End If
End Sub

DesktopX.ExecutableDirectory (only for Pro apps)

If you are running DesktopX Pro, then the created EXE may be running from any location, so it is sometimes useful to know where this is. DesktopX.ExecutableDirectory will return this directory.


Returns the host that is currently running the object. Return values are:

1 – DesktopX Client
2 – DesktopX Builder
3 – Widget runtime
4 – DesktopX PRO application
0 – Unknown


It swaps out unused memory. Useful after using some COM object, ActiveX object, graphics, etc that's not going to be used often anymore until unload.


It quits DesktopX, current widget or gadget. Params is currently unused. Set to 0.

DesktopX.MsgBox(msg, flags, title, owner)

Zorder and thread-friendly Msgbox replacement.
Msg is the actual messagebox content.
Flags contains standard flags. See MS Win32 SDK here:

Title contains the caption string and owner the owner object name (used to fix the messagebox z-order).


Widget Namespace

If you are creating a widget there are several script commands that you can use to replicate the functionality of the widgets and provide additional user feedback.

Widget.Minimize, Widget.Restore, Widget.About, Widget.Close

These simply replicate the options available from the various widget menus to allow you to achieve the functionality via script.returns the current coordinates of the mouse cursor.


If you have specified that your widget is displayed in the taskbar then this command will set the text of that taskbar item. Where a system tray icon is used, it will set a tooltip for that item.

Widget.Caption = "This has been updated"


A user can specify whether to run an application on startup by right clicking the object, but you can also access this functionality via script. This allows you to either prompt the user when they first run the object, or to provide some sort of menu option.


If Widget.Autorun = False Then
x = Msgbox (“Would you like to run this object when you start Windows?”, vbYesNo + vbQuestion, “Autorun …”)
If x = vbYes Then
Widget.Autorun = True
End If
End If


Normally object events are fired to the parent if the child isn’t handling them directly. If the parent isn’t handling them, events are lost. You can configure a script of a widget to be the target of all unhandled events, regardless of parent/children relations.
To do that you can write the following code in Object_OnScriptEnter



Opens the Widget Properties panel programmatically.


Let you selectively disable standard preference options from the widget options. Values can be a combination of the following values:

&H0001 - Removes the opaticy option
&H0002 - Removes the shadow option
&H0004 - Removes the zorder option
&H0010 - Removes the accessibility option
&H0020 - Removes the autorun option


Brings the widget on foreground of other window.


Widgets Preferences

DesktopX 3.0 widgets and gadgets can use an integrated mechanism to manage user preferences.
A “preference” is a local per-user setting that is initially set to a default value and then maintained across multiple executions of the same widget for the same user.
Widget preferences can integrate into the standard widget properties dialog, or can be kept hidden if the author only likes to use persistency and not the interactive feature.

Preferences should be configured in script in Object_OnScriptEnter.
To add a preference object use:

Widget.AddPreference "PreferenceName"

To access a preference object use:


To access a preference property use:



Widget.AddPreference "ZIPCode"
Widget.Preference("ZIPCode”).Type = "Text"
Widget.Preference("ZIPCode”).Caption = "ZIP Code"
Widget.Preference("ZIPCode ").DefaultValue = "12345"
Widget.Preference("ZIPCode").Description = "It defines the ZIP area code to be used by the weather widget"

It creates a ZIPCode item of Text type and is initially set to “12345” with the given description for the Properties panel.

To access the configured value you can later use:

Widget.Preference("ZIPCode ").Value

When the user changes the preferences through the Widget Properties dialog, the script that configured the preferences receives the following event:

Sub Widget_OnPreferencesChange()

Here is the complete Preference namespace reference:

Widget.AddPreference “name”

Adds a new preference item. The name should not contain spaces. Use Preference.Caption to assign a pretty name.


String property. It defines Valid types are:
“Hidden”: No control will be displayed in the Widget properties panel. Hidden is the default type.
“Text”: Text box control type.
“Password”: Text box with obfuscated characters for password entries.
“Checkbox”: Checkbox control. Values for checkboxes are “1” or “0”.
“ComboEdit”: Editable text combobox control.
“ComboList”: Dropdown list combobox control.
“Slider”: Slider control. Values for sliders are still in string form.
"File": Edit control with Browse File feature
"Folder": Edit control with Browse Folder feature
"Font": It is a "ComboEdit" preference, but it is automatically filled with available Font names.
"Color": It provides a color picker preference.
"Hotkey": Hotkey selection control. You can directly pass preference value to Object.RegisterHotkey like:

Object.RegisterHotkey myHotkeyID, Widget.Preference("myHotkey").Value


Sets the pretty name used to name the preference in the Properties panel.


Use to set the preference default value.


Use to set the preference description that appears in the Widget properties panel.


Use to add an item to a Combobox preference.

Widget.Preference("MyCombo1").AddValue "Green"
Widget.Preference("MyCombo1").AddValue "Red"

Preference.MinValue, Preference.MaxValue

Use to configure the minimum and maximum values of a slider preference.


Widget.Preference("Slidersample").MinValue = 1
Widget.Preference("Slidersample").MaxValue = 5


It specifies the ticks distance for slider preferences.


Widget.Preference("Slidersample").MinValue = 10 ‘page size of 10 and displayed tick each 10 values.

Sub Widget_OnPreferencesChange

Sent when the user applies the preferences in the Widget properties panel.


Scriptable Popup Menu

You can create simple popup menus and replace the default system tray menus for DesktopX and widgets with scripting.
To create a popup menu use DesktopX.CreatePopupMenu.

Dim menu
Set menu = DesktopX.CreatePopupMenu
menu.AppendMenu 0, 1, "Item1"
menu.AppendMenu 0, 2, "Item2"
Dim result
res = m.TrackPopupMenu(0, System.CursorX, System.CursorY)

Note: popup menus cannot be used by scripts that run in a separated thread.

Syntax as follow:


AppendMenu flags, ID, text

ID is the item identifier. When the menu is shown and the user selects an item, TrackPopupMenu will return the ID of the item.
Text is simply the text.
Flags let you specify the following options you can combine:
&H00000800 – Menu separator
&H00000001 – Grayed
&H00000002 – Disabled
&H00000008 – Checked
&H00000010 – Popup
&H00000020 – Menu bar break
&H00000040 – Menu break
&H00000080 – Hilite

Popup (&H00000010) let you add a submenu. You can do like this:

Dim submenu
Set submenu = DesktopX.CreatePopupMenu
submenu.AppendMenu 0, 1, "Item in submenu"
Dim menu
Set menu = DesktopX.CreatePopupMenu
menu.AppendMenu &H00000010, submenu.MenuID, "Sub menu"
menu.AppendMenu 0, 2, "Item in main menu"


Result = TrackPopupMenu(flags, posx, posy)

It let you open the menu. It returns the ID of the selected item.
Posx and posy are the screen coordinates where the menu should open.
Flags let you specify some options:
&H00000004 – Center align
&H00000008 – Right align
&H00000010 – Vertical center align
&H00000020 – Bottom align


res = m0.TrackPopupMenu(0, System.CursorX, System.CursorY)


Controller Scripts

In the newest DesktopX release you can register an object and its script to act as a controller for certain functions. Only the controller receives some messages like system tray messages (i.e. the right-click message on the widget right click menu).

To register an object as a controller use Desktopx.RegisterController ObjectName

Sub Object_OnScriptEnter
desktopx.RegisterController Object.Name
End Sub

The object will then be called from the OnControl notification:

Function OnControl(lType, lCode)

End function

The host will call OnControl with messages information in lType and lCode. These messages are available:

 Z-order Think of as What it means
 lType   lCode   Description 
1 1 The systray menu is requested.
1 2 The widget menu is requested from object right-click.
2 0x0201 Left button down
  0x0202 Left button up
  0x0203 Left buttondouble-click
  0x0204 Right button down
  0x0205 Right button up
  0x0206 Right button double-click

Returning true to received messages will cause DesktopX not processing them. For instance you can replace the right click or systray widget menu by returning true to 1 / 1 notification and provide your own menu as described in the preceding chapter.



Forms is a new feature introduced in DesktopX 3.1. They are a sort of enhanced input box and are very similar to widget preferences.

You can use forms to prompt an input dialog to the user. Input elements are the same as the widget preference types:

You can create a work by calling:

Set frm = DesktopX.CreateForm

You can add input controls by calling:

frm.AddPreference "Text1"
frm.Preference("Text1").Type = "Text"
frm.Preference("Text1").DefaultValue = "Sample text pref"
frm.Preference("Text1").Caption = "Default text"
frm.Preference("Text1").Description = "This is a sample description"

To prompt the form simply call:


Then you can retrieve the form return values using:




It returns a new form object.


Gets/sets the form's caption.


Gets/sets the form's Ok button text.


Gets/sets the form's Cancel button text.


Prompts the form. It returns true if the user chose the Ok button, false otherwise.

Form.AddPreference "name"

Adds a new input item to the form. Input preference items are identical to widget preferences, (refer to the widget preferences section).

Previous Page     Next Page