Latest version of xLabel is 4.3
This is xLabel-4.3, a LiteStep module that lets you create "all" basic interface stuff, and also skinnable text labels, which can be placed anywhere on your desktop. The text labels can display both static text as well as dynamically updating system information provided by xStatsClass.
You need to load xPaintClass-1.0 before xLabel, otherwise xLabel won't load! xLabel also uses the features of xStatsClass. If you want to use those features you need to load xStatsClass before xLabel.
You can also simply put xPaintClass-1.0 in your LiteStep folder.
You can download the latest xPaintClass-1.0.dll at: www.ls-universe.info
Add some new LoadModule lines somewhere in your theme configuration, similar to the following (this assumes that xLabel-4.3.dll resides in C:\LiteStep\Modules\):
LoadModule "C:\LiteStep\Modules\xPaintClass-1.0.dll"
LoadModule "C:\LiteStep\Modules\xStatsClass-1.1.dll"
LoadModule "C:\LiteStep\Modules\xLabel-4.3.dll"
or the newer *NetLoadModule lines:
*NetLoadModule xPaintClass-1.0
*NetLoadModule xStatsClass-1.1
*NetLoadModule xLabel-4.3
To make the newest version available for your theme, you should probably add the following lines somewhere in your theme configuration:
*NetLoadModuleSite "http://www.modules.shellfront.org/"
*NetLoadModuleSite "http://www.modules.ls-universe.info/modules/"
*NetLoadModuleSite "http://www.modules.nbi-studio.com/"
*NetloadModuleSite "http://www.ls-themes.org/modules/download/"
The following sections describe how to configure xLabel to actually do something useful. Once you're done configuring, recycle LiteStep.
- [ ]
- Values between [ and ] are optional
- ACTION
- Bang commands, applications, everything LiteStep can execute. Can also be a URL which will be opened in the user's default browser.
- BOOL
- Boolean value (
true
or false
)
- COLOR
- Color in Hex (FFFFFF = White, 000000 = Black, …)
- COORDINATE
- X or Y coordinate on the screen
- If the value is positive, then it is relative to the top/left of the parent (desktop or parent module).
- If the value is negative, then it is relative to the bottom/right of the parent (desktop or parent module).
- You can make the position relative to the center of the parent (desktop or parent module) by appending the character 'c' after the number ("32c", "-128c")
- You can use "real negative values" by adding a '~' before the number ("~10").
- Additionally you can use percent values of the desktop or the parent module ("50%", "75%") and you can combine those percent values with further positioning ("20%-20", "80%+5", "100%+20").
- You can position the label on multi monitor systems with:
- 1@
- Relative to primary monitor
- 2@
- Relative to secondary monitor
- 3@
- Relative to third monitor (untested)
- v@
- Relative to virtual screen (all monitors combined)
- DIMENSION
- A number of pixels
- If the value is positive, then it is an absolute size in pixels
- If the value is negative, then it is the parent (desktop or parent module) width/height minus the specified value.
- Additionally you can make the size relative to a percentage of the parent (desktop or parent module) width/height by appending the character '%' after the number ("50%", "-20", "50%-20", "75%+40").
- You can size the label relative to monitors on multi monitor systems using the same syntax as for COORDINATE (1@, 2@, etc)
- INT
- A number
- STRING
- A word, usually beginning with a period (.) or a quoted text
xLabel lets you create any number of labels. Each label has its own unique name which is used to refer to that label in configuration settings and Bang commands. There are two ways to create labels: automatically and manually. A label that is created automatically is created when xLabel is loaded.
You declare that a label is should be automatically created by placing a *Label
command somewhere in your theme configuration:
*Label MyLabel
*Label OtherLabel NextLabel LastLabel
As shown above, you can create multiple labels with one *Label
line. The names you put after *Label
are referred to as "(label-name)" in this documentation (without the quotes).
If you want to create the label manually instead use the !LabelCreate
Bang command. In this case the label is created if and when the Bang command is executed.
!LabelCreate MyLabel
!LabelCreate OtherLabel NextLabel LastLabel
As you can see, it's possible to create multiple labels with one !LabelCreate
line.
All labels are automatically destroyed when xLabel is unloaded, regardless of how they were created.
To help reduce redundant configuration commands xLabel supports default settings. By prepending "Global" (without the quotes) to the name of the setting you can make defaults that apply to all labels. By prepending a prefix "<labelgroup>" (without the quotes and angle brackets) to the name of the setting you can make defaults that apply to all labels, which belong to the given labelgroup.
- AddToGroup STRING [STRING] [STRING] […]
- This command is used to add a label to one or more label groups.
Example:
The following sets the font LabelOne and LabelTwo will use, but which is overridden by LabelThree. Next, the label group GroupOne defines a default y-coordinate for all labels in that group, which is basically valid for LabelOne and LabelThree, but is overridden by LabelThree (LabelThreeY 150
).
GlobalFont "Tahoma"
GlobalFontHeight 12
GlobalFontBold
GlobalFontColor ffffff
GlobalFontAlign .left
GroupOneY 100
LabelOneAddToGroup GroupOne
LabelOneText "Hello!"
LabelOneX 100
LabelOneFontAlign .center
LabelTwoText "Hi!"
LabelTwoX 200
LabelTwoY 200
LabelThreeAddToGroup GroupOne
LabelThreeText "Greetings!"
LabelThreeX 300
LabelThreeY 150
LabelThreeFont "Arial"
LabelThreeFontHeight 11
LabelThreeFontColor ffffff
The following commands are typically placed somewhere in your theme configuration. See the LiteStep documentation for help modifying these files.
All commands must be prefixed with the label's name.
Example:
To set the text of a label named "MyLabel" the actual command you would put in the step.rc would be
MyLabelText "This is my displayed text"
but the command shown in this documentation would be
- Text STRING
- Sets the text displayed by the label.
- X COORDINATE
- Sets the horizontal position of the label.
Examples:
TestLabelX 5 ; 5 pixels to the right of the LEFT side of the parent
TestLabelX ~5 ; 5 pixels to the left of the LEFT side of the parent
; (Just as info, this is outside the parent)
TestLabelX -5 ; 5 pixels to the left of the RIGHT side of the parent
TestLabelX 1@-5 ; 5 pixels to the left of the RIGHT side of the primary monitor
- Y COORDINATE
- Sets the vertical position of the label.
Examples:
TestLabelY 5 ; 5 pixels below the TOP side of the parent
TestLabelY ~5 ; 5 pixels above the TOP side of the parent
; (Just as info, this is outside the parent)
TestLabelY -5 ; 5 pixels above the BOTTOM side of the parent
TestLabelY 1@-5 ; 5 pixels above the BOTTOM side of the primary monitor
- Width DIMENSION
- Sets the horizontal size of the label.
- Height DIMENSION
- Sets the vertical size of the label.
- ResizeBorder INT INT INT INT
- ResizeBorder INT INT
- ResizeBorder INT
- The parameters are:
left
right
top
bottom
or left/right
top/bottom
or left/right/top/bottom
- Accepts 4, 2 or 1 INT value(s), which defines the borders.
- A virtual border with the specified size is put at the matching side of the label. This border enables you to resize the label on-the-fly like normal windows.
- ResizeBorderSteps INT [INT]
- If you resize a label manually (
ResizeBorder
has to be set), you can now specify steps for each direction. Only after the resize has reached this pixel count, a "Resize Step" is performed.
- First INT value is the horizontal step size, the second INT the vertical.
- If only one INT is supplied that value defines the step size in both directions.
- AutoWidthMode STRING
- The parameter is:
staticedge
-
staticedge
can be .left
, .right
, or .center
.
- Sets the horizontal auto adjusting method of the label.
-
.left
keeps the x-coordinate given in the (label-name)X configuration setting. (The label will only grow to the right.)
-
.right
adjusts the the x-coordinate to keep the right coordinate fixed. (The label will only grow to the left.)
-
.center
adjusts the the x-coordinate to hold label centered to initial center position [(label-name)X + (label-name)Width/2]. (The label will grow equal amount to the left and the right.)
- AutoHeightMode STRING
- The parameter is:
staticedge
-
staticedge
can be .top
, .bottom
, or .center
.
- Sets the vertical auto adjusting method of the label.
-
.top
keeps the y-coordinate given in the (label-name)Y configuration setting. (The label will only grow down, towards the bottom of the screen.)
-
.bottom
adjusts the the y-coordinate to keep the bottom coordinate (according to initial (label-name)Y and (label-name)Height configuration settings). (The label will only grow upwards.)
-
.center
adjusts the the y-coordinate to hold label centered to its initial center position [(label-name)Y + (label-name)Height/2]. (The label will grow equal amounts up and down.)
- AutoAnimation INT INT
- The parameters are:
step
delay
- If both values are set, the
AutoWidthMode
/AutoHeightMode
use animations to resize/reposition.
-
step
defines how many animation steps there should be.
-
delay
specifies the time in milliseconds the animation will pause at each step.
- AutoMaxWidth INT
- Sets the max horizontal size of the label when auto resizing or manually resizing it.
- Can only be a pure INT value. Something like 50% will not work.
- AutoMaxHeight INT
- Sets the max vertical size of the label when auto resizing or manually resizing it.
- Can only be a pure INT value. Something like 50% will not work.
- AutoMinWidth INT
- Sets the minimal horizontal size of the label when auto resizing or manually resizing it.
- Can only be a pure INT value. Something like 50% will not work.
- The default
AutoMinWidth
value is (label-name)Width.
- AutoMinHeight INT
- Sets the minimal vertical size of the label when auto resizing or manually resizing it.
- Can only be a pure INT value. Something like 50% will not work.
- The default
AutoMinHeight
value is (label-name)Height.
- AlwaysOnTop BOOL
- If this command is present it makes the label "AlwaysOnTop". The label stays above all application windows.
- WindowzOrder BOOL
- Normal window zorder behaviour, that means the label floats on top when activated like a normal window.
- BehindWindow STRING [STRING]
- The parameters are
classname
windowtext
- If
classname
(and windowtext
) is set, the label is placed behind this window and will "never" come to front.
- If the special "HWND_TOP" is used for
classname
, the label tries to stay on top of other windows. Only one module should use the "HWND_TOP" classname.
- By default the label never changes its z-order after the first creation (as long as
AlwaysOnTop
isn't set).
- Moveable BOOL
- Moveable [STRING]
- STRING can be
.horizontal
or .vertical
- If this command is present the label will be draggable with "ModifierKey(s)+MoveMouseButton" (Enter the label with mouse, press the "ModifierKey(s)" and hold it, then press and hold the MoveMouseButton and drag the label around. To stop moving either release "ModifierKey(s)" or MoveMouseButton.)
- If the optional STRING is set, the dragging is only allowed in the specified direction.
- MoveButton STRING
- STRING can be
.left
, .right
, or .middle
- This command specifies the what mouse button to use to move a label around.
- If no value is provided, then the default is
.left
.
- MoveModifierKey STRING
- STRING can be
.none
, .ctrl
, .shift
, or .ctrl+shift
(.shift+ctrl
)
- This command specifies the key(s) required to be held down to be able to drag the label around.
- If no value is provided, then the default is
.ctrl
.
- MoveArea COORDINATE COORDINATE DIMENSION DIMENSION
- The parameters are:
x
y
width
height
- On manual moving/dragging you cannot move the label out of this area.
- Make sure that the label starts in this area, otherwise it "jumps" in to this area when you first start moving it.
- NoMoveCursor BOOL
- If this command is present it disables the change to the move cursor during the movement.
- FireOnMoveDuringMove BOOL
- If this command is present the
OnMove
event is fired during a drag all the time. If it isn't set, the even is only fired once, when the move has ended.
- *(label-name)DockedTo STRING [STRING]
- The first STRING is the name of the label to dock to.
- If you move the "Parent Label" (first STRING parameter) the "DockedTo" label (label-name) moves accordingly. This works with manual dragging, Bang commandss and even with animations. (Simultaneous animations are possible without scripting.)
- Optional STRING can be:
- "left", "top", "right", "bottom", "topleft", "topright", "bottomleft", or "bottomright"
- This affects how a docked label reacts on moving/resizing of the DockedTo label.
- Multiple lines are possible (therefore the prepending '*').
Examples:
*LabelOneDockedTo ParentLabel ; Both these labels will be docked to ParentLabel
*LabelTwoDockedTo ParentLabel ; and will therefore move when ParentLabel moves
- DockOnSnap STRING
- STRING can be
.nothing
, .moving
, .snappedTo
, or .moving+snappedTo
.
- .moving
- If a movable label is moved to one of it's "SnapTo" labels and "snaps", then the moved label is automatically docked to the SnapTo label.
- .snappedTo
- If a movable label is moved to one of it's "SnapTo" labels and "snaps", then the SnapTo label is automatically docked to the moved label.
- .moving+snappedTo
- On snap both labels are stuck together and you can only undock them via the Bang command
!LabelDock
. If you move one the other moves as well, so you cannot undock them this way anymore.
- For undocking simply move the docked label away. (Only possible in mode
.moving
or .snappedTo
.)
- SnapTo STRING [INT]
- STRING can be:
- Desktop
- Desktop borders only (jDeskArea, …) DEFAULT, if omitted.
- Specific label name
- The label snaps to the specified label.
- Specific label group
- The label snaps to any label in the specified group.
- AllLabels
- The label snaps to all other labels, and the desktop borders.
- Moveable labels snap to STRING if moved closer than INT pixels to any border of STRING.
- Note: To leave a SnapArea, just quickly move the label away.
- Tooltip STRING
- Sets the tooltip text displayed by the label.
- If no value is provided no tooltip is shown.
- The value can contain both simple text and escape sequences. Escape sequences are enclosed in square brackets ("Simple text [escape]"). See xStatsClass for more information.
- You can use "<br>" to force a line break in the tooltip text. You can use "<tab>" to insert a tab in the tooltip text.
Additionally all xPaintTooltip settings are valid for the label tooltip.
The needed xPaintTooltip prefix is "(label-name)".
- AddToGroup STRING [STRING] [STRING] […]
- The parameters are:
(group-name1)
(group-name2)
(group-name3)
…
- This command is used to add a label to one or more label groups.
- Only the first group has full support for adding itself to another group. So
(group-name2)AddToGroup SomeGroup
will not work as expected.
- You can use Defaults settings for a whole group.
- When xLabel looks for a configuration setting for a label it first looks at the label itself, then it looks at any groups the label is part of, and last it looks for global settings.
- You can apply Bang commands to the whole group.
Supported Bangs:
!LabelAlwaysOnTop labelgroup [true|on, false|off or toggle|switch]
!LabelDestroy labelgroup
!LabelHide labelgroup
!LabelMoveBy labelgroup (x) (y)
!LabelRefresh labelgroup
!LabelScroll labelgroup [INT] "true|on", "false|off", "toggle|switch" or "freeze") (ScrollMode 1-4)
!LabelSetAlpha labelgroup INT
!LabelShow labelgroup
!LabelShowHide labelgroup INT
!LabelRepositionBy labelgroup (x) (y) (cx) (cy)
!LabelResizeBy labelgroup (cx) (cy)
!LabelToggle labelgroup
!LabelUpdate labelgroup
- StartHidden BOOL
- If this command is present then the label will be initially invisible. It can later be shown using Bang commands.
- FocusOnEnter BOOL
- If this command is present the label "steals" the focus from the active window when you move your mouse over it. This provides instant MouseWheel functions, the one and only purpose of this setting.
- Cursor STRING
- Sets the cursor used when the mouse hovers over the label. STRING can be any valid full path to a cursor, or a cursor located in the $LSImageFolder$ like normal images.
- FireOnResizeDuringResize BOOL
- If this command is present "OnResize" is fired during an animated resizing, if not, only one time after the resize has finished.
- Note: If (label-name)ResizeBorder is used, this is automatically set to TRUE.
- HoverTimeOut INT
- Set the amount of time, in milliseconds, the mouse must stay still before the "OnHover" command is executed.
- Default is 400ms.
- TrueTransparency BOOL
- If set, you get "true transparency" otherwise you get a copy of the desktop background in the transparent (magic pink, FF00FF) regions. This is only needed on Windows 9x and Windows ME systems. On Windows 2000 and newer
AlphaMap
does the same thing, but with additional support for alpha transparent images.
- TrackingIgnoreTrueTransparency BOOL
- If set to
true
the full label rectangle is always used for mouse events as if there is no transparency at all. Nevertheless the transparency is still painted normally. This does not work for alpha map images.
- OS requirement: Windows 2000 or newer.
- AlphaTransparency INT
- The command makes the label alpha transparent (eg. you will see the background or a window you drag below the label shine through). It adds an overall transparency on everything in the label no matter what kind of background the label has (transparent, alpha transparent, or solid).
- Valid values are 0-255, where 0 is totally transparent and 255 is opaque.
- Default is 255.
- OS requirement: Windows 2000 or newer.
- AlphaMap BOOL
- If this command is present the label uses per-pixel alpha transparency for images with alpha transparency information (PNG images).
- This is the only transparency related setting you need for images with any kind of transparency on Windows 2000 and newer OSes.
- Caution:
AlphaMap
doesn't work with a hooked label.
- OS requirement: Windows 2000 or newer.
- AlphaFade BOOL
- If this command is present then the label will fade in/out on show/hide.
- CustomAlphaFade INT INT
- The parameters are
step
delay
.
- If this command is present then the label will fade in/out on show/hide in
step
steps, pausing delay
ms at each step.
- OS requirement: Windows 2000 or newer.
- Ghosted BOOL
- If this command is present the label will be ghosted.
- A ghosted label doesn't react to the mouse (clicks etc. will be passed through to the application under the label). Due to this,
Ghosted
is mainly a feature for alpha transparent labels.
- OS requirement: Windows 2000 or newer.
- DropShadow BOOL
- If this command is present the label will have the "drop shadow" invented with Windows XP.
- OS requirement: Windows XP or newer.
- Text STRING
- Sets the text displayed by the label.
- If no value is provided the label is left blank.
- The value can contain both simple text and escape sequences. Escape sequences are enclosed in square brackets ("Simple text [escape]"). See xStatsClass for more information.
- You can assign multiple text items by separating them with semicolons ("Item 1;Item 2") then switch between them with
!LabelPrevious
and !LabelNext
.
- HoverText STRING
- Sets the text displayed by the label, if the mouse hovers over the label.
- If no value is provided the normal label text is used.
- The value can contain both simple text and escape sequences. Escape sequences are enclosed in square brackets ("Simple text [escape]"). See xStatsClass for more information.
Each setting is available for the Normal, Hover and Pressed state.
If a setting isn't provided for the Hover state the setting for the Normal state is used.
If a setting isn't provided for the Pressed state the setting for the Hover state is used.
All xPaintHTMLText settings are valid for the label text.
The needed xPaintHTMLText prefix is (label-name)+(State).
State can be one of the following
- "" (Nothing/Blank)
- Default value for all states
- Hover
- Hover state, i.e. when you have your mouse over the label
- Pressed
- Pressed state, i.e. when the user is clicking on the label
Examples:
*Label TestLabel ; Create a label with (label-name) TestLabel
TestLabelFontColor FF0000 ; Make the text red
TestLabelHoverFontColor 00FF00 ; When moving the mouse over the label the text will be green
- HREFHoverConfig STRING
- STRING is
precfg
;postcfg
- Sets the text (style), if mouse hovers over <a href='action'> tags. You can define additional text or tags which will be applied.
-
precfg
will be inserted before the text in the label.
-
postcfg
will be appended to the text in the label.
-
precfg
and postcfg
are seperated with a semicolon (;).
- Make sure to close all tags in
postcfg
that you opened in precfg
.
- Default: Nothing except cursor change to indicate a clickable link.
Example:
(label-name)HREFHoverConfig "<b><u>;</u></b>" ; Makes the link bold (<b>) and
; underlined (<u>) when hovering it.
- NoEscapeSequence BOOL
- If this command is present the text escape sequences aren't processed anymore. (For example, [cpu] isn't parsed to display the current cpu load.)
- Useful if labels are used with rss readers for instance.
- NoTextSplit BOOL
- If this command is present the text isn't split at ';' anymore.
- Useful for instance, if labels are used with an rss reader. Text split at ; is used with the
!LabelNext
and !LabelPrevious
Bang commands.
- UpdateAlways BOOL
- If this command is present it forces the label to update every
UpdateInterval
even if it doesn't contain any dynamic text like "[cpu]".
- UpdateInterval INT
- Sets the amount of time in milliseconds between updates for labels that contain dynamically updated contents.
- If no value is provided, then the default is 1000 (1 second).
- Scroll BOOL or STRING
- If this command is present then the label scrolls its contents if the text doesn't fit into the label.
- The label must have a background (image or "fake" transparency) for correct scrolling!
- STRING can be "" (nothing),
horizontal
/horizontal
, horizontal-right
, vertical
/vertical-down
or vertical-up
. "" (nothing) is the default, same as horizontal
.
- ScrollInterval INT
- Sets the scrolling update interval in milliseconds.
- If no value is provided, then the default is 100.
- ScrollSpeed INT
- Sets the number of pixels to scroll for each update. Negative values allow you to scroll in the opposite direction.
- If no value is provided, then the default is 1.
- ScrollPad INT
- Sets the the number of pixels between the start and end of the text when scrolling, can be negative.
- If no value is provided, then the default is 10.
- ScrollPerLine INT INT INT
- The parameters are:
initial
standard
pause
- The vertical scrolling can stop for a custom time and scroll a defined height, before it stops again. This allows you to get a line per line scroll, which stops at each new line for the defined duration.
-
initial
is used to set the amount of pixels to scroll the very first time. This is used to align the text for the rest of the scrolling.
-
standard
is the standard scrollheight, in pixels. (A good first guess could be FontHeight + FontNewlineSpace)
-
pause
sets the time to pause in milliseconds on each line.
- The three parameters to
ScrollPerLine
needs to be tweaked by trial and error.
Example:
*Label TestLabel
TestLabelScrollPerLine 0 18 2000
TestLabelScrollPad 2 ; Don't forget to set this one
TestLabelX 100
TestLabelY 100
TestLabelWidth 100
TestLabelHeight 20
TestLabelText "Line1<br>Line2<br>Line3"
TestLabelScroll .vertical
TestLabelAlwaysOnTop
Each setting is available for the Normal, Hover and Pressed state.
If a setting isn't provided for the Hover state the setting for the Normal state is used.
If a setting isn't provided for the Pressed state the setting for the Hover state is used.
All xPaintTexture settings are valid for the label background!
The needed xPaintTexture "Prefix" is (label-name)+(State)!
State can be one of the following
- "" (Nothing/Blank)
- Default value for all states
- Hover
- Hover state, i.e. when you have your mouse over the label
- Pressed
- Pressed state, i.e. when the user is clicking on the label
You want animations for normal state or only on hover state, then these settings are valid. If you use animations you cannot use the AutoSize feature, but you can resize the animation like normal images (but it is not really recommended).
Another important point is the fact that you cannot use TrueTransparency in animations, except for the case where all frames have the same transparent (magic pink, FF00FF) areas.
If you stop the animation (automatically or manually) it will show the standard images (xPaintTexture settings needs to be specified).
All xPaintTexture settings are valid for the animated label background.
The needed xPaintTexture prefix is (label-name)+"Anim"
Additionally you must set:
(label-name)AnimPaintingMode .animation
- AnimFrameLoops INT
- Sets the number of loops the animation should perform, before it automatically stops.
- For infinte loops set to -1 (or any other negative number).
- AnimFrames STRING
- Sets the name of the file containing all the frames in one image. All frames need to have the same width and the same height, and they should be on a row from left to right.
- This file must be in bmp or png format.
- If you want each frame to be in a seperate image this can be configured with the
*(Label-Name)AnimFrames
setting.
- AnimFrameWidth INT
- Sets the width of a single frame.
- Note: Required setting.
- AnimFrameHeight INT
- Sets the height of a single frame.
- Note: Required setting.
- AnimFrameCount INT
- Sets the number of frames in the animation.
-
AnimFrameCount
* AnimFrameWidth
must be indentical to the image width of the AnimFrames image. So, an animation with 5 frames, each with a size of 32x32, needs an image that has the size 160x32.
- Note: Required setting.
- AnimFrameDelay INT
- Sets the delay between each shown frame.
- *(Label-Name)AnimFrames STRING
- Alternative to
AnimFrames
described above.
- Sets the name of one file containing one frame.
- This file must be in BMP or PNG format format.
- You need one line for every frame in the correct order.
- Make sure you have the same amount of "AnimFrameLines" as you have frames specified in
AnimFrameCount
. And make sure that all have the correct size as specified in AnimFrameWidth
and AnimFrameHeight
.
All xPaintTexture settings are valid for the animated label background.
The needed xPaintTexture prefix is (label-name)+"HoverAnim"
Additionally you must set:
(label-name)HoverAnimPaintingMode .animation
- HoverAnimFrameLoops INT
- Sets the number of loops the animation should perform, before it automatically stops.
- For infinte loops set to -1 (or any other negative number).
- HoverAnimFrames STRING
- Sets the name of the file containing all the frames in one image. All frames need to have the same width and the same height, and they should be on a row from left to right.
- This file must be in bmp or png format.
- If you want each frame to be in a seperate image this can be configured with the
*(Label-Name)HoverAnimFrames
setting.
- HoverAnimFrameWidth INT
- Sets the width of a single frame.
- Note: Required setting.
- HoverAnimFrameHeight INT
- Sets the height of a single frame.
- Note: Required setting.
- HoverAnimFrameCount INT
- Sets the number of frames in the animation.
-
HoverAnimFrameCount
* HoverAnimFrameWidth
must be indentical to the image width of the HoverAnimFrames image. So, an animation with 5 frames, each with a size of 32x32, needs an image that has the size 160x32.
- Note: Required setting.
- HoverAnimFrameDelay INT
- Sets the delay between each shown frame.
- *(Label-Name)HoverAnimFrames STRING
- Alternative to
HoverAnimFrames
described above.
- Sets the name of one file containing one frame.
- This file must be in BMP or PNG format format.
- You need one line for every frame in the correct order.
- Make sure you have the same amount of "AnimFrameLines" as you have frames specified in
AnimFrameCount
. And make sure that all have the correct size as specified in AnimFrameWidth
and AnimFrameHeight
.
First of all, an overlay label isn't a normal label, it's only a plain image overlay. Nevertheless it has the most common features of a normal label. Please don't ask for any more features. If you need unsupported features simply use the hooking feature. You can use overlay labels for alpha map overlays, texture overlays, colorizing, multiple texts on big labels, etc. You can combine as many overlay labels as you want and they can overlap each other, they support label groups.
- *(label-name)OverlayLabel COORDINATE COORDINATE DIMENSION DIMENSION STRING #[STRING] [STRING]
- The parameters are:
x
y
width
height
SettingsPrefix
flags
conditionalescapesequence
- You can replace (label-name) with (labelgroup) if you want the same overlay label for a whole group.
- You can replace (label-name) with
AllLabels
if you want the same overlay label for all labels.
- All position and sizing options of the normal labels are available to setup the position and size of the overlay label.
-
x
sets the horizontal position of the overlay relative to its parent.
-
y
sets the vertical position of the overlay relative to its parent.
-
width
and height
sets the size of the overlay label.
-
SettingsPrefix
works just like (label-name) for normal labels. Use SettingsPrefix
infront of any settings you want to use for your overlay label.
-
flags
:
- a
- Specifies that the overlay uses an alpha map image.
- s
- Specifies that the overlay label should have all the same features normal labels have. For example this lets you use the OnEnter and OnLeave events.
- The overlay also gets its own Hover and Pressed xPaintTexture and xPaintHTMLText settings like
SettingsPrefixHoverPaintingMode
and SettingsPrefixPressedFontColor
etc.
- Without the
s
flag the hover and pressed states are still available, but they are bound to (label-name)
's hover and pressed events. If the parent shows its hover state, the overlay does too no matter if you are actually over the overlay or not.
- n
- Draw the overlay when the parent label is in the normal state.
- You need to have normal state settings defined for the overlay label.
- h
- Draw the overlay when the parent label is in the hover state.
- You need to have hover state settings defined for the overlay label.
- p
- Draw the overlay when the parent label is in the pressed state.
- You need to have pressed state settings defined for the overlay label.
- If none of the
n
, h
, or p
flags are set they all defaults to TRUE. (I.e. setting none of them is the same as setting all of them.)
Examples:
For a complete and automatically adapted overlay use for instance:
*ParentOverlayLabel 0 0 100% 100% Ghost #
For a 20 pixel border on the right side of the label without the overlay:
*ParentOverlayLabel 0 0 -20 100% Ghost #
Complete example with settings:
*ParentOverlayLabel 10 10 24 24 Ghost #
GhostPaintingMode .singlecolor
GhostColors 00FF00
GhostHoverPaintingMode .singlecolor
GhostHoverColors 0000FF
GhostPressedPaintingMode .singlecolor
GhostPressedColors FF0000
GhostAddToGroup "GhostGroup" ; Yes, overlay labels support
; the group feature too
- StartHidden BOOL
- If this command is present it makes the overlay label start hidden
All xPaintTexture settings are valid for overlay labels.
The needed xPaintTexture prefix is the "SettingsPrefix" defined in your *(label-name)OverlayLabel
line.
Overlay labels support "Hover" and "Pressed" state settings.
The needed xPaintHTMLText prefix are "SettingsPrefix + Hover" and "SettingsPrefix + Pressed", for the Hover state and Pressed state respectively. "SettingsPrefix" is defined in your *(label-name)OverlayLabel
line.
You can use text on overlay labels, so you can use overlay labels to create multiple text entries in a parent label. Overlay labels don't need to have a background. Simply don't set an image or colors for the overlay label.
- Text "This is my text"
- Sets the text displayed by the overlay label.
- If no value is provided the overlay label is left blank.
- The value can contain both simple text and escape sequences. Escape sequences are enclosed in square brackets ("Simple text [escape]"). See xStatsClass for more information.
You can use HoverText on overlay labels (enable the 's' flag of the overlay label).
- HoverText "This is my hover text"
- Sets the text displayed by the overlay label, if the mouse hovers over it.
- If no value is provided the normal overlay label text is used.
- The value can contain both simple text and escape sequences. Escape sequences are enclosed in square brackets ("Simple text [escape]"). See xStatsClass for more information.
You can disable the TextEscapeSequence processing for the overlay text with
- NoEscapeSequence
- If this command is present the text escape sequences aren't processed anymore. (For example, [cpu] isn't parsed to display the current cpu load.)
- Useful if overlays labels are used with rss readers for instance.
If a Text
is set, then additionally all xPaintHTMLText settings are valid for the label text.
The needed xPaintHTMLText prefix is the "SettingsPrefix", which is defined in your *(label-name)OverlayLabel
line.
Overlay labels support "Hover" and "Pressed" text settings.
The needed xPaintHTMLText prefix is "SettingsPrefix + Hover" and "SettingsPrefix + Pressed". "SettingsPrefix" is defined in your *(label-name)OverlayLabel
line.
You need the 's' flag for this feature.
- Tooltip STRING
- Sets the tooltip text in the overlay label.
- The value can contain both simple text and escape sequences. Escape sequences are enclosed in square brackets ("Simple text [escape]"). See xStatsClass for more information.
- You can use "<br>" to force a line break in the tooltip text. You can use "<tab>" to insert a tab in the tooltip text.
If a tooltip text is set, then additionally all xPaintTooltip settings are valid for the overlay label tooltip.
The needed xPaintTooltip prefix is the "SettingsPrefix" defined in your *(label-name)OverlayLabel
line.
The following events are supported by overlay labels.
OnLeftClickDown
OnLeftClickUp
OnLeftClick
OnRightClickDown
OnRightClickUp
OnRightClick
OnMiddleClickDown
OnMiddleClickUp
OnMiddleClick
OnX1ClickDown
OnX1ClickUp
OnX1Click
OnX2ClickDown
OnX2ClickUp
OnX2Click
These settings also enable the pressed image state in "Seperate Mode", you must activate this mode with the flag 's'.
- !LabelCreateOverlay STRING COORDINATE COORDINATE DIMENSION DIMENSION STRING STRING
- The parameters are:
(label-name)
x
y
width
height
SettingsPrefix
flags
- Creates the overlay label manually. Same as:
*(label-name)OverlayLabel x y width height "SettingsPrefix" #flags
- !LabelDestroyOverlay STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
- Destroys the overlay label.
- !LabelModifyOverlay STRING STRING COORDINATE COORDINATE DIMENSION DIMENSION
- The parameters are:
(label-name)
SettingsPrefix
x
y
width
height
- Modifies the position and/or size of the overlay label.
- !LabelShow STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
- Shows the overlay label
- !LabelHide STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
- Hides the overlay label
- !LabelToggle STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
- Shows the overlay label if it's currently hidden. Hides it if it's currently shown.
- !LabelSetText STRING STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
text
- Sets the text on the overlay label to
text
In all these Bang commands the SettingsPrefix
can either be the name of an overlay label or the whole label group that label's overlay label is a member of.
; First we create the one and only label
; for this example
*Label Parent
ParentAddToGroup Group
ParentResizeBorder 2
ParentResizeBorderSteps 10 10
ParentX 100
ParentY 100
ParentPaintingMode .multicolor
ParentColors FF0000
ParentFontLeftBorder 100
ParentFontRightBorder 40
GroupWidth 250
GroupHeight 50
GroupBorderMethod .bump
*ParentOverlayLabel 0 -15 50 10 Text1 #
Text1Text "[time('i:nn:ss')]"
*ParentOverlayLabel 75 5 50 10 Text2 #
Text2Text "[uptime('i:nn:ss')]"
Text2FontBold
Text2FontColor 00FF00
*ParentOverlayLabel 5 5 25% -20 Ghost1 #s
Ghost1AddToGroup GhostGroup
Ghost1OnEnter !LabelSetText Parent "Enter Ghost1"
Ghost1OnLeave !LabelSetText Parent "Leave Ghost1"
Ghost1OnLeftClick !LabelResizeBy Parent 10 10
*ParentOverlayLabel 40 15 25% -20 Ghost2 #s
Ghost2AddToGroup GhostGroup
Ghost2OnEnter !LabelSetText Parent "Enter Ghost2"
Ghost2OnLeave !LabelSetText Parent "Leave Ghost2"
Ghost2OnRightClick !LabelResizeBy Parent -10 -10
GhostGroupPaintingMode .multicolor
GhostGroupColors FFFFFF
GhostGroupHoverColors 0000FF
GhostGroupPressedColors 00FFFF
*ParentOverlayLabel -40 -16c 32 32 Icon1 #s
Icon1Tooltip "Explorer Icon ToolTip"
Icon1Image "$windir$explorer.exe"
Icon1OnLeftDoubleClick "$windir$explorer.exe"
Just copy and paste this in to your theme and you get a tiny glimps of the possibilities of overlay labels.
Just note that you can manually refresh overlay labels via: !LabelRefresh ParentLabel OverlayLabelSetting NewValue
Example:
!LabelRefresh Box BoxButtonIcon "$IconDir$button1.ico"
In addition to my "Exported Evars", I have added a special "PreBang" to use it in RC-Files without the need of loading the mzscript module.
And the best is, you can use it for any $evar$ you like, not only "my" label exported evars.
- !ParseEvars ACTION
- ACTION has to be a Bang command.
- To use $evars$ that contains the "current" value, use the escape code %# (in mzscripts you should use %|# if you use %[…]%).
-
$TestLabelCurrentWidth$
becomes %#TestLabelCurrentWidth%#
and so on …
Example:
!ParseEvars !vTrayMove -%#vTrayCurrentWidth%# -30
!ParseEvars !execute [!LabelMove Test2Label %#Test1LabelCurrentWidth%# -30][!VWMHide]
!ParseEvars !LabelMove Test2Label %#Test1LabelCurrentWidth+100*Counter%# -50
-
!ParseEvars
can also parse text escape sequences in the current Bang command, with "%[escape sequence]%"
Example:
; Display a MessageBox with the current time.
!ParseEvars !alert "Current Time: %[time]%"
; Positions a "winamplabel" across the screen based on elapsed WinampTime (call with timer-0.5).
!ParseEvars !LabelMove WinampLabel 10 %#%[WinampRemainRime('sec')]%/%[WinampTotalTime('sec')]%*ResolutionY%#
- In mzscript you must write "%|#" instead of "%#".
Example:
*script exec !ParseEvars !LabelMove WinampLabel 10 %|#%[WinampRemainRime('sec')]%/%[WinampTotalTime('sec')]%*ResolutionY%|#
- !SetEvar STRING STRING
- The parameters are:
evar
newvalue
- Sets the value of the given $evar$ to the new specified value.
-
evar
should be the name of the evar without the surrounding dollar signs ($).
- Note: This doesn't change the value in your .rc files, so the change will be lost at the next !recycle
- Most usefull with "my" !ParseEvars Bang command.
Example:
; Set the evar $CustomWidth$ to 100 for later use with !ParseEvars
!SetEvar CustomWidth 100
- !LabelInfoExport STRING [STRING]
- The parameters are:
(label-name)
variable
- Exports the currently displayed LabelText of (label-name) to
variable
- Four possible export methods (Evar, mzScript var, LSLua var or Clipboard)
Evar
!LabelInfoExport (label-name) %#Evar%#
mzScript Var
!LabelInfoExport (label-name) %%mzScriptVar%%
LSLua Var
!LabelInfoExport (label-name) %@LSLuaVar%@
Clipboard
!LabelInfoExport (label-name)
- !LabelInfoExport STRING [STRING]
- The parameters are:
variable
text
- Exports the text escape sequence
text
to variable
- Four possible export methods (Evar, mzScript var, LSLua var or Clipboard)
Evar
!LabelInfoExport %#Evar%# "[date]"
mzScript Var
!LabelInfoExport %%mzScriptVar%% "[date]"
LSLua Var
!LabelInfoExport %@LSLuaVar%@ "[date]"
Clipboard
!LabelInfoExport "[date]"
- !PlaySound [STRING]
- STRING specifies a full path to a wav, mp3, or mid file.
- Plays the specified wav-file, mp3-file or midi-file if found and found valid.
- If you call
!PlaySound
with no paramters it will stop any currently playing sounds.
Bang commands allow you to manipulate labels at run-time through scripts or other modules. See the LiteStep documentation for more information about Bang commands and how to invoke them.
!LabelRefresh
is now the most powerful Bang command ever
!LabelRefresh
with three parameters update the setting you specify, but it also updates any settings you have changed by !SetEvar
. See the examples further down.
Just like with any other Bang command the setting you change with !LabelRefresh
are not permanent. They will be reset on the next recycle.
- !LabelRefresh STRING
- The parameter is:
(label-name)
- Reloads "hardcoded" (saved) settings after a !reload and applies changes to the label.
- !LabelRefresh STRINT STRING STRING
- The parameters are:
(label-name)
labelsetting
newvalue
- Refreshes the label with the updated labelsetting.
- !LabelRefresh STRING STRING STRING
- The parameters are:
(label-group)
labelgroupsetting
newvalue
- Refreshes the
(label-group)
with the updated labelgroupsetting
. Remeber that label specific settings take precedence over label group settings, so all labels in the group might not see the change.
Example:
; All labels in the group MyTestGroup (added to the group by doing
; (label-name)AddToGroup MyTestGroup) that has no individual value
; specified for ''(label-name)Font'' will get the font "Tahoma".
!LabelRefresh MyTestGroup MyTestGroupFont "Tahoma"
- !LabelRefresh STRING STRING STRING
- The parameters are:
(label-group)
*setting
newvalue
- Refreshes the
(label-group)
with the updated label setting (*setting
gets the value newvalue
). Affects all labels in the labelgroup.
Example:
; This affects a whole labelgroup and overrides individual settings
!LabelRefresh MyTestGroup *Font "Tahoma"
- !LabelRefresh STRING STRING STRING
- The parameters are:
(label-name)
(overlay-name)setting
newvalue
- Refreshes the overlay with the updated setting.
You can change almost every label setting on-the-fly without the need of a setting-specific Bang command. You cannot use the !LabelRefresh
Bang command for settings which have their own Bang command. Those Bang commands include, but are not limited to: !LabelAlwaysOnTop
, !LabelSetText
, !LabelMove
, !LabelResize
, etc. Even if making changes to these settings using !SetEvar
and then doing a !LabelRefresh
the label will not be updated. You have to use the dedicated Bang command.
Examples:
To set a new image for you overlay button, do this:
!LabelRefresh Box BoxButtonIcon "$IconDir$button1.ico"
To make a label movable, try this:
; Note that you have to use ''true''. You can not leave that
; out as you can with normal settings in your .rc files
!LabelRefresh PictureLabel PictureLabelMovable true
If you need to change multiple settings at once, only use !LabelRefresh
for the last setting. Change the other settings with !SetEvar
. This is not a requirement, but it will make your theme faster.
This will change the background image, the painting mode, and the font used in your TestLabel
!SetEvar TestLabelFont "Tahoma"
!SetEvar TestLabelPaintingMode .image
!LabelRefresh TestLabel TestLabelImage newimage.jpg
- !LabelCreateOverlay STRING COORDINATE COORDINATE DIMENSION DIMENSION STRING STRING
- The parameters are:
(label-name)
x
y
width
height
SettingsPrefix
flags
- Creates the overlay label manually. Same as:
*(label-name)OverlayLabel x y width height "SettingsPrefix" #flags
- !LabelDestroyOverlay STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
- Destroys the overlay label.
- !LabelModifyOverlay STRING STRING COORDINATE COORDINATE DIMENSION DIMENSION
- The parameters are:
(label-name)
SettingsPrefix
x
y
width
height
- Modifies the position and/or size of the overlay label.
- !LabelShow STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
- Shows the overlay label
- !LabelHide STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
- Hides the overlay label
- !LabelToggle STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
- Shows the overlay label if it's currently hidden. Hides it if it's currently shown.
- !LabelSetText STRING STRING STRING
- The parameters are:
(label-name)
SettingsPrefix
text
- Sets the text on the overlay label to
text
- !LabelHide STRING STRING
- The first STRING is
(label-name)
- The second STRING has to be ".editbox"
- Hides the text edit box, making it invisible.
- !LabelShow STRING STRING
- The first STRING is
(label-name)
- The second STRING has to be ".editbox"
- Shows the text edit box, making it visible.
- If the text edit box is already visible, it will get the keyboard input focus.
- !LabelToggle STRING STRING
- The first STRING is
(label-name)
- The second STRING has to be ".editbox"
- Switches the text edit box back and forth between the visible and invisible states.
- !LabelSetText STRING STRING [STRING]
- The first STRING is
(label-name)
- The second string has to be ".editbox"
- The third string is
text
- Sets the text displayed in the text edit box to
text
- If
text
is empty or not present the text edit box will be cleared of any text.
- !LabelShow STRING
- The parameter is:
(label-name)
- Shows the label, making it visible.
- !LabelHide STRING
- The parameter is:
(label-name)
- Hides the label
(label-name)
, making it invisible.
- !LabelToggle STRING
- The parameter is:
(label-name)
- Switches the label back and forth between the visible and invisible states.
- !LabelShowHide STRING INT
- The parameters are:
(label-name)
time
- If the label is hidden it will be shown for
time
milliseconds then hidden again.
- If the label is visible it will be hidden for
time
milliseconds then shown again.
- !LabelAlwaysOnTop STRING STRING
- The first STRING is
(label-name)
- The second STRING can be:
-
true
or on
- Makes the label "always on top", it stays above all application windows.
-
false
or off
- Pins the label to the desktop so that it stays below all application windows. This the default state and is the opposite of always on top.
-
toggle
or switch
- Switches the label back and forth between the always on top and pinned to desktop states.
- !LabelClipboardCopy STRING [STRING]
- The parameters are:
(label-name)
text
- Copies the contents of the label to the clipboard.
- If the optional
text
is present it will be prefixed to the text that is copied to the clipboard.
- !LabelClipboardPaste STRING [STRING]
- The parameters are:
(label-name)
text
- Sets the label's text to the current contents of the clipboard.
- If the optional text parameter is present it will be inserted before the clipboard contents in the label.
- Naturally, this only works if the clipboard contains text.
- !LabelCreate STRING
- The parameter is:
(label-name)
- Manually creates the label named
(label-name)
- !LabelDestroy STRING
- The parameter is:
(label-name)
- Destroys the label named
(label-name)
- !LabelDock STRING STRING [BOOL] [STRING]
- The parameters are:
(label-name1)
(label-name2)
bool
modifier
- Docks
(label-name1)
to (label-name2)
, when bool
is set to true
or not defined.
- Undocks
(label-name1)
when bool
is set to false
.
- If
bool
is set to true
modifier
can be "left", "top", "right", "bottom", "topleft", "topright", "bottomleft", or "bottomright". This affects how the docked label reacts to Moving/Resizing of (label-name2)
.
- !LabelFocus STRING
- The parameter is:
(label-name)
- Trys! to set the keyboard input focus to
(label-name)
. Probably only works if another label already has the focus.
- !LabelModuleHook STRING ACTION
- The parameters are:
(label-name)
!ModuleHookBang
- With this Bang command you can hook a module/label inside
(label-name)
on-the-fly.
- This is basically the same as a
*(label-name)ModuleHook
line, the !ModuleHookBang
syntax is the same as always. See the section on Hook Modules On Labels for more details.
- !LabelMove STRING COORDINATE COORDINATE [INT] [INT]
- The parameters are:
(label-name)
x
y
steps
time
- Moves the label. The move will be animated if both
steps
and time
are set.
-
steps
sets the animation steps and time
sets the pause time between two steps in milliseconds. Maximum pause time is 50ms.
- !LabelMoveBy STRING INT INT [INT] [INT]
- The parameters are:
(label-name)
dx
dy
steps
time
- Lets you move the label relative to its current position. The move will be animated if both
steps
and time
are defined.
- To keep current position set
x
or y
to 0. Negative values moves the label to the left/top, positive to the right/bottom.
-
steps
are the number of animation steps and time
sets the pause time between two steps in milliseconds. Maximum pause time is 50ms.
- !LabelResize STRING DIMENSION DIMENSION [INT] [INT]
- The parameters are:
(label-name)
width
height
steps
time
- Resizes the label. The resize will be animated if both
steps
and time
are defined.
-
steps
are the number of animation steps and time
sets the pause time between two steps in milliseconds. Maximum pause time is 50ms.
- !LabelResizeBy STRING INT INT [INT] [INT]
- The parameters are:
(label-name)
dw
dh
steps
time
- Resizes the label relative to current size. The resize will be animated if both
steps
and time
are defined.
- If
dw
and/or dh
is negative the label is shrunken dw
and/or dh
pixels. If they are positive the label is increased in size.
- To keep the current width, set
dw
to 0. To keep the current height, set dh
to 0.
-
steps
are the number of animation steps and time
sets the pause time between two steps in milliseconds. Maximum pause time is 50ms.
- !LabelReposition STRING COORDINATE COORDINATE DIMENSION DIMENSION [INT] [INT]
- The parameters are:
(label-name)
x
y
width
height
steps
time
- Repositions (moves and resizes) the label
(label-name)
.
- Works like
!LabelMove
and !LabelResize
combined.
- !LabelReposition STRING COORDINATE COORDINATE DIMENSION DIMENSION [INT] [INT]
- The parameters are:
(label-name)
dx
dy
dw
dh
steps
time
- Repositions (moves and resizes) the label relative to its current size and position
(label-name)
.
- Works like
!LabelMoveBy
and !LabelResizeBy
combined.
- !LabelNext STRING
- The parameter is:
(label-name)
- Switches to the next text. See the section on Text Setup for more info.
- !LabelPrevious STRING
- The parameter is:
(label-name)
- Switches to the previous text. See the section on Text Setup for more info.
- !LabelScroll STRING STRING [INT]
- The parameters are:
(label-name)
mode
scrollmode
- Controlls the scrolling of the text in the label.
-
mode
can take the following values:
-
true
or on
- Turns scrolling on
-
false
or off
- Turns the scrolling off
-
freeze
- Freezes the scrolling if the text is currently scrolling. Restarts the scrolling if the text is currently frozen.
- Number
- If
mode
is a number the label scrolls the given number of times.
- If the number is 0 and the label is already scrolling it will finish the "current scroll" and then stop.
-
scrollmode
is only needed if you haven't already set (label-name)Scroll
. scrollmode
can take the following values:
- 1
- Scroll to the left (this is the default).
- 2
- Scroll to the right.
- 3
- Scroll down.
- 4
- Scroll up.
- !LabelSetAlpha STRING INT [INT] [INT]
- The parameters are:
(label-name)
amount
steps
time
- Sets the alpha transparency on the fly. The change will be animated if both
steps
and time
are defined.
-
amount
determines how transparent the label will be. Valid values for amount
are 0-255, where 0 is totally transparent and 255 is opaque.
-
steps
are the number of animation steps and time
sets the pause time between two steps in milliseconds. Maximum pause time is 50ms.
- !LabelSetAnimation STRING STRING [INT]
- The parameters are:
(label-name)
state
loops
- Start/stop frame animation (only normal) or start and loop given number of times and then stop.
-
state
can be true
/on
or false
/off
-
loop
determines how many full animation cycles to do. For infinite looping use -1 for loops
.
- !LabelSetText STRING [STRING]
- The parameters are:
(label-name)
text
- Sets the text displayed in the label.
- If
text
is not present then the label will be cleared of any text.
- !LabelUpdate STRING
- The parameter is:
(label-name)
- Forces the label to update its contents.
Events allows you to execute programs or Bang commands based on user interaction with the label. The following work the same as configuration settings. Each of them takes the name of a program or a Bang command as their value. When the event is triggered, the program or Bang command is executed. Note that in the case of mouse clicks, assigning an action to both the click and the double click event will not work. As before, you must prefix the command name with the label name.
Clicking outside of these specified regions, or if none are defined, executes the normal mouse click command. If regions overlap each other, the first matching region defined in the LiteStep configuration files will be executed.
- *(label-name)OnLeftClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when clicked with the left mousebutton. You can have as many of these lines as you want.
- *(label-name)OnLeftDoubleClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when doubleclicked with the left mousebutton. You can have as many of these lines as you want.
- *(label-name)OnMiddleClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when clicked with the middle mousebutton. You can have as many of these lines as you want.
- *(label-name)OnMiddleDoubleClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when doubleclicked with the middle mousebutton. You can have as many of these lines as you want.
- *(label-name)OnRightClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when clicked with the right mousebutton. You can have as many of these lines as you want.
- *(label-name)OnRightDoubleClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when doubleclicked with the right mousebutton. You can have as many of these lines as you want.
- *(label-name)OnX1ClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when clicked with the X1 mousebutton. You can have as many of these lines as you want.
- *(label-name)OnX1DoubleClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when doubleclicked with the X1 mousebutton. You can have as many of these lines as you want.
- *(label-name)OnX2ClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when clicked with the X2 mousebutton. You can have as many of these lines as you want.
- *(label-name)OnX2DoubleClickRegion COORDINATE COORDINATE DIMENSION DIMENSION ACTION
- The parameters are:
x
y
width
height
action
- Specifies a region inside the label which executes the given action when doubleclicked with the X2 mousebutton. You can have as many of these lines as you want.
- *(label-name)TooltipRegion COORDINATE COORDINATE DIMENSION DIMENSION STRING
- The parameters are:
x
y
width
height
tooltip
- Specifies a region inside the label which has the given tooltip when hovering over this area. You can have as many of these lines as you want.
- Text escape sequences are fully supported.
- OnEnter ACTION
- Sets an action to perform when the mouse cursor enters the label.
- OnLeave ACTION
- Sets an action to perform when the mouse cursor leaves the label.
- OnHover ACTION
- Sets an action to perform when the mouse hovers over the label.
- "Hover" means that the mouse stays for a specific time (defined with
(label-name)HoverTimeOut
) nearly motionless over the label.
- OnDrop STRING [STRING]
- The parameters are:
fileaction
path
- Sets an action to perform when files or folders are dropped on the label. User confirmation on overwrite or deletion is required.
-
fileaction
can be: "move", "copy", "delete files" or "shortcut"
-
path
is the path to move, copy or create shortcut to. path
must be quoted (enclosed in '" "').
Examples:
; Moves dropped files to C:\MoveTarget\
(label-name)OnDrop move "C:\MoveTarget\"
; Copies dropped files to C:\CopyTarget\
(label-name)OnDrop copy "C:\CopyTarget"
; Deletes files you drop on the label
(label-name)OnDrop delete files
; Creates shortcuts to the dropped files in C:\ShortCutTarget\
(label-name)OnDrop shortcut "C:\ShortCutTarget\"
- OnDrop ACTION
- ACTION must be a Bang command.
- "%[droppath]%" (lowercase) will be replaced with the full path of the dropped file.
- If "%[droppath]%" isn't explicitly used in the Bang command the drop path will be appended to the Bang command.
Example:
(label-name)OnDrop !execute [!alert "%[droppath]%" "Saved"][!xtextsaveevar @$configdir$save.rc@ @dropped@ @%[droppath]%@]
- OnLeftClickDown ACTION
- Sets an action to perform when the user presses down the left mouse button on the label.
- OnLeftClick ACTION
- Sets an action to perform when the user left clicks on the label
- OnLeftClickUp ACTION
- Sets an action to perform when the user left clicks on the label (releases the left mouse button).
- OnLeftDoubleClick ACTION
- Sets an action to perform when the user double-clicks the label with the left mouse button.
- OnMiddleClickDown ACTION
- Sets an action to perform when the user presses the middle mouse button down on the label.
- OnMiddleClick ACTION
- Sets an action to perform when the user middle clicks on the label.
- OnMiddleClickUp ACTION
- Sets an action to perform when the user middle clicks on the label (releases the middle mouse button).
- OnMiddleDoubleClick ACTION
- Sets an action to perform when the user double-clicks the label with the middle mouse button.
- OnRightClickDown ACTION
- Sets an action to perform when the user presses the right mouse button down on the label.
- OnRightClick ACTION
- Sets an action to perform when the user right clicks on the label.
- OnRightClickUp ACTION
- Sets an action to perform when the user right clicks on the label (releases the right mouse button).
- OnRightDoubleClick ACTION
- Sets an action to perform when the user double-clicks the label with the right mouse button.
- OnX1ClickDown ACTION
- Sets an action to perform when the user presses the X1 mouse button down on the label.
- OnX1Click ACTION
- Sets an action to perform when the user clicks with the X1 button on the label.
- OnX1ClickUp ACTION
- Sets an action to perform when the user clicks with the X1 button on the label (releases the X1 mouse button).
- OnX1DoubleClick ACTION
- Sets an action to perform when the user double-clicks the label with the X1 mouse button.
- OnX2ClickDown ACTION
- Sets an action to perform when the user presses the X2 mouse button down on the label.
- OnX2Click ACTION
- Sets an action to perform when the user clicks with the X2 button on the label.
- OnX2ClickUp ACTION
- Sets an action to perform when the user clicks with the X2 button on the label (releases the X2 mouse button).
- OnX2DoubleClick ACTION
- Sets an action to perform when the user double-clicks the label with the X2 mouse button.
- OnTextChange ACTION
- Sets an action to perform when the text in the label changes.
- OnWheelDown ACTION
- Sets an action to perform when the mouse wheel scrolls down while the mouse cursor hovers over the label.
- OnWheelUp ACTION
- Sets an action to perform when the mouse wheel is scrolled up while the mouse cursor hovers over the label.
- OnResize ACTION
- Sets an action to perform when the label has changed its size. (Suitable for AutoWidth/Height labels.)
- Initial sizing will be ignored.
- OnMove ACTION
- Sets an action to perform when the label has changed its position.
- Initial positioning will be ignored.
- OnShow ACTION
- Sets an action to perform when the label shows up (executed only after Bang command call and [hideifempty(x)]).
- Main purpose is a method to automatically react on [hideIfEmpty(x)]
- OnHide ACTION
- Sets an action to perform when the label hides (executed only after Bang Call and [hideifempty(x)]).
- Main purpose is a method to automatically react on [hideIfEmpty(x)]
- OnFocusGained ACTION
- Sets an action to perform when the label gets the input focus.
- OnFocusLost ACTION
- Sets an action to perform when the label looses the input focus.
- OnKeyDown ACTION
- Sets an action to perform when a key is pressed and the label has the (keyboard) focus.
- The
keycode
is referenced by it's INT value.
- In the ACTION the string
%[keycode]%
will be replaced with the INT value.
- OnKeyUp ACTION
- Sets an action to perform when a key is released and the label has the (keyboard) focus.
- The
keycode
is referenced by it's INT value.
- In the ACTION the string
%[keycode]%
will be replaced with the INT value.
- OnAnimLoopStart ACTION
- Sets an action to perform when an animation is started.
- This action is only triggered on the very first start, when the animation is changed with
!LabelSetAnimation
or the label is hidden and then shown again.
- OnAnimLoopStop ACTION
- Sets an action to perform when an animation is stopped.
- This action is only triggered when the last loop is reached, when the animation is stopped with
!LabelSetAnimation
or the label is hidden.
All these events has a parameter called modifier
. modifier
can be: .ctrl, .shift, .alt and all combinations of those three (.ctrl+shift, .shift+alt, .alt+shift+ctrl, …). The action is executed, if the matching key combination is pressed during the click.
- *(label-name)OnLeftClickDown STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user presses the left mouse button down on the label.
- *(label-name)OnLeftClick STRING ACTION
- *(label-name)OnLeftClickUp STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user left clicks on the label (releases the left mouse button).
- *(label-name)OnLeftDoubleClick STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user double-clicks the label with the left mouse button.
- *(label-name)OnMiddleClickDown STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user presses the middle mouse button down on the label.
- *(label-name)OnMiddleClick STRING ACTION
- *(label-name)OnMiddleClickUp STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user middle clicks on the label (releases the middle mouse button).
- *(label-name)OnMiddleDoubleClick STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user double-clicks the label with the middle mouse button.
- *(label-name)OnRightClickDown STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user presses the right mouse button down on the label.
- *(label-name)OnRightClick STRING ACTION
- *(label-name)OnRightClickUp STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user right clicks on the label (releases the right mouse button).
- *(label-name)OnRightDoubleClick STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user double-clicks the label with the right mouse button.
- *(label-name)OnX1ClickDown STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user presses the X1 mouse button down on the label.
- *(label-name)OnX1Click STRING ACTION
- *(label-name)OnX1ClickUp STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user clicks with the X1 button on the label (releases the X1 mouse button).
- *(label-name)OnX1DoubleClick STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user double-clicks the label with the X1 mouse button.
- *(label-name)OnX2ClickDown STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user presses the X2 mouse button down on the label.
- *(label-name)OnX2Click STRING ACTION
- *(label-name)OnX2ClickUp STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user clicks with the X2 button on the label (releases the X2 mouse button).
- *(label-name)OnX2DoubleClick STRING ACTION
- The parameters are:
modifier
action
- Sets an action to perform when the user double-clicks the label with the X2 mouse button.
ESC = 27
F1 = 112
F2 = 113
F3 = 114
F4 = 115
F5 = 116
F6 = 117
F7 = 118
F8 = 119
F9 = 120
F10 = 121
F11 = 122
F12 = 123
PAUSE = 19
1 = 49
2 = 50
3 = 51
4 = 52
5 = 53
6 = 54
7 = 55
8 = 56
9 = 57
0 = 48
BACKSPACE = 8
INSERT = 45
HOME = 36
PAGEUP = 33
TAB = 9
A = 65
B = 66
C = 67
D = 68
E = 69
F = 70
G = 71
H = 72
I = 73
J = 74
K = 75
L = 76
M = 77
N = 78
O = 79
P = 80
Q = 81
R = 82
S = 83
T = 84
U = 85
V = 86
W = 87
X = 88
Y = 89
Z = 90
DELETE = 8
END = 35
PAGEDOWN = 34
CAPSLOCK = 20
ENTER = 13
SHIFTLEFT = 16
SHIFTRIGHT = 16
CTRLLEFT = 17
APPLEFT = 91
SPACE = 32
ALTGR = 17
APPRIGHT = 92
MENU = 93
CTRLRIGHT = 17
ARROWLEFT = 37
ARROWUP = 38
ARROWRIGHT = 39
ARROWDOWN = 40
You will need to define dummy variables if you include these in scripts/rc files with standard $evar$ syntax, since when LiteStep reads these files xLabel has not yet added them, causing LS to think the variables are undefined.
Only useful, if used in handtyped Bang commands (LSXCommand), or if you use it in mzscripts, or with "my" special !ParseEvars
Bang command. To use $evars$ in Bang commands, which contain the "current" value, use the escape code %# and prefix the Bang command you want to use with !ParseEvars
. Read the section on the !LabelRefresh Bang command for more information.
- $(label-name)Visible$
- The current visibility state of the label, either
true
or false
.
- $(label-name)CurrentX$
- The current horizontal position of the label.
- $(label-name)CurrentY$
- The current vertical position of the label.
- $(label-name)CurrentWidth$
- The current width of the label.
- $(label-name)CurrentHeight$
- The current height of the label.
- $(label-name)TexteditBoxVisible$
- The current visibility state of the text edit box in the label, either
true
or false
.
- $(label-name)CurrentTextEditBoxText$
- The current content of the text edit box in the label.
- Updated when pressing <Enter> in the text edit box and on calls to
!LabelSetText (label-name) .editbox
.
- TextEditBox COORDINATE COORDINATE DIMENSION STRING [INT]
- The parameters are:
x
y
width
flags
chars
-
flags
must start with # and can then be any combination of the following:
- h
- Hidden
- The text edit box is hidden on start.
- l, c and r
- Sets the text alignment inside the text edit box
- 'l'eft is the default.
- p
- Password
- The entered text is shown as the password character (asterisk).
- n
- Numbers
- Allows only digits to be entered into the text edit box.
- Even if no flags are specified the # character still has to be there.
-
chars
restricts the amount of characters that can can be entered.
Example:
; Creates a text edit box that is as wide as the label it is
; created in.
; At most six characters can be entered in the box. Could be
; usefull for specifying a hexadecimal color value, like FF00FF
ExampleLabelTextEditBox 0 0 100% # 6
- TextEditBoxCursor STRING
- The parameter is:
cursorpath
.
- Specifies what cursor to change to when entering the text edit box.
-
cursorpath
can be: "", ".none", "Path to cursor in LSImageFolder", or "Full Path to Cursor"
- Default is normal caret cursor (this is what you get if
cursorpath
is "").
- If ".none" is specified no cursor change is performed at all, otherwise any valid cursor can be used.
- TextEditBoxPadding INT INT INT INT or INT INT or INT
- The parameters are:
left
right
top
bottom
or left/right
top/bottom
or left/right/top/bottom
- Accepts 4, 2 or 1 INT value(s) which define the amount of padding in pixels between the text and the edge of the text edit box.
All xPaintTexture settings are valid for the text edit box background.
The needed xPaintTexture prefix is (label-name)+"TextEditBox".
- TextEditBoxEnterAction ACTION
- The parameter is:
specialaction
- The action is fired if you press <Enter>.
-
specialaction
can be:
- .execute
- Tries to execute the text in the edit box (everything LSExecute can handle will work).
- This is the default
- .settext
- Sets the label text to the text in the edit box.
- Any Bang command
-
%[textinput]%
in the Bang command will be replaced with the text in the edit box.
Example:
; This will show a message box with the text in the edit box
ExampleLabelTextEditBoxEnterAction !alert "%[textinput]%" "Hi"
- TextEditBoxOnSuccess ACTION
- Sets an action to perform when the entered action is performed successfully.
- That means either the programm is launched, or the Bang command was executed.
- You can, for instance, use it to clear the text edit box.
-
%[textinput]%
in the ACTION will be replaced with the text in the edit box.
- TextEditBoxOnFail ACTION
- Sets an action to perform when the entered action couldn't be performed.
-
%[textinput]%
in the ACTION will be replaced with the text in the edit box.
Example:
ExampleLabelTextEditBoxOnFail !alert "I could not execute %[textinput]%" "Sorry"
- TextEditBoxOnFocus ACTION
- Sets an action to perform when the text edit box gets input focus (mostly happens by clicking it the first time or calling
!labelshow (label-name) .editbox
)
- TextEditBoxOnUnFocus ACTION
- Sets an action to perform when the text edit box looses input focus.
- !TextEditBoxExecute STRING ACTION
- The parameters are:
(label-name)
bang
- This Bang command executes
bang
like a normal !execute with just one difference; It replaces %[textinput]%
with the text edit box text of the label (label-name)
.
- So you can execute the "EnterAction" of a text edit box from anywhere within LiteStep.
-
TextEditBoxOnSuccess
and TextEditBoxOnFail
will fire as appropriate.
Example:
; Shows a message box with the text that is currently
; in ExampleLabel's text edit box
!TexteditBoxExecute ExampleLabel !execute [!alert %[textinput]%]
- !LabelShow STRING STRING
- The first STRING is
(label-name)
- The second string has to be
.editbox
- If the edit box is not shown, this Bang command will show it and give it keyboard input focus.
- If the edit box is already visible it will get keyboard input focus.
- !LabelFocus STRING STRING
- The first STRING is
(label-name)
- The second string has to be
.editbox
- This Bang command will focus the edit box.
- !LabelHide STRING STRING
- The first STRING is
(label-name)
- The second string has to be
.editbox
- This Bang command will hide the edit box.
- !LabelToggle STRING STRING
- The first STRING is
(label-name)
- The second string has to be
.editbox
- This Bang command will toggle the visibility of the edit box.
- !LabelSetText STRING STRING [STRING]
- The first STRING is
(label-name)
- The second STRING has to be
.editbox
- The third STRING is
text
- Sets the text of the edit box to
text
, or clears the current text if text
isn't defined.
xLabel supports the LsBox hook feature. So all modules that support hooking can be hooked in to an xLabel. The syntax is exactly the same as for LSBox, except that you don't have .box files and must use *(label-name)ModuleHook
instead of *ModuleHook
.
Modules known to support hooking: (x)Label, Rabidvwm, Tasks, Taskbar(3), vTray, LSSlider, LSXCommand, ClockWork, xProp, RainMeter-0.9.
Important:
You have to load the modules you want to hook before you load xLabel.
The modules seem to have problems when hooked at negative coordinates, therefore it's recommended to only use positive coordinates.
You can not use a label that has (label-name)TrueTransparency
or (label-name)AlphaMap
set to true
as a parent label for a hook if it doesn't have a background set (Image, Color, …).
- *(label-name)ModuleHook ACTION STRING [STRING] …
- The parameters are:
hookbang
userdata1
userdata2
…
- (label-name) is the label the module will be loaded into.
- Read the documentation for the module you want to hook to find out what
hookbang
to use.
Examples:
; Hooks HookedLabel into ExampleLabel
*ExampleLabelModuleHook !LabelLsBoxHook HookedLabel
; Hooks RabidVWM into ExampleLabel
*ExampleLabelModuleHook !VWMLoadBoxHook
; Hooks the xTaskbar called HookedBar into ExampleLabel
*ExampleLabelModuleHook !xTaskbarLSBoxHook
; Hooks LSSlider into ExampleLabel
*ExampleLabelModuleHook !SliderHook "Main volume" 10 0 5 background.bmp handle.bmp HI [VOLUME] 0
xLabel supports the *ModuleHook
feature of LSBox.
- *ModuleHook !LabelLSBoxHook STRING
- The parameter is:
(label-name)
- Creates a label inside an LSBox.
- All the settings for the label will still be in the step.rc. Make sure that you do not put the same name in both a *ModuleHook and a *Label command. Note that xLabel must be loaded before LSBox in order for this to work.
- *(label-name)ModuleHook !LabelLSBoxHook STRING
- The parameter is:
(label-name2)
-
(label-name2)
will be hooked inside the label (label-name)
The following Bang commands/features do not work for labels hooked in a label/LSBox: