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:
Object.property – 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 *

Object.Name
Object.Parent
Object.Visible

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.
Examples:

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

Object.Clone
Object.Delete

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.

Examples:

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.

Examples:

Object.Top = 500
Object.Move 500,200

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

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.

Examples:

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

Object.Resize

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

Examples:

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).

Examples:

For x = 0 To 255
Object.Hue = x
Next

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.
Examples:

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.
Examples:

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.
Example:

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

Object.ExecuteCommand

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.
Example:

Sub Object_OnScriptExit
Object.ExecuteCommand
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.

Example:

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

Sub Object_OnTimer12346
GetWeather(Object.LocalStorage("MyZip"))
End Sub

Sub Object_OnScriptExit
Object.KillTimer 12346
End Sub

Function GetWeather(zip)
...
End Function

Object.OnTop

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.
Example:

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

Object.SetFocus

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.
Example:

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

Object.TooltipText

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.
Example:

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

Object.AppBar

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
Example:

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

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

Object.Directory

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.
Example:

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

Object.Volume

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

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

Object.Picture
also Object.States("name").Picture

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

Object.Picture = “image01.png”
Object.States(“Mouse away”).Picture = “C:\images\image01.png”
Object.Picture = http://www.something.com/pic.png

Notes:
- 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.

Object.SetPicture
also Object.States("name").SetPicture

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

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

Object.CurrentFrame

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

Object.Child

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.

Object.SetMargins
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.
Syntax:
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.

Object.Group

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.
Syntax:
Object.RegisterHotkey hotkeyID, hotkeyValue

hotkeyValue is defined as a long in the same way the HKM_GETHOTKEY returns (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/
platform/commctls/hotkey/messages/hkm_gethotkey.asp):
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

Object.Comments

Gets/sets the object comments field

Object.SetFont
also Object.States("name").SetFont

Let you assign all font settings at once.
Syntax:
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.

Object.SetShadow
also Object.States("name").SetShadow

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

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

Object.SetScript(name)

• 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("").

Object.Cursor

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.

Examples:
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 obj.name
Case “mybutton01”
‘do something
Case “mybutton02”
‘etc
End Select
End Sub

Sub Object_OnScriptEnter

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

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.
Example:

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.

Example:

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.
Example:

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.
Example:

Sub Object_OnShow(IsVisible)
If IsVisible = True Then
msgbox "Showing object"
Else
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.
Example:

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.
Example:

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.
Example:

Dim filelist
Sub Object_OnDropFiles(files)
filelist = Split(files,"|")
For x = 0 To UBound(filelist)
outputmsg = outputmsg & filelist(x) & vbNewLine
Next
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.

Example:

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.
Example:

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.
Example:

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.
Example:

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: http://msdn.microsoft.com/library/en-us/winui/winui/windowsuserinterface/
userinput/virtualkeycodes.asp

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.
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.
Example:

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.
Example:

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

System.PixelColor

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

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.
Examples:

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

System.SetWallpaper

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.
Option:

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

Examples:

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).
Examples:

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
BIF_RETURNONLYFSDIRS = &H1
'No network folders below domain level
BIF_DONTGOBELOWDOMAIN = &H2
'Allows user to rename selection
BIF_EDITBOX = &H10
'Insist on valid edit box result (or CANCEL)
BIF_VALIDATE = &H20
'Allow URLs To be displayed Or entered
BIF_BROWSEINCLUDEURLS = &H80
'Only returns computers
BIF_BROWSEFORCOMPUTER = &H1000
'Only returns printers
BIF_BROWSEFORPRINTER = &H2000
'Browse for everything
BIF_BROWSEINCLUDEFILES = &H4000
'Sharable resources displayed
BIF_SHAREABLE = &H8000

Examples:

Const BIF_RETURNONLYFSDIRS = &H1
x = System.FolderDialog ("Please select your image folder:", "c:\", BIF_RETURNONLYFSDIRS)
Const BIF_EDITBOX = &H10
x = System.FolderDialog ("", "", BIF_EDITBOX)
Const BIF_BROWSEINCLUDEFILES = &H4000
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
OFN_READONLY = &H1
'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
OFN_OVERWRITEPROMPT = &H2
'Hides the read only check box
OFN_HIDEREADONLY = &H4
'Restores the current directory if the user changes directory while searching
OFN_NOCHANGEDIR = &H8
'Allow invalid characters in the returned file name
OFN_NOVALIDATE = &H100
'Specifies that the user typed a file name extension that differs from the default extension specified
OFN_EXTENSIONDIFFERENT = &H400
'Specifies that the user can type only valid paths and file names
OFN_PATHMUSTEXIST = &H800
'User can type only names of existing files in the File Name entry field
OFN_FILEMUSTEXIST = &H1000
'If a file that doesn’t exist is selected ask for confirmation to create it
OFN_CREATEPROMPT = &H2000
'If the command fails because of a network sharing violation, error is ignored
OFN_SHAREAWARE = &H4000
'Specifies that the returned file does not have the Read Only check box selected and is not in a write-protected directory
OFN_NOREADONLYRETURN = &H8000
'Specifies that the file is not created before the dialog box is closed
OFN_NOTESTFILECREATE = &H10000
'Hides and disables the Network button
OFN_NONETWORKBUTTON = &H20000
'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
OFN_NODEREFERENCELINKS = &H100000

Examples:

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)

System.KeyState(vk)

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

http://msdn.microsoft.com/library/en-us/winui/WinUI/WindowsUserInterface/UserInput/VirtualKeyCodes.asp

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

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

System.Clipboard

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

System.Clipboard = Object.text

System.CPUActivity

Property to get the percentage of current CPU activity.
Example:

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

System.Volume

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

System.Mute

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

System.DesktopColor

Sets the current desktop solid color.
Example:

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.

Example:

System.DownloadFile "http://www.mysite.com/myfile.zip", "c:\temp\myfile.zip", True

Sub System_OnDownloadFinish(url)
'url equals "http://www.mysite.com/myfile.zip"
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.

Example:

strPage = System.SendRequest("http://www.mysite.com/page.asp", "param1=123&param2=456", false

strPage = System.SendRequest("http://www.mysite.com/page2.asp", "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.

Example:

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.

Example:

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.

Example:

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.

Example:

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.

Examples:

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.

Examples:

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

DesktopX.IsObject

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.

Example:

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.

DesktopX.HostType

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

DesktopX.GarbageCollection

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.

DesktopX.Exit(params)

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: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/
windowsuserinterface/windowing/dialogboxes/dialogboxreference/dialogboxfunctions/messagebox.asp
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.

Widget.Caption

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.
Example:

Widget.Caption = "This has been updated"
Widget.Autorun

Widget.Autorun

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.

Example:

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

Widget.RegisterController

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

Widget.RegisterController Object.name

Widget.OpenProperties

Opens the Widget Properties panel programmatically.

Widget.StandardPreferencesOptions

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

Widget.OnTop

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:

Widget.Preference("PreferenceName")

To access a preference property use:

Widget.Preference("PreferenceName").property

Example:

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.

Preference.Type

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

Preference.Caption

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

Preference.DefaultValue

Use to set the preference default value.

Preference.Description

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

Preference.AddValue

Use to add an item to a Combobox preference.
Example:

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.

Example:

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

Preference.Ticks

It specifies the ticks distance for slider preferences.

Example:

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.
I.e.

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

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"

TrackPopupMenu

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

Example:

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
Example:

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:

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

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:

frm.Prompt

Then you can retrieve the form return values using:

frm.Preference("Text1").value

Reference

DesktopX.CreateForm

It returns a new form object.

Form.Caption

Gets/sets the form's caption.

Form.OkButton

Gets/sets the form's Ok button text.

Form.CancelButton

Gets/sets the form's Cancel button text.

Form.Prompt

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).