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 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
PDF available
