Table of Contents

xStatsClass Version 1.x Documentation

Latest version of xStatsClass is 1.1.5

Important: The following explanations are mostly written for xLabel-4.0.5 and all newer versions of this module. Additionally xTaskbar-2.1.5, xPopup-2.0.5 and all other modules which might use xStatsClass in the future can use this too.

Make sure you load xStatsClass BEFORE all the modules that uses it.

Settings

xStatsNetStatsUpdateInterval INT
The internal update interval for the network traffic.
The default value is 1000 (ms).
You don't need to change this setting.
xStatsCpuStatsUpdateInterval INT
The internal update interval for the CPU-Usage.
The default value is 1000 (ms).
You don't need to change this setting.

TextEscapeSequences

To include dynamic text in labels, such as system information, you can use escape sequences mixed in with normal text in labels. Escape sequences consist of data source names and any necessary parameters and possibly one or more modifier functions. The entire text should be enclosed in square brackets. If you want to include [ or ] in your label's text, use [[ and ]].

LabelText      "Just some text... [modifier(dataSource(parameter))]"
ClockLabelText "The time is: [time]"
QuoteLabelText "Quote of the Day: [trim(randomLine('C:\quotes.txt'))]"
SysLabelText   "CPU: [cpu], RAM: [memInUse]"

Valid data sources and parameters

activeTask('Default Value')
Title of the currently active (and visible) task. If no active task is visible it will show "Default Value". "Default Value" is optional.
battery
Percentage of battery power remaining.
clipboardText
Current text in the clipboard.
computerName
Name assigned to this computer.
cpu('process')
Current total CPU usage in percent, if no "process" is specified.
If you specify a optional "process" (use the exe-name displayed by the taskmanager but without the .exe part), then the CPU-usage of that specific process is displayed.
cpuInfo
Shows autoformatted multiline detailed CPU chip information.
cpuInfo('vendorid')
cpuInfo('typeid')
cpuInfo('familyid')
cpuInfo('modelid')
cpuInfo('steppingcode')
cpuInfo('brandid')
Displays the specified information.
cpuSpeed
Shows static CPU speed in MHz. (Recommended!)
cpuSpeed('dynamic')
Shows current CPU speed in MHz.
Make sure that the cpuspeed('dynamic') is in a label with a suitable UpdateInterval, maybe once a min (UpdateInterval 60000) or even longer!
date('format')
Current local date. Format is optional and is explained below.
dateCreated('file', 'format')
Date and time file was created. Format is optional.
dateLastModified('file', 'format')
Date and time file was last modified. Format is optional.
diskAvailable('drive', units)
Amount of space currently available on given drive.
diskInUse('drive', units)
Amount of space currently in use on given drive.
diskTotal('drive', units)
Total amount of space on given drive.
exportedevar('evar')
Shows the content of the specified Evar (Eevar without '$').
firstLine('file', 'numberoflines')
Retrieves the first line from the given file.
You can optionally set the "number of lines", which should be retrieved.
For an interactive/automatically usage of the text extraction escape sequences use the module "AutoRecycle-1.0"

Simply set the following for each text file which need to be tracked:

*watchfile c:\litestep\track.txt !labelupdate trackinglabel
hostName
Host name assigned to this computer.
ip
Internet Protocol (IP) address assigned to this computer. Accepts numbers from "1" and upwards to choose network adapter. [ip('2')] for instance.
iTime
Current time as Swatch Internet time (beats).
kblayout
Full localized name of the current keyboard layout language.
labelname
Is set to the name of the xLabel from which this Bang/TextEscape is called (for !ParseEvars).
This only works with exactly "[labelname]"!
labeltext
Is set to the displayed text of the xLabel from which this Bang/TextEscape is called (for !ParseEvars).
This only works with exactly "[labeltext]"!
lastLine('file', 'numberoflines')
Retrieves the last line from the given file.
You can optionally set the "number of lines", which should be retrieved.
For an interactive/automatically usage of the Text Extraction Escape Sequences use the module "AutoRecycle-1.0"

Simply set the following for each text file which need to be tracked:

*watchfile c:\litestep\track.txt !labelupdate trackinglabel
line('file', 'line', 'endline')
Retrieves the number:th line from the given file, "endline" is optional to extract more than one line.

Examples:

To extract the first five lines of a file use this:

[line('c:\test.txt', '1', '5')]

For a whole file, you can do this:

[line('c:\test.txt', '1', lineCount('c:\test.txt'))]
lineCount('file')
Number of lines in the given file.
matchline('file', 'Wildcards')
Retrieves the first found line in "File", which matches the wildcards string (*, ?, …).
mbmCPUUsage
CPU usage as reported by MBM5. Takes an optional numeric index as a parameter. MBM5 supports 4 CPUs numbered 1 to 4.
mbmFanSpeed
Fan speed as reported by MBM5. Takes an optional numeric index as a parameter. MBM5 supports 10 fans numbered 1 to 10.
mbmTemperature
Temperature as reported by MBM5. Takes an optional numeric index as a parameter. MBM5 supports 10 temperature sensors numbered 1 to 10.
mbmVoltage
Voltage as reported by MBM5. Takes an optional numeric index as a parameter. MBM5 supports 10 voltages numbered 1 to 10.
memAvailable(units)
Amount of physical memory currently available.
memInUse(units)
Amount of physical memory currently in use.
memTotal(units)
Total amount of physical memory in the system.
mousepos
Current mouse position. Format: "x: 100, y: 100"
netadaptername('adapterindex')
Display the name of the selected network adapter.
Default is always "0" (nothing), if that isn't the correct one on your PC, try "1" and so on…
netin('adapterindex')
Incoming traffic in KB/sec, updated once a sec (fixed timeout, doesn't react on UpdateInterval)
You can OPTIONALLY specify the adapter for the network traffic monitor.
Default is always "0" (nothing), if that isn't the correct one on your PC, try "1" and so on …
nettotalin('adapterindex')
Total incoming traffic since the PC started.
Updated once a sec (fixed timeout, doesn't react on UpdateInterval)
You can OPTIONALLY specify the adapter for the network traffic monitor.
Default is always "0" (nothing), if that isn't the correct one on your PC, try "1" and so on …
netout('adapterindex')
Outgoing traffic in KB/sec, updated once a sec (fixed timeout, doesn't react on UpdateInterval)
You can OPTIONALLY specify the adapter for the network traffic monitor.
Default is always "0" (nothing), if that isn't the correct one on your PC, try "1" and so on …
nettotalout('adapterindex')
Total outgoing traffic since the PC started updated once a sec (fixed timeout, doesn't react on UpdateInterval)
You can OPTIONALLY specify the adapter for the network traffic monitor.
Default is always "0" (nothing), if that isn't the correct one on your PC, try "1" and so on …
netinout('adapterindex')
Combined (in & out) traffic in KB/sec, updated once a sec (fixed timeout, doesn't react on UpdateInterval)
You can OPTIONALLY specify the adapter for the network traffic monitor.
Default is always "0" (nothing), if that isn't the correct one on your PC, try "1" and so on …
nettotalinout('adapterindex')
Total combined (in & out) traffic since the PC started.
Updated once a sec (fixed timeout, doesn't react on UpdateInterval)
You can OPTIONALLY specify the adapter for the network traffic monitor.
Default is always "0" (nothing), if that isn't the correct one on your PC, try "1" and so on …
online('www.host.com', '/file.ext')
If you specify a valid "Hostname" and a "Valid Online Path" to a plain text online documents you can retrieve the content!

Example:

If you want the following: "http://www.myhost.com/myfiles/log/daily.log"

[online('www.myhost.com', '/myfiles/log/daily.log')]
ATTENTION: You need to allow Litestep.exe (that means xLabel) to access the Internet.
os
Name of the operating system running on this computer.
osex
"Extended OS information", just a little bit more detailed (longer) OS info.
powerSource('AC', 'Battery')
Selects what text to display based on whether the system is running on AC or battery power. Defaults are "AC" and "Battery".
randomLine('file')
Retrieves a randomly selected line from the given file.
skblayout
The abbreviated name of the language based entirely on the ISO standard 639 values (two letters).
size('file', units)
Size of the given file. Units is optional.
swapAvailable(units)
Amount of swap space currently available.
swapInUse(units)
Amount of swap space currently in use.
swapTotal(units)
Total amount of swap space in the system.
tasks('separator')

Shows the current running tasks.
'separator' is an optional spacer string between each task, default is ' - '.
It's like !popuptasks in the popupmenu, the active task is the first.
time('format')
Current local time. Format is optional and is explained below.
uptime('format')
Current system uptime. Format is optional and is explained below.
userName
Name of the user currently logged on.
volume('winamp')
Master speaker volume in %, if used without option.
Shows the current Winamp volume in %, if "winamp" is set as option.
windowTitle('class')
Title of the window with the given class name.

Music players

You can get information from Winamp, QCD, Foobar2000 and possibly other music players using xStatsClass. For Foobar2000 you MUST download a component DLL (homepage) named "foo_winamp_spam.dll" and copy it to your ../Foobar2000/components/ folder.

winampSong('Default Value')
Song currently loaded in Winamp (QCD or Foobar2000). If Winamp (and the other supported players) is not running or there is no song loaded this will show "Default Value". "Default Value" is optional.
winampArtist('Default Value')
Artist of the currently loaded song in Winamp (QCD or Foobar2000). If Winamp (and the other supported players) is not running or there is no Artist Tag available this will show "Default Value". "Default Value" is optional.
winampTitle('Default Value')
Title currently currently loaded song in Winamp (QCD or Foobar2000). If Winamp (and the other supported players) is not running or there is no Title Tag available this will show "Default Value". "Default Value" is optional.
winampTime('sec')
Time elapsed on the current song in Winamp (QCD or Foobar2000). If Winamp (and the other supported players) is not running or there is no time info available this will show "". "sec" is optional and shows time only in sec, not in min:sec.
winampRemainTime('sec')
Time remaining on the current song in Winamp (QCD or Foobar2000). If Winamp (and the other supported players) is not running or there is no time info available this will show "". "sec" is optional and shows time only in sec, not in min:sec.
winampTotalTime('sec')
Length of the current song in Winamp (or QCD or Foobar2000). If Winamp (and the other supported players) is not running or there is no time info available this will show "". "sec" is optional and shows time only in sec, not in min:sec.
winampBitrate
Current BitRate of playing song.
winampSamplerate
Current SampleRate of playing song.
winampStatus('Default Value')
Current status of Winamp (or Foobar2000). If Winamp (or Foobar2000) is running this will be one of "Playing", "Paused", or "Stopped". If Winamp (or Foobar2K) is not running this will show "Default Value". "Default Value" is optional.
winamprating
Current rating of playing song.
winampalbum
Album of playing song.
winampgenre
Genre of playing song.
winampalbumtrack
Albumtrack of playing song.
winampyear
Year of playing song.
winampcomment
Comment of playing song.

Valid modifier functions and parameters

The following is the list of all valid modifier functions. These functions can be used to modify the output from any of the above data sources. For instance, the computer name is usually reported in all uppercase letters, so you could use lowerCase or capitalize to change that.

Examples:

[after(winampSong,'-')]
[afterLast(winamptime, ':')]
[between(winampSong, '-', ';')]

And so on …

after(x, delim)
Extracts the part of x after the first occurrence of delim.
afterLast(x, delim)
Extracts the part of x after the last occurrence of delim.
before(x, delim)
Extracts the part of x before the first occurrence of delim.
beforeLast(x, delim)
Extracts the part of x before the last occurrence of delim.
between(x, delim1, delim2, 'Mode')
Extracts the part of x that lies between the first occurrence of delim1 and the last occurrence of delim2.
Also supports index numbers for delim1 and delim2, as well as index number and letter count.
'Mode' can be nothing, "index" or "indexspan"

Examples:

[between('This is the text, which is modified', '6', '2')]

gives back: "This is the text, which is modified" because there is no '6' or '2' in the string (Normal Mode).

[between('This is the text, which is modified', '6', '11', 'index')]

gives back: "is the"

All letters between the 6th char and the 11th char (including 6th and 11th) (six letters, 6,7,8,9,10,11) are extracted.

[between('This is the text, which is modified', '6', '2', 'indexspan')]

gives back: "is"

2 letters after 6th char (including 6th) are extracted.

capitalize(x)
Makes all characters lowercase except for the first which is uppercased.
lowerCase(x)
Makes all characters lowercase.
remove('x', 'chars to remove')
Removes a list of chars (case sensitive) from the text.
replace('x', 'string to replace', 'new string')
Replaces a string (case sensitive) with the supplied new string.
trim('x', 'chars to trim')
Removes leading and trailing whitespace characters.
Accepts an optional list of chars (case sensitive), which will be removed additionally to whitespace.
upperCase(x)
Makes all characters uppercase.
verticaldown(x)
Converts a single line x in a vertical text. Readable from top to bottom.
verticalup(x)
Converts a single line x in a vertical text. Readable from bottom to top.

Valid formats for [date], [time], and [uptime]

The [date], [time], and [uptime] data sources can optionally take a format as a parameter. The following character sequences will be interpreted in the format (anything else is included verbatim):

m
  month (1-12)
mm
  month with leading zero (01-12)
mmm
  abbreviated month name (Jan, Feb, etc)
mmmm
  full month name (January, February, etc)
d
  day (1-31)
dd
  day with leading zero (01-31)
ddd
  abbreviated weekday name (Sun, Mon, etc)
dddd
  full weekday name (Sunday, Monday, etc)
y
  day of the year
yy
  2-digit year
yyyy
  4-digit year
h
  hour (1-12)
hh
  hour with leading zero (01-12)
i
  hour (0-23)
ii
  hour with leading zero (00-23)
n
  minute (0-59)
nn
  minute with leading zero (00-59)
s
  second (0-59)
ss
  second with leading zero (00-59)
am/pm
  lowercase am/pm indicator
AM/PM
  capitalized AM/PM indicator

For [uptime] only the day, hour, minute, and second values are valid. The [date] and [time] data sources can also take a second parameter that modifies the timezone used. Here are some examples:

[time('h:nn am/pm', '+4')]

[time('h:nn am/pm', '-2:30')]
[time('h:nn am/pm', 'UTC')]
[time('h:nn am/pm', 'UTC+1')]

UTC means coordinated universal time and is loosely defined as the current date and time in Greenwich, England.

Valid units for data sources that return a size in bytes

Data sources that return a size in bytes (mem, swap, etc.) take an optional parameter that specifies the units to use. Legal values are KB, MB, GB, and % (percent). If no units are given, then the units are automatically selected based on the current value.

For example, if 24 MB of memory are free (out of 64 MB total):

[memAvailable(bytes)] ;--> 25165824
[memAvailable(KB)]    ;--> 24576

[memAvailable(MB)]    ;--> 24
[memAvailable(GB)]    ;--> 0.02
[memAvailable(%)]     ;--> 38

Note that when you use specific units, the unit labels are not added for you, but when the units are implicit they are.

MotherBoard Monitor

The MBM data sources [mbm*] require MBM version 5.1 (or higher).

Conditional TextEscapeSequences

Conditional text escape sequences let you display different information based on system conditions and/or value evaluation. For example, you can have a label displaying Winamp information if Winamp is currently playing a song, and something else if it is not.

Examples: For the system conditions:

LabelText "[if(cond1)]-- Text A --[endIf]"

LabelText "[if(cond1)]-- Text A --[else]-- Text B --[endIf]"
LabelText "[if(cond1)]-- Text A --[elseIf(cond2)]-- Text B --[else]-- Text C --[endIf]"

In the first example, if cond1 is true (a condition can only be true or false) then text A is displayed otherwise nothing is displayed.

In the second example, if cond1 is true then text A is displayed otherwise text B is displayed.

In the third example, if cond1 is true then text A is displayed, if cond1 is false and cond2 is true then text B is displayed, if cond1 and cond2 are both false then text C is displayed.

Yeah, that last one sounds pretty confusing but don't worry, it's not that likely you'll need to use it.

A condition ("cond1" for example) can contain up to three SubConditions, which MUST all be true to make the whole condition true. So you can make some kind of nested if conditions. Here are some further examples for the value evaluation

You can use the following modes (value1/2 can also be a system condition of course):

[ifeval('value1','value2')] or [elseifeval('value1','value2')]
true, if both values are identical.
[ifeval('value1','=','value2')] or [elseifeval('value1','=','value2')]
true, if both values are identical.
[ifeval('value1','<>','value2')] or [elseifeval('value1','<>','value2')]
true, if the values are different.

The following are used for number evaluation:

[ifeval('value1','<','value2')] or [elseifeval('value1','<','value2')]
true, if value1 is smaller then value2.
[ifeval('value1','?','value2')] or [elseifeval('value1','?','value2')]
true, if if value1 is smaller or equal to value2.
[ifeval('value1','>','value2')] or [elseifeval('value1','>','value2')]
true, if value1 is bigger then value 2.
[ifeval('value1','>=','value2')] or [elseifeval('value1','>=','value2')]
true, if value1 is bigger or equal to value2.

Conditions

Now you're probably wondering what these conditions are. Conditions always return:

mute
true, if MASTER volume is mute.
connected
true, if there is an active network connection.
empty(x)
true, if x is an empty string.
fileExists('file')
true, if the given file exists.
keyboardstate('key')
true, if the given keyboard LED is ON.
'key' can be:
  • Capslock
  • NumLock
  • ScrollLock
mbmLoaded
true, if MBM is loaded.
notEmpty(x)
true, if x is not an empty string.
winampPlaying
true, if Winamp is currently playing.
winampPaused
true, if Winamp is currently paused.
winampStopped
true, if Winamp is currently stopped.
winampRepeat
true if Winamp setting "Repeat" is currently active.
winampShuffle
true, if Winamp setting "Shuffle" is currently active.

So, let's do some concrete examples:

LabelText "[if(winampPlaying)]Playing: [winampSong][else][date][endIf]"
 
LabelText "[if(winampPlaying,connected)]Playing: [winampSong] with Current IP [ip][elseif(winampplaying)]Playing: [winampSong][elseif(connected)]Current IP [ip][else][date][endIf]"
 
LabelText "[ifeval('$resolutionx$','>=','1152')]You have a good resolution![else]Hmm[endif]"

 
LabelText "[ifeval(winampremaintime('sec'),'<=','15')]Song is soon over![else][winampsong][endif]"