Table of Contents

xTaskbar Version 2.x Documentation

Latest version of xTaskbar is 2.3

This is xTaskbar-2.3, a LiteStep module used to display a list of the currently running programs/tasks.

You need to load xPaintClass-1.0 before xTaskbar, otherwise xTaskbar won't load! xTaskbar can also use the features of xStatsClass. If you want to use those features you need to load xStatsClass before xTaskbar.

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

Overview

Add some new LoadModule lines somewhere in your theme configuration, similar to the following (this assumes that xTaskbar-2.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\xTaskbar-2.3.dll"

or the newer *NetLoadModule lines:

*NetLoadModule xPaintClass-1.0
*NetLoadModule xStatsClass-1.1
*NetLoadModule xTaskbar-2.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 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 name of the xTaskbar, normally this is xTaskbar.

Occurrences of (taskbar-name) should be replaced by the actual name of the xTaskbar, normally this is xTaskbar.

Legend

[ ]
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 taskbar 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 taskbar 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

Configuration Values

Size and Position

X COORDINATE
Sets the horizontal position of the taskbar.

Examples:

xTaskbarX 5    ; 5 pixels to the right of the LEFT side of the parent
xTaskbarX ~5   ; 5 pixels to the left of the LEFT side of the parent 
               ; (Just as info, this is outside the parent)
xTaskbarX -5   ; 5 pixels to the left of the RIGHT side of the parent

xTaskbarX 1@-5 ; 5 pixels to the left of the RIGHT side of the primary monitor
Y COORDINATE
Sets the vertical position of the taskbar.

Examples:

xTaskbarY 5    ; 5 pixels to the bottom of the TOP side of the parent
xTaskbarY ~5   ; 5 pixels to the top of the TOP side of the parent
               ; (Just as info, this is outside the parent)

xTaskbarY -5   ; 5 pixels to the top of the BOTTOM side of the parent
xTaskbarY 1@-5 ; 5 pixels to the top of the BOTTOM side of the primary monitor
Width DIMENSION
Sets the horizontal size of the taskbar.
Height DIMENSION
Sets the vertical size of the taskbar.
AutoSize INT [INT] [INT]
The parameters are: maxtaskbarsize steps delay
Resizes the taskbar to exactly fit around the current number of running tasks. The resize will be animated if both steps and size are set.
maxtaskbarsize sets the maximum width or height the taskbar will automatically resize to. maxtaskbarsize controls the maximum width if the taskbar layout is .horizontal and the maximum height if the taskbar layout is .vertical.
steps sets the animation steps and time sets the pause time between two steps in milliseconds. Maximum pause time is 50ms.
ButtonMaxWidth and ButtonMaxHeight must also be set.
Attention: This feature isn't suitable for all "normal" taskbars. You should only use this if you want to use a taskbar layout that uses mainly fixed size buttons. For instance taskbars that only contains big icons.
AlwaysOnTop BOOL
If this command is present it makes the taskbar "AlwaysOnTop". The taskbar stays above all application windows.
WindowZOrder BOOL
If this command is present it enables the normal window z-order behavior, that means, the taskbar floats on top like a normal window when activated.
BehindWindow STRING [STRING]
The parameters are: classname windowtext
If classname (and windowtext) is set, the taskbar is placed behind this window and will "never" come to front.
If the special "HWND_TOP" is used for classname, the taskbar tries to stay on top of other windows. Only one module should use the "HWND_TOP" classname.
By default the taskbar never changes its z-order after the first creation (as long as AlwaysOnTop isn't set).
StartHidden BOOL
If this command is present, then the taskbar will be initially invisible. It can later be shown using Bang commands.

Layout

Layout STRING
STRING can be either .horizontal or .vertical.
Sets the basic layout, and affects how the taskbar is filled with task buttons.
If no value is provided, then the default is .horizontal.
ButtonDirection STRING
STRING can be .left, .right, .top or .bottom.
Sets the direction in which new task buttons are added.
If no value is provided, then the default is .right (.bottom for vertical layouts).
ButtonXSpacing INT
Sets the X (= horizontal) spacing between task buttons.
If no value is provided, then the default is 0.
ButtonYSpacing INT
Sets the Y (= vertical) spacing between task buttons.
If no value is provided, then the default is 0.
Lines INT
Sets the number of lines (.horizontal layout) or rows in the taskbar (.vertical layout).
If no value is provided, then the default is 1.
MaxLines INT
Sets the maximum allowed number of taskbar lines or rows.
This setting takes precedence over Lines
WrapCount INT
The taskbar wraps (a new line is added), if the number of task buttons exceeds this value.
If no wrap count is set, there is no automatic adding of lines.
If more than one taskbar line is set and no wrap count is set, then the default wrap count is 5.
ButtonWrapDirection STRING
STRING can be .top, .bottom, .left or .right.
Sets the direction in which new task buttons are added after a wrap in multiline taskbars.
If no value is provided, then the default is .bottom (.right for vertical layouts).
ButtonMaxCount INT
This command sets the maximum number of task buttons that will be displayed in the taskbar.
You can scroll through the "invisible" buttons with the Bang command !xTaskbarScrollButtons.
This feature will not work with a taskbar that uses AutoSize
ButtonMaxWidth INT
Maximum width of a task button.
If no value is provided, then the default is $ResolutionX$.
ButtonMaxHeight INT
Maximum height of a task button.
If no value is provided, then the default is 32.
ButtonAdaptiveSize BOOL
If this command is present and you use WrapCount (or Lines), then the width of the task buttons is adapted to fill up the available taskbar space completely if more than WrapCount buttons are visible.
Let's say you have a 500 pixels wide taskbar, a ButtonMaxWidth of 200 and WrapCount set to 2. When a third task is added the new task button will be added to a new row of tasks. Without setting ButtonAdaptiveSize you would have 100 pixels that never get used on the first row of task buttons. With ButtonAdaptiveSize the task buttons would be made 250 pixels wide, overriding ButtonMaxWidth, to fill the entire taskbar.
(Basically it enables the behavior of the former xTaskbar (older than 2.1.6) versions.)
LeftBorder INT
Sets the number of pixels on the left edge to reserve as a border to the task buttons.
If no value is provided, then the default is 0.
TopBorder INT
Sets the number of pixels on the top edge to reserve as a border to the task buttons.
If no value is provided, then the default is 0.
RightBorder INT
Sets the number of pixels on the right edge to reserve as a border to the task buttons.
If no value is provided, then the default is 0.
BottomBorder INT
Sets the number of pixels on the bottom edge to reserve as a border to the task buttons.
If no value is provided, then the default is 0.
Borders INT INT INT INT
Borders INT INT
Borders INT
Accepts 4, 2 or 1 INT value(s), which define the borders.
The values provided are either Left Right Top Bottom, Left/Right Top/Bottom, or Left/Right/Top/Bottom.
This is a single configuration-line alternative to using LeftBorder, RightBorder, TopBorder, and BottomBorder

Tooltips

ShowTooltip BOOL
Controls the visibility of the task button tooltips.
If no value is provided, then the default is true.
TooltipMode STRING
STRING can take the following values:
.prefix-caption-file
Shows the title bar text of the task with the text "Caption:" in front of it. Also shows the path to the task with the text "Executable:" in front of it.
.caption-file
Shows the title bar text and the path to the task.
.prefix-caption
Shows the title bar text of the task with the text "Caption:" in front of it.
.caption
Shows the title bar text of the running task.
.prefix-file
Shows the path to the task with the text "Executable:" in front of it.
.file
Shows the path to the task.

Additionally all xPaintTooltip settings are valid for the taskbar tooltips.

The needed xPaintTooltip prefix is (taskbar-name), normally this is xTaskbar.

Transparency features

AlphaTransparency INT
Sets the alpha transparency of the taskbar (eg. you will see the background or a window you drag below the taskbar shine through).
Valid values are 0-255, where 0 is totally transparent and 255 is opaque.
If no value is provided, then the default is 255.
OS requirement: Windows 2000 or newer.
Caution: AlphaTransparency doesn't work with a hooked taskbar.
AlphaMap BOOL
If this command is present, then the taskbar uses real per-pixel alpha transparency used in PNG images.
OS requirement: Windows 2000 or newer.
Caution: AlphaMap doesn't work with a hooked taskbar.
AlphaFade BOOL
If this command is present, then the taskbar will be fade in/out on show/hide.
OS requirement: Windows 2000 or newer.
Caution: AlphaFade doesn't work with a hooked taskbar.
CustomAlphaFade INT INT
The parameters are: stepsize delay
Makes the taskbar fade in/out on show/hide.
stepsize is the number of transparency steps to take when animating (range 0 - 255).
delay is the time in ms to pause at each step.
OS requirement: Windows 2000 or newer.
Caution: CustomAlphaFade doesn't work with a hooked taskbar.
TrueTransparency BOOL
If this command is present, then the transparent parts (parts of the image painted with MagicPink = FF00FF) will be fully removed.

Other

LoadInBox BOOL
Must be set to hook the taskbar in another LiteStep module.
HideIfEmpty BOOL
If this command is present the taskbar hides itself when it is empty, and shows up again if a task button is added.
NoCreateAtStartup BOOL
If this command is present no taskbar will be created on startup.
Display STRING
STRING can be flashing, all, normal, active, minimized, normal+active, normal+minimized or active+minimized.
Defines, which button states your taskbar should display.
all is the default and it is not recommended to change this unless you have more than one taskbar.
HoverStateDisplay STRING
STRING can be flashing, all, normal, active, minimized, normal+active, normal+minimized or active+minimized.
Makes the taskbar only register hover in the specified state(s). Both for normal task buttons and overlay buttons.
If you need multiple hover states you have to use overlay buttons.
HoverIcon and HoverFont settings only uses the HoverStateDisplay setting to determine if they should be used or not.
Sort STRING
STRING can be .none, .filename, .classname, .windowname or .zorder.
Sorts the tasks alphabetically ascending with the specified method.
.none is the default.
Note: Drag'n'Drop sorting is only possible if Sort is set to .none.
FocusOnEnter BOOL
If this command is present the taskbar "steals" the focus from the active window when the mouse enters the taskbar.
This provides instant mouse wheel functions. That is the one and only intended purpose of this setting.
NoMinimizeOnClick BOOL
If this command is present, clicking a selected task button will not minimize the application.
AddOnlyMatching STRING
The parameter is: matchingstrings
If defined, the only tasks that are shown in this taskbar are the ones which match one of the strings in matchingstrings. The search is case-insensitive. You can add as many wildcard strings as you want/need.
matchingstrings support normal wildcards and the strings to search for are separated with a semicolon ";". Each string specifies a part of a window classname or title to search for.

Example:

; xTaskbar will only show tasks whose classname or windowtext 
; either starts with "super", or contains "free" at any 
; place inside them.

xTaskbarAddOnlyMatching "super*;*free*"
RemoveOnlyMatching STRING
The parameter is: matchingstrings
If defined, the tasks that are removed (not shown) in this taskbar are the ones which match one of the strings in matchingstrings. The search is case-insensitive. You can add as many wildcard strings as you want/need.
matchingstrings support normal wildcards and the strings to search for are separated with a semicolon ";". Each string specifies a part of a window classname or title to search for.

Example:

; xTaskbar will not show tasks whose classname or windowtext 
; either starts with "super", or contains "free" at any 

; place inside them.
xTaskbarRemoveOnlyMatching "super*;*free*"

MultiMonitor

SpecifiedMultiMonitorOnly INT
The INT can be 0 to 3, where 1 is the primary monitor, 2 the secondary monitor, etc.
This setting controls what tasks to show based on what monitor they are on. Specifying 2 for example only shows tasks that are on the secondary monitor.
0 is special. It refers to the monitor on which the taskbar currently is. Using 0 it works this way: If you move the taskbar from the secondary monitor to the primary, the taskbar automatically shows only the tasks on the new monitor.

VWM

Attention: You have to load the vwm module before xTaskbar!

VWMSpecifiedDesktopOnly INT
The taskbar will only show the tasks, which are on the specified VWM desktop (0 based).
You need at least RabidVWM v1.2.1, BangVWM v0.41 or any newer VWM module that supports LM_GETDESKTOPOF.
VWMCurrentDesktopOnly BOOL
If this command is present only the tasks that are on the current desktop are displayed.
You need at least RabidVWM v1.2.1, BangVWM v0.41 or any newer VWM module that supports LM_GETDESKTOPOF.

Icon

ShowIcon BOOL
Controls the visibility of the task icons in task buttons.
If no value is provided, then the default is true.
LargeIconChangeAt INT
The parameter is: threshold
If the IconSize (of the xPaintIcon class) is equal to or bigger than threshold a large icon is extracted and used.
If no value is provided, then the default is 32 (32x32 Icon).
Minimum value is 17.

Text

ShowText BOOL
Controls the visibility of the text in task buttons.
If no value is provided, then the default is true.

Special States

ShowHoverState BOOL
If this command is present it enables a visual change if the mouse hovers over a button.
This command enables HoverButton settings.
See also: HoverStateDisplay
ShowPressedState BOOL
If this command is present it enables a visual change if the mouse is pressed on a button.
This command enables PressedButton settings.
UseGrouping BOOL
If this command is present tasks with the same "class" are represented by one task button only. Access the "hidden" tasks via ".select" (normally by left clicking on the task button).
UseFlashingState BOOL
If this command is set to false, then (the visual part of) flashing is deactivated.
If no value is provided, then the default is true (flashing is enabled).

Timers

UpdateInterval INT
Sets the update interval of the task buttons to check for changes.
If no value is provided, then the default is 1000 (ms).
TrackingInterval INT
Sets the timer that checks for hover events and OnLeave events.
If no value is provided, then the default is 250 (ms).
FlashInterval INT
Sets the flashing interval of the task buttons.
If no value is provided, then the default is 500 (ms).
DropDelay INT
If defined, it specifies the time in milliseconds a dragged file must hover over a task button until the task is activated (application comes to front).
If no value is provided, then the default is 0 (ms).

xTaskbar Background Setup

All xPaintTexture settings are valid for the taskbar background.

The needed xPaintTexture prefix is (taskbar-name), normally this is xTaskbar.

Example:

xTaskbarPaintingMode .singlecolor

xTaskbarColors       ff0000

OverlayTaskbar Setup

Overview

First of all, an overlay taskbar isn't a normal taskbar, it's only a plain image overlay below all the buttons. You can use an overlay taskbar for alpha map overlays, texture overlays, colorizing, etc. You can combine as many overlay taskbars as you want and they can overlap each other.

Syntax

*(taskbar-name)OverlayTaskbar COORDINATE COORDINATE DIMENSION DIMENSION STRING #[STRING] [STRING]
This is the command used to create a new overlay taskbar.
The two COORDINATE values are the X and Y positions, in that order.
The two DIMENSION values specifies the width and the height, in that order.
The first STRING value defines the "settings prefix" used for further configuration.
The STRING after # can be a, t or a combination of both. If it's set to a that means that the overlay uses an image with alpha map information. If it's set to t that means the overlay is painted on top of the task buttons. The # sign should always be present.
The last STRING is a "conditional overlay", which is detailed further down.

Settings

All xPaintTexture settings are valid for the overlay taskbar.

The needed xPaintTexture prefix is "settings prefix".

The "settings prefix" is defined in your *(taskbar-name)OverlayTaskbar line.

Conditional OverlayTaskbar

You MUST load xStatsClass-1.x before xTaskbar to use this feature!

Any "conditional text escape sequence" from xStatsClass, which returns a value can be used.

If the return value is 0 or false, then the overlay isn't painted, otherwise it is painted.

Examples:

; This would paint the overlay for the last 30 seconds of every minute.
*xTaskbarOverlayTaskbar 0 0 50% 50% Overlay # "[ifeval(time('ss'),'<=','30')]0[else]1[endif]"
; This would paint the overlay, if Winamp is stopped.

*xTaskbarOverlayTaskbar 0 0 50% 50% Overlay # "[winampstopped]"
; This would paint the overlay, if the evar $blah$ is empty.
*xTaskbarOverlayTaskbar 0 0 50% 50% Overlay # "[empty(exportedevar('blah'))]"

Examples

; This overlay will cover the entire taskbar.
*xTaskbarOverlayTaskbar 0 0 100% 100% TestOverlay #
; This overlay will cover the entire taskbar except for a 20 pixels wide area along the right side.

*xTaskbarOverlayTaskbar 0 0 -20 100% TestOverlay #
;An example with extra settings
*xTaskbarOverlayTaskbar 10 10 24 24 TestOverlay #

 
TestOverlayPaintingMode        ".image"
TestOverlayImage               "ghost.png"
TestOverlaySaturationIntensity 75

Button State Setup

Overview "Button Texture"

The "(Button Type)" in front of each setting means that every setting can be:
"Button", "NormalButton", "ActiveButton", "MinimizedButton", "FlashingButton", "HoverButton", "PressedButton", or "GroupedButton"

If you don't set any of these seven specific modifiers, the default settings will be used for all modes. (See Examples)

Examples:

; All button states gets a saturation intensity of 70%.

xTaskbarButtonSaturationIntensity 70
 
; Minimized buttons have a saturation intensity of 70%.
xTaskbarMinimizedButtonSaturationIntensity 70

Button Texture Settings

All xPaintTexture settings are valid for the task buttons background.

(Button Type) used below is a place holder and can be one of the following:

Button
Default value for all button states.
NormalButton
Normal button state.
ActiveButton
Active/Selected button state.
MinimizedButton
Minimized button state.
FlashingButton
Flashing button state.
HoverButton
Hover button state. See also: ShowHoverState.
PressedButton
Pressed button state. See also: ShowPressedState.
GroupedButton
Grouped button state. See also: UseGrouping.

The needed xPaintTexture prefix is (taskbar-name)+(Button Type).

Example:

xTaskbarHoverButtonPaintingMode .image
xTaskbarHoverButtonImage        "taskbuttonhover.bmp"

Overview "Button Icon"

The "(Button Type)" in front of each setting means that every setting can be:
<nothing>, "Normal", "Active", "Minimized", "Flashing", "Hover", "Pressed", or "Grouped"

If you don't set any of these seven specific modifiers, the default settings will be used for all modes. (See Examples)

UseHoverIconSettings BOOL
If this command is present hover icon settings are enabled, otherwise current state settings are used.
UsePressedIconSettings BOOL
If this command is present pressed icon settings are enabled, otherwise current state settings are used.
UseGroupedIconSettings BOOL
If this command is present grouped icon settings are enabled, otherwise current state settings are used.

Examples:

; All button states have a horizontal icon position of 5.
xTaskbarIconX 5
 
; Minimized buttons have a horizontal icon position of 5.

xTaskbarMinimizedIconX 5

Button Icon Settings

All xPaintIcon settings are valid for the task button icons.

(Button Type) used below is a place holder and can be one of the following:

<nothing>
Default value for all button states.
Normal
Normal button state.
Active
Active/Selected button state.
Minimized
Minimzed button state.
Flashing
Flashing button state.
Hover
Hover button state. See also: ShowHoverState and UseHoverIconSettings.
Pressed
Pressed button state. See also: ShowPressedState and UsePressedIconSettings.
Grouped
Grouped button state. See also: UseGrouping and UseGroupedIconSettings.

The needed xPaintIcon prefix is (taskbar-name)+(Button Type).

xTaskbarIconSize              32
xTaskbarIconAlphaTransparency 100

 
xTaskbarNormalIconSize              32
xTaskbarNormalIconAlphaTransparency 150

Overview "Button Font"

The "(Button Type)" in front of each setting means that every setting can be:
<nothing>, "Normal", "Active", "Minimized", "Flashing", "Hover", "Pressed", or "Grouped"

If you don't set any of these seven specific modifiers, the default settings will be used for all modes. (See Examples)

UseHoverFontSettings BOOL
If this command is present hover font settings are enabled, otherwise current state settings are used.
UsePressedFontSettings BOOL
If this command is present pressed font settings are enabled, otherwise current state settings are used.
UseGroupedFontSettings BOOL
If this command is present grouped font settings are enabled, otherwise current state settings are used.

Examples:

; All button states get a font height of 20.

xTaskbarFontHeight 20
 
; Minimized buttons get a font height of 20.
xTaskbarMinimizedFontHeight 20

Button Text Setup

You can modify the displayed text in the different button states if you load xStatsClass-1.x before xTaskbar. xStatsClass-1.x provides all text escape sequences you know from xLabel.

; Load xStatsClass before xTaskbar
 
*NetLoadModule xstatsclass-1.x
*NetLoadModule xtaskbar-2.x.x

The settings for the different button states are:

NormalButtonText STRING
ActiveButtonText STRING
MinimizedButtonText STRING
FlashingButtonText STRING
HoverButtonText STRING
PressedButtonText STRING
GroupedButtonText STRING
STRING can be any text or text escape sequence you like.
%caption% will be replaced with the default caption.
%executable% will be replaced with the full application path.
You can use "<br>" to create a multi line text in the task button.

Example:

; Displays the CPU usage of the task in the caption of the task button if the task is active.
xTaskbarActiveButtonText "[cpu(before(afterlast('%executable%', '\'), '.'))]% %caption%"

Scrolling Text

FontScroll BOOL
If this command is present the taskbar button text scrolls if it's too long to fit in the button, as long the mouse hovers over it.
FontScrollInterval INT
Sets the scrolling update interval in milliseconds.
If no value is provided, then the default is 100.
FontScrollSpeed INT
Sets the number of pixels to scroll for each update.
If no value is provided, then the default is 2.
FontScrollPad INT
Sets the the number of pixels between the start and end of the scrolling text.
If no value is provided, then the default is 10.

Button Font Settings

All xPaintText settings are valid for the task button text.

(Button Type) used below is a place holder and can be one of the following:

<nothing>
Default value for all button states.
Normal
Normal button state.
Active
Active/Selected button state.
Minimized
Minimized button state.
Flashing
Flashing button state.
Hover
Hover button state. See also: ShowHoverState and UseHoverFontSettings.
Pressed
Pressed button state. See also: ShowPressedState and UsePressedFontSettings.
Grouped
Grouped button state. See also: UseGrouping and UseGroupedFontSettings.

The needed xPaintText prefix is (taskbar-name)+(Button Type).

xTaskbarFontHeight 12
xTaskbarFontColor  002200
 
xTaskbarHoverFontHeight 14
xTaskbarHoverFontColor  009900

OverlayButton Setup

Overview

First of all, an overlay button isn't a normal task button. It's only a plain image overlay over the existing buttons. You can use overlay buttons for alpha map overlays, texture overlays, colorizing, etc. You can combine as many overlay buttons as you want and they can even overlap each other.

Syntax

*(taskbar-name)OverlayButton COORDINATE COORDINATE DIMENSION DIMENSION STRING #[STRING] [STRING]
The parameters are: x y width height settingsprefix flags conditionalescapesequence
All position and sizing options of the normal xTaskbar is available to setup the position and size of the overlay buttons.
The overlay is always relative to the current button size, so most of the time you will probably use "100%" for width and height.
settingsprefix is used for all overlay button settings. They work exactly like (taskbar-name) for normal xTaskbar settings.
flags can be a, t, or both. a specifies that the overlay uses an alpha map image. t specifies that the overlay is painted on top of the icon and text. The # must always be present, even if no flags are set.
conditionalescapesequence is detailed further down.

Settings

All xPaintTexture settings are valid for the overlay buttons.

(Button Type) used below is a place holder and can be one of the following:

Button
Default value for all button states.
NormalButton
Normal button state.
ActiveButton
Active/Selected button state.
MinimizedButton
Minimzed button state.
FlashingButton
Flashing button state.
HoverButton
Hover button state. See also: ShowHoverState.
PressedButton
Pressed button state. See also: ShowPressedState.
GroupedButton
Grouped button state. See also: UseGrouping.

The needed xPaintTexture prefix is settingsprefix+(Button Type), settingsprefix is defined in your *(taskbar-name)OverlayButton line.

Conditional OverlayButton

You must load xStatsClass-1.x before xTaskbar to use this feature!

Any "conditional text escape sequence" from xStatsClass that returns a value can be used.

If the return value is 0 or false the overlay isn't painted, otherwise it is painted.

Examples:

; This would paint the overlay for the last 30 seconds of every minute.
*xTaskbarOverlayButton 0 0 50% 50% Overlay # "[ifeval(time('ss'),'<=','30')]0[else]1[endif]"
; This would paint the overlay, if Winamp is stopped.

*xTaskbarOverlayButton 0 0 50% 50% Overlay # "[winampstopped]"
; This would paint the overlay, if the evar $blah$ is empty.
*xTaskbarOverlayButton 0 0 50% 50% Overlay # "[empty(exportedevar('blah'))]"

Examples

*xTaskbarOverlayButton 10 10 24 24 OverlayButton #
 

; The correct syntax for the overlay button settings are now:
OverlayButtonNormalButtonPaintingMode .image
OverlayButtonNormalButtonImage        "ghost_n.png"
OverlayButtonActiveButtonPaintingMode .image
OverlayButtonActiveButtonImage        "ghost_a.png"

For a complete and automatically adapted overlay use for instance:

*xTaskbarOverlayButton 0 0 100% 100% OverlayButton #

For a 20 pixel border on the right side without overlay:

*xTaskbarOverlayButton 0 0 -20 100% OverlayButton #

This would display an overlay button that is six pixels bigger than the normal button ("Glow Effect")

*xTaskbarOverlayButton ~6 ~6 100%+12 100%+12 testoverlay #a

Bang Commands

Remember that all values in between [ and ] are optional. This means that if you didn't specify more than one taskbar you never need to specify (taskbar-name).

(taskbar-name) must naturally be replaced with the actual name of the taskbar you want to be affected.

The exact purpose of every Bang command should be quite obvious.

!xTaskbarAlwaysOnTop [STRING] STRING
The parameters are: (taskbar-name) state
state can be:
true or on
Makes the taskbar "always on top", it stays above all application windows.
toggle or switch
Switches the taskbar back and forth between the always on top and pinned to desktop states.
false or off
Pins the taskbar to the desktop so that it stays below all application windows. This the default state and is the opposite of always on top.
!xTaskbarCreate [STRING]
The parameter is: (taskbar-name)
Create a taskbar manually.
!xTaskbarDestroy [STRING]
The parameter is: (taskbar-name)
Destroys a taskbar.
!xTaskbarDisplay [STRING] STRING
The parameters are: (taskbar-name) displaystates
Sets the currently displayed states.
See Display for possible values for displaystates
!xTaskbarLSBoxHook STRING
The parameter is: (taskbar-name)
LoadInBox must be set to hook xTaskbar in another module.
Caution: Do not call this Bang command manually. It is called by the parent window to hook xTaskbar.
!xTaskbarMove [STRING] COORDINATE COORDINATE [INT] [INT]
The parameters are: (taskbar-name) x y steps time
Moves the taskbar. 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.
!xTaskbarMoveBy [STRING] INT INT [INT] [INT]
The parameters are: (taskbar-name) x y steps time
Moves the taskbar relative to its current positioning. The move will be animated if both steps and time are defined.
Negative values for x and/or y moves the taskbar to left/top, positive to 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.
!xTaskbarResize [STRING] DIMENSION DIMENSION [INT] [INT]
The parameters are: (taskbar-name) width height steps time
Resizes the taskbar. 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.
!xTaskbarResizeBy [STRING] INT INT [INT] [INT]
The parameters are: (taskbar-name) width height steps time
Resizes the taskbar relative to its current size. The resize will be animated if both steps and time are defined.
If width and/or height is negative the taskbar is shrunken width and/or height pixels. If they are positive the taskbar is incresed in size.
steps are the number of animation steps and time sets the pause time between two steps in milliseconds. Maximum pause time is 50ms.
!xTaskbarReposition [STRING] COORDINATE COORDINATE DIMENSION DIMENSION [INT] [INT]
The parameters are: (taskbar-name) x y width height steps time
Works like !xTaskbarMove and !xTaskbarResize combined.
!xTaskbarRepositionBy [STRING] INT INT INT INT [INT] [INT]
The parameters are: (taskbar-name) x y width height steps time
Works like !xTaskbarMoveBy and !xTaskbarResizeBy combined.
!xTaskbarScrollButtons [TASKBARNAME] [STRING] [INT]
The parameters are: (taskbar-name) direction amount
If xTaskbarButtonMaxCount is set, you can scroll through the buttons with this Bang command.
direction can be "next" or "prev". Default is "next".
amount controls how many task buttons to scroll. Default is 1.
!xTaskbarSetAlpha [STRING] INT [INT] [INT]
The parameters are: (taskbar-name) transparency steps time
You can set the alpha transparency on the fly with this Bang command. The transparency change will be animated if steps and time are both defined.
steps are the fade steps and time is the pause between two steps in milliseconds.
!xTaskbarShow [STRING]
The parameter is: (taskbar-name)
Shows the taskbar, making it visible.
!xTaskbarHide [STRING]
The parameter is: (taskbar-name)
Hides the taskbar, making it invisible.
!xTaskbarToggle [STRING]
The parameter is: (taskbar-name)
Switches the taskbar back and forth between the visible and invisible state.
!xTaskbarSwitch [STRING] [STRING]
The parameters are: (taskbar-name) direction
direction can be "next" or "prev"
Switches to "next" or "prev"ious task in the taskbar.
!xTaskbarRefresh [STRING] STRING STRING
The parameters are: (taskbar-name) setting newvalue
Updates one of the taskbar settings. You can change every taskbar setting with this Bang command. The change is only temporary and is only effective until the next !recycle.

Examples:

!xTaskbarRefresh xTaskbarImage        new_image.png ; Changes the background image
!xTaskbarRefresh xTaskbarShowTooltips true          ; Take care to always use two parameters

Bangs applied to all applications

!xTaskbarMinimizeAll
Minimizes all applications in xTaskbar, as well as most other visible application windows.
!xTaskbarRestoreAll
Restores all applications in xTaskbar, but no other application windows.
!xTaskbarCascadeAll
Cascades all windows.
!xTaskbarTileAll
Tiles all windows.

Events

Taskbar Button Events

ActionsOnButtonDown BOOL
This command controls when actions should fire.
If this command is present, then the events fire on ButtonDown.
Default is to fire on ButtonUp.
OnLeftClickButton STRING
STRING can be .select, .menu, .close, .ontop or .none.
Sets an action to perform when the user left clicks a task button.
If no value is provided, then the default is .select.
OnRightClickButton STRING
STRING can be .select, .menu, .close, .ontop or .none.
Sets an action to perform, when the user right clicks a task button.
If no value is provided, then the default is .menu.
OnMiddleClickButton STRING
STRING can be .select, .menu, .close, .ontop or .none.
Sets an action to perform, when the user middle clicks a task button.
If no value is provided, then the default is .none.
OnSelect ACTION
If a task button is selected (clicked in the taskbar, or selected in a group menu), the given ACTION is executed.

Taskbar Events

OnEnter ACTION
Sets an action to perform, when the mouse cursor enters the taskbar.
OnLeave ACTION
Sets an action to perform, when the mouse cursor leaves the taskbar.
OnLeftClickDown ACTION
Sets an action to perform, when the user presses the left mousebutton down on the taskbar.
OnLeftClickUp ACTION
Sets an action to perform, when the user releases the left mousebutton on the taskbar.
OnMiddleClickDown ACTION
Sets an action to perform, when the user presses the middle mousebutton down on the taskbar.
OnMiddleClickUp ACTION
Sets an action to perform, when the user releases the middle mousebutton on the taskbar.
OnRightClickDown ACTION
Sets an action to perform, when the user presses the right mousebutton down on the taskbar.
OnRightClickUp ACTION
Sets an action to perform, when the user releases the right mouse button on the taskbar.
OnWheelDown ACTION
Sets an action to perform, when the mouse wheel scrolls down while the mouse cursor hovers over the taskbar.
See also: ...FocusOnEnter
OnWheelUp ACTION
Sets an action to perform, when the mouse wheel scrolls up while the mouse cursor hovers over the taskbar.
See also: ...FocusOnEnter
OnResize ACTION
Sets an action to perform, when the taskbar has changed its size.
OnMove ACTION
Sets an action to perform, when the taskbar has changed its position (executed after the move!).
OnAdd ACTION
Sets an action to perform, when a task has been added.
OnRemove ACTION
Sets an action to perform, when a task has been removed.
OnLineAdd ACTION
Sets an action to perform, when a line has been added.
OnLineRemove ACTION
Sets an action to perform, when a line has been removed.
BecomesFilled ACTION
Same as HideIfEmpty just with the difference that the themer can decide what should happen when the first taskbutton is shown.
BecomesEmpty ACTION
Same as HideIfEmpty just with the difference that the themer can decide what should happen when the last taskbutton is hides.
OnFlash ACTION
Sets an action to perform, when a flashing task starts flashing.

Exported Variables

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 xTaskbar has not yet added them, causing LiteStep to think the variables are undefined.

Only useful if used in handtyped Bang commands (like in LSXCommand for example) or if you use it in mzscripts or with xLabel's special !ParseEvars Bang command.

To use $evars$ in Bang commands that contain the "current" value, use the escape code %# and prefix the Bang command with the !ParseEvars Bang command. $xTaskbarcurrentwidth$ becomes %#xTaskbarcurrentwidth%# and so on.

Example:

xTaskbarOnDoubleClick !ParseEvars !vTrayMove -%#vTrayCurrentWidth%# -30
$(taskbar-name)CurrentHWND$
Exports the current HWND of the xTaskbar window as an INT value. You can use it to directly access the xTaskbar via SendMessage.
$(taskbar-name)CurrentX$
The current horizontal position of the taskbar.
$(taskbar-name)CurrentY$
The current vertical position of the taskbar.
$(taskbar-name)CurrentWidth$
The current width of the taskbar.
$(taskbar-name)CurrentHeight$
The current height of the taskbar.
$(taskbar-name)CurrentButtonCount$
The current count of displayed buttons in the taskbar.
$(taskbar-name)CurrentButtonWidth$
The current width of the buttons in the taskbar.
$(taskbar-name)CurrentButtonHeight$
The current height of the buttons in the taskbar.
$(taskbar-name)CurrentLines$
The current lines/rows of the taskbar.
$(taskbar-name)HoverTask$
The current task title under the mouse, if the mouse is actually over one of the task buttons, otherwise empty.

Special Features

Wildcards

The following settings all support the use of wildcards in their STRING parameters.

The wildcards works as follows:

*
Matches any sequence of characters (zero or more)
?
Matches any character
[SET]
Matches any character in the specified set. [!SET] or [^SET] matches any character not in the specified set.
A set is composed of characters or ranges.
A range looks like character hyphen character (as in 0-9 or A-Z).

[0-9a-zA-Z_] is the minimal set of characters allowed in the pattern construct. Other characters are allowed (i.e. 8 bit characters), if your system supports them.

To suppress the special syntactic significance of any of '[]*?!^-', and match the character exactly, precede it with a '\'.

Configuration Settings

*xTaskbar STRING
The parameter is: (taskbar-name)
Defines your own taskbar name. (Or for having more than one taskbar.)
If you only need one taskbar, you do not need to set this. (See Examples)

Examples:

Settings without a custom taskbar name (90% of the users will use xTaskbar this way.):

xTaskbarX 100

xTaskbarY -20

Settings with a custom taskbar name, in this case "Task":

*xTaskbar Task
TaskX 100
TaskY -20
*xTaskbarUpdateIcon STRING
The parameter is: substring
All applications whose "classname" or "windowtext" matches substring, will update their task icon once every UpdateInterval. substring can contain wildcards. Normally task icons are only updated if something else changes on the taskbar that causes an update.
This is usefull for tasks with dynamic icons, like some IM and IRC programs etc.
*xTaskbarAdd STRING
The parameter is: substring
All applications whose "classname" or "windowtext" match substring will be shown in the taskbar(s). All other applications are hidden. substring can contain wildcards.

Example:

; All applications that have the string "free" somewhere in 
; their classname or windowtext gets a button in the taskbar.
*xTaskbarAdd "*free*"
*xTaskbarRemove STRING
The parameter is: substring
All applications whose "classname" or "windowtext" matches substring will not be shown in any taskbar. substring may contain wildcards.

Example:

; All applications that have the string "free" somewhere in 
; their classname or windowtext will be hidden in the taskbars.
*xTaskbarRemove "*free*"
*xTaskbarIcon STRING STRING
The parameters are: substring path
This command allows you to set custom task icons.
All applications whose "classname" or "windowtext" matches substring gets the icon from the chosen (icon-)file in all taskbars. *xTaskbarIcon supports icon extraction based on icon index number.
path needs to be a full path.

Example:

; All applications that have the string "free" somewhere in 

; their classname or windowtext will get the eighth icon of 
; explorer.exe, which in this case is an alert icon.
*xTaskbarIcon "*free*" "c:\windows\explorer.exe,8"

Examples

Main Layout Examples

Common settings

First the standard settings, which are common to all the examples in the "Main Layout Examples" section:

xTaskbarPaintingMode                .multicolor
xTaskbarBorderMethod                .etched
xTaskbarButtonPaintingMode          .multicolor
xTaskbarButtonBorderMethod          .raised

xTaskbarActiveButtonBorderMethod    .sunken
xTaskbarMinimizedButtonBorderMethod .bump
 
xTaskbarX      20
xTaskbarY      20
xTaskbarWidth  $resolutionx-40$ ;(remove this setting if another value is used below!)

xTaskbarHeight 32               ;(remove this setting if another value is used below!)
 
xTaskbarTopBorder    4
xTaskbarBottomBorder 4
xTaskbarLeftBorder   10
xTaskbarRightBorder  10

 
xTaskbarButtonXSpacing 4
xTaskbarButtonYSpacing 2
 
xTaskbarButtonMaxWidth 200
 
xTaskbarFontLeftBorder 24
 
xTaskbarIconY 4

Normal single-line taskbar

Guess what, you only need the standard settings :)

Taskbar with two lines horizontally filled and a vertical wrap with the sixth button:

Use the common settings with the following changes/additions:

xTaskbarHeight    58 ;(we should start bigger due to second line)
xTaskbarLines     2
xTaskbarWrapCount 5  ;(technically you don't need this since the default is also 5)

Taskbar with two lines vertically filled and a horizontal wrap

Use the common settings with the following changes/additions:

xTaskbarHeight    58        ;(we should start bigger due to second line)
xTaskbarLayout    .vertical

xTaskbarLines     2
xTaskbarWrapCount 2

Single-line taskbar that grows vertically on wraping

Use the common settings with the following changes/additions:

xTaskbarWrapCount    4

xTaskbarOnLineAdd    !xTaskbarResizeBy 0 26
xTaskbarOnLineEemove !xTaskbarResizeBy 0 -26

Single-line taskbar that grows/shrinks with each added/removed button

Use the common settings with the following changes/additions:

xTaskbarWidth    0                        ;(we should start with zero, cause of no buttons)
xTaskbarOnAdd    !xTaskbarresizeby 200 0  ;(our task buttons are 200px wide)

xTaskbarOnRemove !xTaskbarresizeby -200 0 ;(our task buttons are 200px wide)

For all layouts you can define the direction in which new task buttons are added and the direction in which it wraps with the according settings.

The above five examples should give you an idea as to how you create your desired taskbar layout.

Multiple Taskbars

A little example that shows two xTaskbars and the use of xTaskbarDisplay:

*xTaskbar tbleft
*xTaskbar tbright
 

tbleftX                  2
tbleftY                  2
tbleftWidth              152
tbleftHeight             $resolutiony/2$
tbleftLayout             .vertical

tbleftDisplay            "normal+minimized"
tbleftPaintingMode       .multicolor
tbleftColors             c0c0c0 000000
tbleftBevels             1
tbleftButtonPaintingMode .multicolor

tbleftButtonMaxHeight    24
tbleftLeftBorder         2
tbleftRightBorder        2
tbleftTopBorder          2
tbleftBottomBorder       2
tbleftFontLeftBorder     20

tbleftIconX              2
 
tbrightX                  154
tbrightY                  2
tbrightWidth              152
tbrightHeight             24
tbrightDisplay            "active"

tbrightPaintingMode       .multicolor
tbrightButtonPaintingMode .multicolor
tbrightLeftBorder         2
tbrightRightBorder        2
tbrightTopBorder          2
tbrightBottomBorder       2

tbrightFontLeftBorder     20
tbrightIconX              2