Meters

Meters in SysStats are used to hold data that can be displayed. Most meters hold values that change and the overlays used to display those meters will update their display when that happens.

 

A meter might change its value on its own, or it might have its value explicitly changed by a controller or a scriptlet. The effect on the display will be the same.

 

Some meters need to have an interval defined in order for them to notify SysStats of any changes. The interval is in seconds and the meters will be polled every interval seconds to see if their value has changed. You can use a fraction if you want to specify an interval of less than one second. A value of 0 means the meter will never be polled  - some meters will notify SysStats of any change themselves.

 

SysStats defines the following meters as standard (see also the script document for details of all the individual attributes):

 

 

A meter may hold more than one value – this is especially true of the XML meter. Such meters define a selector which can be used to specify which specific value you want. The selector might be defined by a fixed set of values (as is the case with the Animation meter) or it might be an arbitrary string (as is the case with XML meter – which allows you to use any XPath expression as the selector).

 

All meters can provide their value as:

 

Different types of overlay will request the value of a meter in one of these formats. For example a text overlay will always ask for a string. A gauge overlay will always ask for an integer.

Fixed

The fixed meter holds a ‘fixed’ value. It never changes on its own, though a controller or scriptlet might change it.

 

For overlays that require a string, use the string format specifiers

Memory

The memory meter provides access to RAM usage information. You should set the interval to something other than 0 to make the meter update.

 

For overlays that require a string, use the real number format specifiers

Disk

The disk meter provides access to disk and folder usage information. You should set the interval to something other than 0 to make the meter update.

 

For overlays that require a string, use the real number format specifiers

PDH

The PDH meter provides access to Microsoft’s Performance Data Handler. This allows you to monitor a vast array of data about your computer including CPU activity, disk activity and network Activity.

 

For overlays that require a string, use the real number format specifiers

Time

The time meter provides access to the time of day. The user can configure a timezone for the meter.

 

For overlays that require the time as a number it provides the value as the number of seconds since midnight.

 

For overlays that require the time as text, use the time format specifiers.

 

Overlays that expect a String value can use the following selectors:

 

0 – Returns the time using the format string.

1 – Returns the timezone description

2 – Not implemented

3 – Returns the offset from GMT

 

Overlays that expect a number can use the following selectors:

 

0 – Returns the number of seconds since midnight in the meter’s timezone.

2 – Not implemented – always returns 0.

3 – Returns the offset from GMT

MBM

The MBM meter provides access to values reported by MotherBoard Monitor. These include component temperatures and fan speeds.

 

For overlays that require the number as text, use the real number format specifiers.

Battery

The battery meter provides access to information about a laptop’s battery including time-remaining, charging status, charge level etc.

 

Overlays that expect a numeric value (e.g. Meter and Gauge) can set the selector as follows to obtain different information from the battery meter:

 

0 - ACLine Status. Values returned are as follows:

            0          Offline

            1          Online

            -1         Unknown status

 

1 – BatteryFlag. Values returned are as follows:

            1          High

            2          Low

            4          Critical

            8          Charging

            128      No system battery

            -1         Unknown status

 

2 – BatteryLifePercent

 

3 – BatteryLifeTenths

 

4 – BatteryLifeTime

 

5 – BatteryFullLifeSeconds

 

Overlays that require battery information as text should use the battery format specifiers.

Mail

The mail meter provides access to information about email accounts. At the moment it only uses MAPI – which limits it to accessing Outlook and Outlook express.

 

The mail meter uses one of two possible selector values:

0 – Return the number of unread emails

1 – Return 0 if there are no unread emails or 1 if there are unread emails.

 

Overlays that require the value as text should use the integer number format specifiers.

Animation

The animation meter is used to drive an animation! By holding this information as a meter it allows designers to drive several overlays from the same animation – thus they could run several animations in sync, provide control buttons for an animation etc.

 

The meter can be configured with the following information:

Frame count

The total number of frames in the animation

Frame rate

The number of frames per second (you can use fractions for really slow animations)

Auto start

If set, the animation will start as soon as the docklet is loaded

Loop

If set the animation will play continuously, otherwise it stops when it reaches the end

Auto reverse

If set the animation plays forwards then backwards. If loop is not set the animation will pause at the beginning and the end

Step

If set the animation will only play one frame and then pause

Post Message on State Transition

This defines a windows message (typically User Message or any value greater than 1024) that is posted when the meter changes state. For example is starts, stops or pauses or reaches the end or start of an animation. The actual state the meter entered is provided in the WPARAM argument to the windows message (see below)

State Transition LPARAM

This allows you to associate a value with the LPARAM argument to the windows message.

 

In addition to these values, overlays and controllers can get and set the following properties:

Current frame

The current frame number

Frame delta

The meter adds this number to the current frame number whenever it moves to the next frame. Typically it is +1 or -1 but can be any number

Position

This is a mask:

1 = At beginning

2 = At end

All of the values 0, 1, 2 & 3 are valid depending on the number of frames in the animation!

Play state

A number representing the state of the animation:

0 = stopped

1 = playing

2 = paused

If the animation is stopped then it will be at the beginning. If it is paused it could be anywhere.

Step

When written to the meter causes it to step to the next frame.

 

State transition messages are provided in the WPARAM argument of a windows message. The lowest four bits contain the new playstate, the next four bits contain the position. This gives the following possible values:

 

0

Stopped in the middle of an animation

1

Started in the middle of an animation

2

Paused in the middle of an animation

16

Stopped at the start of an animation

17

Started at the start of an animation

18

Paused at the start of an animation

32

Stopped at the end of an animation

33

Started at the end of an animation

34

Paused at the end of an animation

 

Overlays that want the value as text should use the real number format specifier.

Example Use

The example animated weather docklet uses several animation meters and controllers. One set of animation meters controls the scrolling of the weather symbols. Another one controls the fade-in and fade-out of the scroll arrows on mouse-over/leave. The scroll-arrow fader is complicated by the fact that mouse-over is really done using mouse-move messages: you can get many of these while the mouse is over the docklet, but you only want the first one to have any effect, This is why there is a controller that sets the frame delta to +1 which has the effect of locking the animation at the final frame once it gets there.

XML

The XML meter allows you to use any source of XML to hold values that can be displayed. Typical sources include web services and RSS feeds.

 

If you use this meter you should download and install MSXML4 from Microsoft. This is not essential but it will give you an improved set of facilities including:

 

The XML meter accepts arbitrary XPath expressions as a selector – this allows an overlay to display just a single part of the whole XML document. This XPath support comes in two flavors. The default flavor ignores any namespaces in the XML document but can only return data that is in the document! The second flavor can use an XPath expression (so it can concatenate strings, return substrings, count elements of a particular type etc. etc.) but it requires you to list each namespace that occurs in the document, so only select this if you need full XPath selectors (the included GMail docklet is an example that uses full XPath with namespaces).

 

Overlays that require a text value should use the string format specifiers.

Script

The script meter allows you to write your own meter in any language supported by the Microsoft Script Host engine. Typically this will be VBScript.

 

SysStats makes the entire SysStats object model available to the script through the SysStatsModel global object, including all overlays, meters, controllers, label and all of their properties and methods.

 

You can change any object’s properties, add new objects, delete objects and move them around.

 

SysStats also provides an implementation of Microsofts WScript global object. Currently this only implements the following WScript functions:

 

SysStats automatically wires up three script functions:

 

·         ScriptMeter_Update()

·         ScriptMeter_GetValue(selector)

·         ScriptMeter_PutValue(value)

 

Any given script can use either, 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 from a ValueSetter controller.

 

Note that these calls are synchronous. This means that SysStats will wait until they have finished executing. If the functions take a long time to execute SysStats will appear to freeze.

 

Please see the separate script documentation for more details.

ASyncScript

This is an asynchronous version of the script meter. SysStats doesn’t wait for any of the functions to finish executing before it continues. Thus it is useful for scripts that take a long time to execute.

 

The only problem with this is that you won’t necessarily get an up-to-date value if you try and display the value of the meter.