Scripts

SysStats allows you to write your own meters and controllers using any script language that supports the Windows Script Host mechanism. Typically this means VBScript.

 

This document documents how SyStats interfaces to such a script – what functions it expects to find and what objects and functions the script can call to control SysStats.

 

ScriptMeter 1

Synchronous v. ASynchronous. 3

ScriptController 3

Synchronous v. ASynchronous. 3

WScript 3

SysStatsModel 4

Collections. 5

Label 6

Meter 6

DiskMeter 8

FixedMeter 8

MBMMeter 8

MemoryMeter 9

PDHMeter 9

ScriptMeter 9

TimeMeter 10

XMLMeter 10

MailMeter 11

Animation. 11

Overlay. 12

SimpleOverlay. 13

SimpleOverlay2. 14

GaugeOverlay. 15

ImageOverlay. 15

MeterOverlay. 16

TextOverlay. 16

CompositeOverlay. 18

MappedOverlay. 18

Scroller 19

Animator 20

Controller 21

ValueSetter 21

MessageSender 22

ScriptController 22

ASyncScriptController 22

Shortcut 22

DropTargetController 23

Mapped. 23

Cursor 23

Timer 23

AppConfig. 24

 

ScriptMeter

Add a ScriptMeter using the ‘Configure meters…’ dialog and configure it by selecting the script and specifying its type – if you ever need to reload the script (if you edit the script for example) you will have to re-select the same file to get SysStats to re-load it.

 

SysStats communicates with a script meter through three pre-defined functions:

 

ScriptMeter_Update()

ScriptMeter_GetValue(selector)

ScriptMeter_PutValue(value)

 

Any given script can use any, all or none of these functions as it sees fit. In addition to these functions a script can define whatever other functions it likes – it is just these three functions that have a special meaning to SysStats.

 

ScriptMeter_Update()

This is called every interval seconds as set in the Configure meters… dialog. It should return true if the value of the meter has changed since it was last called, false otherwise.

 

ScriptMeter_GetValue(selector)

This is called whenever SysStats wants to get the latest value of the meter. This is not necessarily when ScriptMeter_Update() returns true – SysStats may need to retrieve the value for other reasons.

 

Selector is a string that is passed in by whatever overlay is trying to render it. Normally this value is set via the overlay’s configuration dialog. The script can use it however it likes – including totally ignoring it.

 

The value returned by the function can be:

·         A string

·         An integer

·         A float

It is up to the calling overlay to render the value properly.

 

ScriptMeter_PutValue(value)

This is typically called by a ValueSetter controller, though it could be called by another script.

 

So. One possible VB script would be:

 

myValue = 0

 

‘ Increment the value

Function ScriptMeter_Update

     myValue = myValue + 1

     ‘We always have a new value!

     ScriptMeter_Update = true

End Function

 

‘ Return the current value

Function ScriptMeter_GetValue(selector)

     ScriptMeter_GetValue = myValue

End Function

 

‘ Set the value

Function ScriptMeter_PutValue(newVal)

     myValue = newVal

End Function

 

In addition to a script being called by SysStats, a script can call SysStats. SysStats makes all of its objects available to a script in a structured fashion – this is often referred to as a ‘Document Object Model’. If you’ve ever scripted a web page, you will probably already have come across one DOM.

 

Synchronous v. ASynchronous

There are two flavors: Synchronous and Asynchronous. If you use a synchronous script controller SysStats waits for its HandleMessage() function to complete. If you use an ASyncScriptController SysStats will not wait for the function to complete.

ScriptController

A script controller is a controller that you write in a scripting language such as VBScript.

 

SysStats communicates with a script controller through one pre-defined function:

ScriptController_HandleMessage(wparam, lparam, x, y)

The arguments are the windows message wparam and lparam values and the x and y location of the mouse pointer relative to the docklet’s window. See Microsoft’s documentation on these for complete descriptions.

 

The return value should be true if you want to stop any further processing of the message by the docklet. False otherwise.

 

Synchronous v. ASynchronous

There are two flavors: Synchronous and Asynchronous. If you use a synchronous script controller SysStats waits for its HandleMessage() function to complete. If you use an ASyncScriptController SysStats will not wait for the function to complete.

 

WScript

This is one of two global objects that SysStats makes available to scripts. This one mimics some of the functionality of Microsoft’s WScript object. Namely:

 

ConnectObject(object, prefix)

This connects the event methods of an existing COM object to the script using the passed prefix.

 

Disconnect(object)

This disconnects a previously connected object.

 

DisconnectAll()

This disconnects all objects previously connected with ConnectObject().

 

Echo(string)

This echos a single string to the script’s console. This can be useful for debugging!

SysStatsModel

The ‘root’ of SysStat’s DOM is the ClientModel. You can access this object using a variable called SysStatsModel: Here’s an example:

 

Value = 0

 

Function ScriptMeter_Update

     ‘We always have a new value!

     ScriptMeter_Update = true

End Function

 

‘ Return the previous value + 1 and rotate the overlay

‘ at position 0 by value degrees clockwise.

Function ScriptMeter_GetValue(selector)

     Value = Value + 1

     ScriptMeter_GetValue = Value

     SysStatsModel.Overlays(0).Rotation = Value

End Function

 

The key to using SysStat’s ClientModel is knowing your way around it.

 

The client model holds all of the overlays, meters and controllers for a single instance of SysStats (or, for a single config, which amounts to the same thing):

 

Meters

This is an collection of all of the meters in this config. The collection can be indexed by number or name. Numerical indices always start at 0. So SysStatsModel.Meters(0) will return you the first meter in the list. SysStatsModel.Meters(“first”) will return you the meter called first (or the first one in the list with that name if you have several with the same name!).

 

Overlays

This is a collection of all of the overlays in this config. The collection can be indexed by number or name. Numerical indices always start at 0.. So SysStatsModel.Overlays(0) will return you the first overlay in the list. SysStatsModel.Overlays(“first”) will return you the overlay called first (or the first one in the list with that name if you have several with the same name!).

 

If you’ve looked at some of the existing configs you might have noticed that overlays can be nested inside other overlays so SysStatsModel.Overlays(0) might return you another collection of overlays, which might return another collection of overlays etc. etc.. A script should know what to expect.

 

NOTE: This is in fact just one example of polymorphism: Although each type of overlay (and each type of meter for that matter) all share a common set of properties and functions, they can also have extra properties and functions too – specific to their own type. I’ll go into all of the properties and functions of each type a little later. But for now lets continue with the client model itself:

Controllers

Another collection (but you guessed that right?). This time of controllers (you probably guessed that too). The collection can be indexed by number or name. Numerical indices always start at 0. So SysStatsModel.Controllers(0) will return you the first controller in the list. SysStatsModel.Controllers(“first”) will return you the controller called first (or the first one in the list with that name if you have several with the same name!).

 

 

NOTE: SysStatsModel.Models(0) is in fact shorthand for: SysStatsModel.Models.Item(0). You see, collections have their very own properties too. You can get their size, and you can add elements to them. More on this later. Lets continue with the client model!

 

Label

This is an object that represents the label.

 

AppConfig

This object holds some configuration information for the model itself and provides some useful filepath manipulation functions.

 

Dirty

This is a simple Boolean value. If it is set to true SysStats will render all of the overlays. You can get it or set it. You might set this if you do some work using a timer, for example, and want to force SysStats to re-render the overlays afterwards.

 

X

The X location of the window. This is ignored in ObjectDock and YzDock.

 

Y

The Y location of the window. This is ignored in ObjectDock and YzDock.

 

Width

The width of the window.

 

Height

The height of the window.

 

Name

The name of the docklet.

 

Description

The description of the docklet.

 

Version

The version of the docklet.

 

Author

The author of the docklet.

 

ConfigFile

The config file for this docklet.

 

hWnd

The handle to the window for this docklet.

 

UpdateMeters()

Calling this method is like selecting Update… from the context menu – it will call the Update method of every meter.

 

PostMessage(messageID, wParam, lParam)

This method will post the passed message onto the windows message queue for this docklet.

 

Load()

Load the config for this docklet.

 

Save(bool interactive)

Save this docklet. If interactive is true the docklet may open a confirmation dialog.

Collections

When something can have more than one value it is held in a collection. You can get at an entry in an collection using two techniques. Taking SysStatsModel.Overlays as an example, the following two statements will both return the entry at index 1:

 

SysStatsModel.Overlays(1)

SysStatsModel.Overlays.Item(1)

 

You can also get the number of entries in a collection using the Count() method. For example the following code retrieves the number of entries in the meters collection:

 

SysStatsModel.Meters.Count

 

You can also add and remove entries from a collection using the Add() and Remove() entries. Add() takes a single argument – the element to be added. Remove also takes a single argument – the index of the element to be removed.

Label

Label is accessed as SysStatsModel.Label.

 

Label has the following properties and functions:

Format

If the label has no meter associated with it, this will be the string that is displayed for the label.

 

If the label does have a meter associated with it, the meter will be called to return a value and that value might be used to make up the label. For example if the Format is ‘%d’ and the meter returns an integer that integer will be displayed in the label. If the Format is ‘This is a label’, it won’t matter what the meter value is – it won’t be displayed – the label will always read ‘This is a label’.

 

MeterIndex

An index into the collection of meters. This is the meter that will be called when rendering the label. A value of –1 means no meter.

 

selector

A string that will be passed to the meter when it is called to return a value. Its meaning depends on which meter is being called – most don’t use it.

 

GetLabel()

This will return the label string as it would be displayed, i.e. it will call any meter associated with the label and format the result.

Meter

Meters are held in a collection indexed from 0 and are accessed as SysStatsModel.Meters(n) - where n is the index of the meter, or as SysStatsModel.Meters(name) – where name is the name of the meter.

 

All meters share the properties and methods defined by Meter. In OO-speak, they inherit Meter.

GetAsLong(selector)

Returns the current value of the meter as a long integer.

 

Selector is a string that the meter can interpret any way it likes. Different types of meter (or sub-classes in OO-speak) will define how they interpret this value. It is typically used to select one value from several that the meter might hold – most meters only hold one value so most meters ignore this.

 

GetAsDouble(selector)

Returns the current value of the meter as a double.

 

See GetAsLong() above for an explanation of selector .

 

GetAsString(format, selector)

Returns the current value of the meter as a string.

 

Format is a string that the meter can interpret any way it likes. Different types of meter (or sub-classes in OO-speak) will define how they interpret this value. This will be described later for each type of meter.

 

See GetAsLong() above for an explanation of selector .

GetValue()

Returns the value of the meter as a variant. The type of the return value (integer, float, string etc.) will depend on the type of the meter.

 

This is also the default method for a meter – which will be explained below.

 

So we could use:

 

‘ Just return the value of the first meter:

Function ScriptMeter_GetValue(selector)

     DIM meter

      Set meter = SysStatsModel.Meters(0)

 

     ‘ This will call GetValue() on the meter:

     ScriptMeter_GetValue = SysStatsModel.Meters(0)

     ‘ So will this:

     ScriptMeter_GetValue = meter.GetValue()

     ` So will this:

     ScriptMeter_GetValue = meter

 

     ‘ This will return a string value from a time meter:

     ScriptMeter_GetValue = meter.GetAsString(“%H”, selector)

     ` This will return an integer value:

     ScriptMeter_GetValue = meter.GetAsLong(selector)

     ` This will return a double value:

     ScriptMeter_GetValue = meter.GetAsDouble(selector)

 

End Function

 

There are other methods and properties you can call too:

 

Update()

This may cause the meter to update its value – some meters update themselves independently, e.g. MBMMeter or TimeMeter .

 

It returns true if the value has changed since the last time Update was called.

 

Name

Is the name displayed in the ‘Configure meters…’ dialog.

 

Type

Is the type of the meter. e.g. a PDH meter has a type of ‘PDHMeter Class’.

 

Interval

This is the number of seconds that SysStats will wait between calling the Update() method. A value of 0 means that SysStats will never call the Update() method.

DiskMeter

DiskMeter is used to measure the space of a disk or partition. A meter of type DiskMeter adds three properties to those defined by Meter.

 

Path

Path is the path of the disk whose space will be monitored, e.g. C:

Selector

This is an integer that specifies what exactly should be monitored:

 

0 - % space used.

1 - % space free.

2 – Number of bytes used.

3 – Number of bytes free

4 – Total size in bytes

 

Scale

This is a value that specifies a scale factor for the value the meter returns. The value is divided by this number – for example a scale of 1024, coupled with a selector of 2 will cause the meter to return the number of kilobytes used.

 

FixedMeter

FixedMeter is used to hold an unchanging value. A meter of type FixedMeter adds a single property to those of Meter:

 

Value

This is the value that is to be stored. It should be a string (note that this doesn’t mean that it will be interpreted as a string by an overlay).

 

MBMMeter

MBMMeter is used to access values monitored by MBM. A meter of type MBMMeter adds three properties to those of Meter.

 

Index

This is the index of the probe being monitored.

 

Reading

This is an integer specifying exactly which value to return for the probe. It can be one of:

0 – the current value.

1 – the all-time-low value.

2 – the all-time-high value.

 

Scale

This is a value that specifies a scale factor for the value the meter returns. The value is divided by this number.

 

MemoryMeter

MemoryMeter is used to monitor RAM. A meter of type MemoryMeter adds two properties to those of Meter.

 

Selector

This is an integer that specifies what exactly should be monitored:

 

0 - % space used.

1 - % space free.

2 – Number of bytes used.

3 – Number of bytes free

4 – Total size in bytes

 

Scale

This is a value that specifies a scale factor for the value the meter returns. The value is divided by this number – for example a scale of 1024, coupled with a selector of 2 will cause the meter to return the number of kilobytes used.

 

PDHMeter

PDHMeter is used to monitor values using the Performance Data Helper APIs, through which a wide range of system performance metrics can be monitored. A meter of type PDHMeter adds two properties to those of Meter.

 

Counters

This is an array of strings that define what should be monitored. The format of these string is defined here. For example \Processor(_Total)\% Processor Time specifies the CPU usage.

 

Although this is an array, only the first entry is ever used by PDHMeter .

 

Scale

This is a value that specifies a scale factor for the value the meter returns. The value is divided by this number

 

ScriptMeter

ScriptMeter is used to execute a script supported by the windows scripting host (e.g. vbscript) as if it were a meter. See also here for more information. A meter of type ScriptMeter adds the following properties to those of Meter:

 

FileName

This is the path to the file containing the script.

 

ScriptType

This defines the script language. This can be one of:

            JavaScript

            Perl

            ActivePHP

            Python

            RubyScript

            vbScript

 

Value

If you set this property to a value the method ScriptMeter_PutValue(value).

TimeMeter

TimeMeter is used to monitor the time.

 

If the string value of a TimeMeter is accessed, the GetValue function requires a format string as defined here.

 

If a numeric value is accessed – the number of seconds since midnight is returned.

 

TimeZone

A long list of possible timezones culled from the following registry entry: LOCALMACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones

 

TZDescription

A description of the timezone.

XMLMeter

XMLMeter is used to retrieve an XML document and access values in it. A meter of type XMLMeter adds seven properties to those of Meter. All but the first of these require you to install MSXML4 on your computer. Do yourself a favor and install it J.

 

URL

The URL of the XML document.

 

Username

A username that can be used if the URL requires a username/password

 

Password

A password that can be used if the URL requires a username/password

 

ProxyURL

The URL of a proxy server – this might be required if you are behind a firewall.

 

ProxyUsername

A username that can be used if the proxy server requires a username/password

 

ProxyPassword

A password that can be used if the proxy server requires a username/password.

 

UseXPath

If true this will force the XML meter to use true xpath expressions. This may require that you define namespaces for the query.

 

NameSpaces

This is an array of strings defining namespaces in the XML document for use by XPath. These are only used if UseXPath is set to true. An example namespace definition is:

 

xmlns:a="http://purl.org/atom/ns#"

 

The namespace a can then be used in subsequent Xpath expressions such as:

 

format-number(count(//a:entry), '#')

 

Value

This attribute can be set to an XML document that is then used as the source for all of the other operations.

 

IXMLDOMNodeList *GetNodeList(String Xpath)

This method executes the passed Xpath expression and returns a nodelist.

 

When obtaining a value from an XMLMeter you need to provide a selector in the format of an XPath expression.

MailMeter

The mail meter is used to retrieve inbox information from MAPI mail clients such as Outlook and OutlookExpress. It adds the following properties to those of meter.

 

Username

If SysStats needs to authenticate it will use this username.

 

Password

If SysStats needs to authenticate it will use this password.

 

ValidDays

Mail message older than this value (in days) will not count as part of the value of the meter.

Animation

The animation meter is used to provide state information to animated overlays (or anything else that requires an animation state I guess). It adds the following properties and methods to those of meter:

 

FrameCount

The number of frames in the animation.

 

FrameRate

The rate in frames/sec of the animation.

 

PlayState

The current state of the animation – playing, paused etc. If you set the value it will force the animation into that state. This is how the animation is started/stopped etc.

 

Position

The current position of the animation. Start, end etc.

 

Loop

If true the animation should loop when it reaches the end.

 

AutoReverse

If true the animation will reverse after reaching either end.

 

SingleStep

If true the animation will pause after each frame.

 

PutValue(String selector, BSTR value)

This single method can be called to set a value specified by the selector to the passed value.

 

The selector can be one of:

·         framerate

·         framecount

·         loop

·         autoreverse

·         singelstep

·         autostart

·         playstate

·         position

·         currentframe

·         framedelta

·         step

 

Step()

Call this method to step the animation to the next frame.

 

AutoStart

If true the animation will start playing when SysStats loads.

 

StateMsg

This is a windows message that should be posted when the playstate of the animation changes.

 

StateLParam

This is the value of the LParam that should be passed with the message. WParam will be the new state and position of the animation.

Overlay

Overlays are held in an collection indexed from 0 and are accessed as SysStatsModel.Overlays(n). Where n is the index of the overlay. Some of the overlays retrieved may themselves be a collection.

 

All overlays share the properties defined by Overlay. In OO-speak, they inherit Overlay.

Name

Is the name displayed in the ‘Configure meters…’ dialog.

 

Type

Is the type of the overlay. e.g. an image overlay has a type of ‘ImageOverlay Class’.

 

MeterIndex

The index of the referenced meter in the list of meters. A value of –1 means no meter.

 

Visible

If this is false then the overlay will not be drawn. In fact, because it won’t be drawn it won’t get a chance to get the value of a meter. So if you set an overlay’s visibility to false in ScriptMeter_GetValue() , make sure that it isn’t the overlay that called ScriptMeter_GetValue() in the first place, or you might never get a chance to set it to true again.

 

Mode

The combination mode used when compositing the image. Ignored in this version of SysStats.

 

SimpleOverlay

SimpleOverlay is the base class for all of the overlays provided with SysStats. It adds the following properties to those defined by Overlay:

 

X

The x-coordinate in the docklet’s window at which the center of the overlay will be rendered.

 

Y

The y-coordinate in the docklet’s window at which the center of the overlay will be rendered.

 

Rotation

The angle in degrees running clockwise from 3 o’clock at which the overlay will be rendered. The overlay is rotated about its center.

 

CenterX

The x-coorindate of the center of the overlay measured from the top-left corner of the overlay itself.

 

CenterY

The y-coorindate of the center of the overlay measured from the top-left corner of the overlay itself.

 

HAlign

Some overlays do not have a fixed size (e.g. the TextOverlay). In that case this value is used to specify how the overlays boundaries should grow in the horizontal direction.

0 – Left Aligned: The left boundary is fixed – grow only to the right.

1 – Center Aligned: Grow equally to the left and right.

2 -  Right Aligned: The right boundary is fixed – grow only to the left.

 

VAlign

Some overlays do not have a fixed size (e.g. the TextOverlay). In that case this value is used to specify how the overlays boundaries should grow in the vertical direction.

0 – Top Aligned: The top boundary is fixed – grow only down the ways.

1 – Middle Aligned: Grow equally up and down.

2 -  Bottom Aligned: The bottom boundary is fixed – grow only upwards.

 

HScale

A scale factor for the horizontal direction. 1.0 = no scaling. The horizontal axis rotates with the overlay.

 

Vscale

A scale factor for the vertical direction. 1.0 = no scaling. The vertical axis rotates with the overlay.

 

Selector

A value used by some meters to select one from many possible values.

 

SimpleOverlay2

SimpleOverlay2 adds some extra features to those of SimpleOverlay:

bool HitTest(int X, int Y)

This method returns true if the pixel addressed by the passed X and Y value has a non-zero alpha channel (i.e. if the pixel is opaque).

 

Parent

This property holds a reference to the containing composite overlay (if any). If there is no parent, it holds NULL. The value should be treated as read-only.

 

EffectOverlay

This property holds a reference to an overlay that is used for masking this overlay.

 

EffectOverlayEffect

This defines how the effect overlay is used. It can be one of:

0 = Mask out

1 = Mask in

GaugeOverlay

GaugeOverlay draws a dial whose angle is determined by the value of a meter. An overlay of type GaugeOverlay adds the following properties to those defined by SimpleOverlay2, SimpleOverlay and Overlay:

Length

This is the length of the line drawn.

 

Thickness

This is the thickness of the line.

 

Span

This is the maximum number of degrees that the gauge can rotate.

 

Min

This is the meter value that is represented by a rotation of zero.

 

Max

This is the meter value that is represented by a rotation of Span degrees.

 

Color

This is the color of the line in BGR form! I.e. 0x00FF0000 is blue, 0x0000FF00 is green. 0x000000FF is red.

 

Alpha

This is the transparency of the line from 0 to 255 with 0 being totally transparent and 255 being totally solid.

 

ImageOverlay

ImageOverlay draws an image into the window. An overlay of type ImageOverlay adds the following properties to those defined by SimpleOverlay2, SimpleOverlay and Overlay:

Path

This is the pathname of the image.

 

Alpha

This is the transparency of the image from 0 to 255 with 0 being totally transparent and 255 being totally solid. This is in addition to any per-pixel transparency that the image may have.

 

ImageWidth

This is a read-only property giving the width of the source image in pixels. Note that the image drawn may differ if a scale factor is being used.

 

ImageHeight

This is a read-only property giving the height of the image in pixels. Note that the image drawn may differ if a scale factor is being used.

 

long GetPixelValue(int X, int Y)

This returns the value of the pixel at the given location.

 

Dispose()

ImageMeter caches the image. This will make it impossible to change the file containing the image. Calling this method causes the file to be released.

 

AnimationMeter

This is a reference to an AnimationMeter that can be used to control the animation of a multi-frame image.

 

HueShift

This is a value between –180 and 180 that is used to shift the hue of an image. The default of 0 means no hue shift.

 

Saturation

This is a value between 0 and 3 that controls the saturation of an image. A value of 0 will give a grey-scale image. The default value of 1 will leave the saturation unaltered.

MeterOverlay

MeterOverlay draws a bar whose length is determined by the value of a meter. An overlay of type MeterOverlay adds the following properties to those defined by SimpleOverlay2, SimpleOverlay and Overlay:

Length

This is the maximum number of pixels a meter can extend to. Depending on the value of a meter the MeterOverlay will extend from 0 to Length pixels.

 

Thickness

This is the thickness of the bar in pixels.

Min

This is the meter value that is represented by a zero length bar.

 

Max

This is the meter value that is represented by a bar of Length pixels.

 

Color

This is the color of the bar in BGR form! I.e. 0x00FF0000 is blue, 0x0000FF00 is green. 0x000000FF is red.

 

Alpha

This is the transparency of the bar from 0 to 255 with 0 being totally transparent and 255 being totally solid.

 

TextOverlay

TextOverlay draws a string. The size of an image rendered by a text overlay is not known until it is drawn, thus the HAlign and VAlign properties of SimpleOverlay are used to specify how the position of the image is adjusted as the size changes. Essentially the X location of the image is used as either the left, center or right of the drawn image and the Y location of the image is used as either the top, middle or bottom of the image.

 

The diagram below shows how text would be drawn if HAlign were set to center and VAlign were set to middle. Note that the vertical ‘middle’ is actually the baseline of the text., not the actual middle in pixel terms.

 

The picture is complicated a little if CenterX and CenterY are non-zero:

 

 

A meter of type TextOverlay adds the following properties to those of SimpleOverlay2, SimpleOverlay and Overlay:

Format

This determines the string that will be displayed. The format of this string is define here.

 

FontName

The name of the font face, e.g. ‘Arial’.

 

FontStyle

The font style, e.g. ‘Italic’.

 

FontSize

The font size.

 

FontColor

This is the color of the text in BGR form! I.e. 0x00FF0000 is blue, 0x0000FF00 is green. 0x000000FF is red.

 

Alpha

This is the transparency of the bar from 0 to 255 with 0 being totally transparent and 255 being totally solid.

 

Radius

This specifies a glow radius for the text.

 

BlurColor

Specifies the color of the glow in BGR form!

 

Width

If this is > -1 it specifies a clipping width for the text. This is also used to wrap the text if Wrap is set to true.

 

Height

If this is > -1 it specifies a clipping height for the text.

 

Wrap

If this is true and a clipping width is specified the text will be wrapped to fit inside the width.

 

AlternateRender

If this is true the following properties can be used to change how the text is drawn:

 

TextRenderingHint

This changes the anti-aliasing. It can be one of:

0 = Default (use system setting)

1 = No AntiAlias Grid Fit

2 = No AntiAlias

3 = AntiAlias Grid Fit

4 = AntiAlias

5 = ClearType

 

TextContrast

This should be a value between 1 and 8. Though it doesn’t seem to make any difference anyway!

 

CompositeOverlay

CompositeOverlays can contain other overlays. They behave like collections to scripting languages, so they can be indexed, entries can be added and entries can be removed.

 

Any type of overlay can be contained, including other CompositeOverlays.

 

CompositeOverlay inherits all of the methods of SimpleOverlay2, SimpleOverlay and Overlay.

MappedOverlay

A MappedOverlay is a special sort of ImageOverlay. It displays an image using a Map to control what portion of the main image is visible. This is all explained here.

 

MappedOverlay inherits all of the methods of SimpleOverlay2, SimpleOverlay and Overlay.

Min

This should be set to the minimum value of the meter being monitored. Often this is 0.

 

Max

This should be set to the maximum value of the meter being monitored.

 

MapPath

This is the pathname of the map.

 

ImagePath

This is the pathname of the image.

 

Alpha

This is the transparency of the image from 0 to 255 with 0 being totally transparent and 255 being totally solid. This is in addition to any per-pixel transparency that the image may have.

 

ImageWidth

This is a read-only property giving the width of the source image in pixels. Note that the image drawn may differ if a scale factor is being used.

 

ImageHeight

This is a read-only property giving the height of the image in pixels. Note that the image drawn may differ if a scale factor is being used.

 

long GetPixelValue(int X, int Y)

This returns the value of the pixel at the given location.

 

Dispose()

MappedMeter caches its images. This will make it impossible to change the files containing the images. Calling this method causes the files to be released.

 

HueShift

This is a value between –180 and 180 that is used to shift the hue of an image. The default of 0 means no hue shift.

 

Saturation

This is a value between 0 and 3 that controls the saturation of an image. A value of 0 will give a grey-scale image. The default value of 1 will leave the saturation unaltered.

Scroller

A scroller overlay is a special sort of composite overlay. It adds the following methods and properties to those of CompositeOverlay.

Alpha

This is the transparency of the image from 0 to 255 with 0 being totally transparent and 255 being totally solid. This is in addition to any per-pixel transparency that the image may have.

 

dx

This is the amount that the x coordinate of the contained image should change with each frame.

 

dy

This is the amount that the y coordinate of the contained image should change with each frame.

 

SmoothScrollMeter

This is a reference to an AnimationMeter that can be used to implement a smooth scroll between frames.

 

DupliateLastFrame

This is used for animations that wrap around. Setting it to true will ensure that the scroller displays correctly when the scroll wraps around.

Animator

The Animator overlay is used to in-between a source image and a destination image. It adds the following methods to those of SimpleOverlay2, SimpleOverlay and Overlay.

 

Alpha

This is the transparency of the image from 0 to 255 with 0 being totally transparent and 255 being totally solid. This is in addition to any per-pixel transparency that the image may have.

 

AlphaEnd

The desired end transparency.

 

XEnd

Specifies the X coordinate for the image at the end of the animation period.

 

YEnd

Specifies the Y coordinate for the image at the end of the animation period.

 

CenterXEnd

Specifies the X coordinate for the image center at the end of the animation period.

 

CenterYEnd

Specifies the Y coordinate for the image at the end of the animation period.

 

RotationEnd

Specifies the rotation for the image at the end of the period.

VScaleEnd

Specifies the end VScale at the end of the animation.

 

HScaleEnd

Specifies the end HScale at the end of the animation.

Controller

Controllers are held in a collection indexed from 0 and are accessed as SysStatsModel.Controllers(n). Where n is the index of the controller.

 

All controllers share the properties and methods defined by Controller. In OO-speak, they inherit Controller. Controllers are not a fully integrated feature in this version of SysStats so you should use them with caution.

 

Name

Will be the name displayed in the ‘Configure meters…’ dialog.

 

Type

Is the type of the controller. e.g. a shortcut controller has a type of ‘Shortcut Class’.

 

MeterIndex

The index of the referenced meter in the list of meters. A value of –1 means no meter.

 

OverlayPath

A variant array holding a set of overlay names that identify the overlay the mouse pointer has to be over for the controller to be triggered.

 

MessageType

An integer giving the windows message that this controller is triggered by. Some controllers don’t use this value (e.g. Timer and DropTarget).

 

Key

A modifier key mask that can be used in combination with a mouse message type to further refine the trigger.

 

PassThrough

If true the controller should return false from its HandleMessage() method.

 

HandleMessage(wparam, lparam, x, y)

This function takes four arguments: The wparam associated with the windows message, the lparam, the x location of the mouse and the y location of the mouse relative to the docklet’s window.

 

This is the function that causes the controller to perform its action.

 

If the function handled the message it will return true, otherwise it will return false (which just means that it wants you to continue handling the message).

ValueSetter

ValueSetter calls the PutValue method of a meter – if it has one. It adds the following properties to those of the base controller class:

 

Selector

This is passed to the PutValue method along with the value – if the meter supports selectors in its PutValue method.

Value

This is the value that the meter referred to by MeterIndex will be set to.

MessageSender

MessageSender can be used to send another message when it is triggered. This is useful for trapping some standard messages and converting them to a single message type. It adds the following properties to those of the base controller class:

 

SendMessage

This is an integer specifying the windows message that will be sent when the controller is triggered.

UseLParam

If this is true then the LParam value is used when the message is sent, otherwise the LParam value that is received by the HandleMessage method is used.

LParam

This is an integer that is passed as the LParam value of the windows message if UseLParam is set to true.

UseWParam

If this is true then the WParam value is used when the message is sent, otherwise the WParam value that is received by the HandleMessage method is used.

WParam

This is an integer that is passed as the WParam value of the windows message if UseWParam is set to true.

ScriptController

ScriptController is used to execute a script supported by the windows scripting host (e.g. vbscript) as if it were a controller. A controller of type ScriptController adds two properties to those of Controller:

 

FileName

This is the path to the file containing the script.

 

ScriptType

This defines the script language. This can be one of:

            JavaScript

            Perl

            ActivePHP

            Python

            RubyScript

            vbScript

ASyncScriptController

            The interface to this is the same as the interface to ScriptController.

Shortcut

Shortcut adds the following properties to those of the base controller class:

 

Args

This is a string specifying the command line arguments for the shortcut.

Selector

This is used with the meter specified by MeterIndex to format the value in shortcut.

Shortcut

This is the command that will be executed. It can be a format string that the meter defined by MeterIndex can use to provide the final value.

StartIn

This specifies what the working directory for the command will be set to.

DropTargetController

DropTargetController adds the following property to that of MessageSender.

Effect

This is an integer mask made up out of the following values:

0 – The controller does not accept drops

1 – The controller accepts copy drops

2 – The controller accepts move drops

4 – The controller accepts link drops

Mapped

Mapped controller doesn’t add any extra attributes or methods over and above those of MessageSender.

Cursor

Cursor controller adds the following attribute to those of the base controller class:

CursorID

An integer that should have one of the following values:

Arrow (default) =   32512

IBeam =                32513

Wait =                   32514

Cross =                 32515

Up Arrow =            32516

Size =                    32640

Icon =                    32641

Size NWSE =       32642

Size NESW =       32643

Size WE =            32644

Size NS =              32645

Size All =               32646

No =                      32648

Hand =                  32649

App Starting =       32650

Help =                    32651

Timer

Timer controller adds the following attributes and methods to those of MessageSender:

Start

This method starts the timer.

Stop

This method stops the timer

Interval

This attribute specifies the timer interval in seconds. A fractional value is accepted (e.g. 0.5 for ½ sec).

AppConfig

RootPath

AppConfig uses various algorithms to try and determine the directory in which SysStats is installed. This property represents that directory.

 

NormalizePath(path)

If the passed path is contained within RootPath, return a relative path, otherwise return an absolute path.

 

E.g. if RootPath is \Program Files\ObjectDock\Docklets\SysStats, then NormalizePath(“\Program Files\ObjectDock\Docklets\SysStats\images\clock.png”) will return images\clock.png

 

And

 

NormalizePath(“\Program Files\ObjectDock\images\clock.png”) will return \Program Files\ObjectDock\images\clock.png

 

CanonicalPath(path)

If the passed path is relative, convert it to an absolute path starting with our root directory. I.e. CanonicalPath(NormalizePath(path)) will return path.