xStatsClass Docs Version 1.x
Important:
The following explanations are related to xLabel-4.0.5 and newer, other modules which might use xStatsClass in the future, will probably only use the explained TextEscapeSequences internally and display their own visual stats representations with their own setups!
That means, that the following docs are especially for xLabel and additionally for Module Developers, which make use of xStatsClass.
xStatsNetStatsUpdateInterval INT
The internal! update interval for NetWork Traffic, default is 1000 (ms).
You really don't need to change this!
xStatsCpuStatsUpdateInterval INT
The internal! update interval for the CPU-Usage, default is 1000 (ms).
You really don't need to change this!
To include dynamic text in labels, such as system information, you can use escape sequences mixed in with normal text in labels. Escapes sequences consist of a data source names and any necessary parameters and possibly one or more modifier functions all enclosed in square brackets:
If you want to include [ or ] in your label's text, use [[ and ]].
LabelText "Just some test... [modifier(dataSource(parameter))]"
ClockLabelText "The time is: [time]"
QuoteLabelText "Quote of the Day: [trim(randomLine('C:\quotes.txt'))]"
SysLabelText "CPU: [cpu], RAM: [memInUse]"
As of version 1.5, labels can have text which spans multiple lines. To create a line break in the text use the character sequence "<br>".
MultiLineLabelText "This is on line 1<br>This is on line 2" MemLabelText "Memory Info<br><br>Free: [memAvailable]<br>Total: [memTotal]"
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 Taskmanager displayed exe-name without exe), then the CPU-Usage of that specific Process is displayed.
cpuInfo('info')
Shows autoformatted multiline detailed CPU Chip Informations.
But you can also get single informations (optional argument):
[cpuInfo('vendorid')]
[cpuInfo('typeid')]
[cpuInfo('familyid')]
[cpuInfo('modelid')]
[cpuInfo('steppingcode')]
[cpuInfo('brandid')]
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 adapted 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 (Evar 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 for each Text-File which need to be tracked the following:
*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", ... 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 displyed 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 for each Text-File which need to be tracked the following:
*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 then one line.
Example:
To extract the first 5 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 MousePosition. Format: "x: 100, y: 100"
netadaptername('adapterindex')
Display the name of the selected NetWorkAdapter.
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 PC Start 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 PC Start 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 PC Start 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 follwing: "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 (2 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 runnning tasks in the label. "separator" is an optional spacer string between each task (best is '
'), default is ' - '.
It's like !popuptasks in popupmenu, Active Tasks 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 WinampVolume in %, if "winamp" is set as option.
Foobar2K:
You MUST download a component DLL (-> Homepage) named "foowinampspam.dll" and copy it to your ../Foobar2000/components/ folder. Done! All [winamp...] Escape Sequences work now also for Foobar v0.7+!
winampSong('Default Value')
Song currently loaded in Winamp (QCD or Foobar2K). 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 Foobar2K). 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 Foobar2K). 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 Foobar2K). 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 Foobar2K). 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 (QCD or Foobar2K). 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 Foobar2K). 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.
windowTitle('class')
Title of the window with the given class name.
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 occurance of delim.
afterLast(x, delim)
Extracts the part of x after the last occurance of delim.
before(x, delim)
Extracts the part of x before the first occurance of delim.
beforeLast(x, delim)
Extracts the part of x before the last occurance of delim.
between(x, delim1, delim2, 'Mode')
Extracts the part of x that lies between the first occurance of delim1 and the last occurance of delim2.
Supports also IndexNumbers for delim1 and delim2, as well as IndexNumber and LetterCount.
'Mode' can be nothing (as before), or "index" or "indexspan"
Examples:
[between('This is the text, which is modified', '6', '2')]
gives back: "This is the text, which is modified"
Cause there is no '6' and '2' in the string (Normal Mode).
[between('This is the text, which is modified', '6', '11', 'index')]
gives back: "is the"
All letters between 6th char and 11th char (including 6th and 11th) (6 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!), which will be removed out of the text.
trim('x', 'chars to trim')
Removes leading and trailing Whitespace, accepts a 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.
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.
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.
As of version 1.9 of Label the MBM data sources [mbm*] require MBM version 5.1 (or higher). Due to the nature of the changes this makes Label 1.9 incompatible with earlier versions of MBM.
Conditional text escapes let you display different information based on System Conditions and/or Value Evaluation. For example, you can have a label that displays Winamp information if Winamp is currently playing a song, or something else if it is not.
Here are some 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.
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 both values are NOT identical.
Next Ones 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.
Now you're probably wondering what these conditions are, well here they are.
Conditions always return:
"1" -> TRUE or
"0" -> FALSE
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 "key"board 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.
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]"