Documentation

Attach

The first step is to attach an interface to a window. The application must own the window.

tbi := new taskbarInterface(hWnd [, callbackFunction:=""])

Parameters

• hWnd, handle to the window to which the interface will apply.
• callbackFunction, a function name, func or bound func object, which will be called when a taskbar button is clicked.

About the callback function,

myCallbackFunction([n, ref])

The callback function will be called with two parameters.

• n, the clicked button's identification number, in the range 1 to 7
• ref, a reference to the button's associated interface.

Example

myGui := guiCreate()
tbi := new taskbarInterface(gui.hWnd, "myFunction") ; Attach an interface to myGui.

myFunction(buttonNumber, interfaceReference){
	; React to button presses.
}

In the subsequent, tbi will represent an object derived from the taskbarInterface class.

Methods

There are six groups of available methods,

• Button methods
• Icons
• Previews
• Progress bars
• Templates
• Misc

Button methods.

To use buttons, you need to first specify a button callback function, this function is called whenever the user clicks one of the buttons. Specify this function when you create the interface, as shown above. In the following, the number n will indicate a button number. There is a maximum of 7 buttons. Buttons have declining button number, from left to right, and are grouped around the center of bottom of the thumbnail preview.

In the image there are four buttons, button number 1 is the left-most button, followed by 2, 3 and 4. For managing buttons, use the following methods,

Showing and hiding,

showButton(n) 		; Shows button number n. Example: tbi.showButton(1)

hideButton(n) 		; Hides button n.

disableButton(n)	; Disables button n, the button becomes unclickable and grays out.

enableButton(n)		; Reenables button n if it was disabled, the button becomes clickable and regains its color.

Setting the button icon,

setButtonIcon(n,hIcon)

• n, the button number which will use the icon.
• hIcon, a handle to the icon which will be used by button n. Call queryButtonIconSize() to obtain the required size of the icon. See queryButtonIconSize() below.

Alternatively, you can define an image list, of bitmaps, from which you can specify an image to use for a button. First you add the bitmaps (the list is created on first addition), using,

[nIL:=] addToImageList(bitmap)

• bitmap, is a handle (integer) to a bitmap or a path (string) to an image, or an object on the form: bitmap:=[path,iconNumber]. Path is relative to script directory if not full.
• nIL, return value, the added image's index in the image list. The first image has index 1, second 2 and so on.

When specifying a handle, call queryButtonIconSize() to obtain the required size of the bitmap. See queryButtonIconSize() below.

setButtonImage(n,nIL) 	

• n, button number which will use the image.
• nIL, the index of the image to use as button n's image, this is the number returned by addToImageList().

To destroy the image list, call

destroyImageList()

To obtain the required icon and image sizes, call,

[sz:=] queryButtonIconSize()

• sz, return value, an array on the for, {w:width, h:height}, which are the required pixel width and height for the button icons.

Example,

sz := taskbarInterface.queryButtonIconSize()
Msgbox("The icon width must be: " sz.w  "`nThe icon height must be: " sz.h)

Add an informative tooltip.

Enable a tooltip when the mouse cursor hovers over the button for a few seconds.

setButtonToolTip(n [,text:=""])

• n, the button number.
• text, the text to display, omit to remove the tooltip.

Misc. button methods.

To make button click cause the thumbnail preview to be dismissed (closed), use

dismissPreviewOnButtonClick(n[, dismiss:=true])	

• n, the button number.
• dismiss, specify true to make button n's click dismiss the preview. Call with dismiss:=false to invoke the default behaviour, i.e, no dismiss on click.

Button backgrounds can be removed or re-added,

removeButtonBackground(n)
reAddButtonBackground(n)

• n, the button number.

The button has a background by default. (Note: the background looks more like a border.)

Toggle the interactive state of a button,

setButtonNonInteractive(n)
setButtonInteractive(n)

• n, the button number.

Similar to disableButton(n), but the button doesn't gray out. For changing or specifying the button callback function,

setButtonCallback([onButtonClickFunction:=""])

• onButtonClickFunction, function name, func or bound func object to use as callback function for button clicks. Omit paramters to remove callbacks

Icons

To display an overlay icon such as the one depicted above, call,

setOverlayIcon([hIcon:=0,text:=""])

• hIcon, the handle to an icon to be used as the overlay. This should be a small icon, measuring 16x16 pixels at 96 dpi. If an overlay icon is already applied to the taskbar button, that existing overlay is replaced. Omit the handle paramter to remove the icon.
• text, a string that provides an alt text version of the information conveyed by the overlay, for accessibility purposes.

To use a bitmap as the overlay icon, you can use LoadPictureType to load a bitmap as an icon, see LoadPictureType

Change the taskbar icon, and / or the window caption icon,

setTaskbarIcon(smallIconHandle [,bigIconHandle:=""])

• smallIconHandle, an icon handle to the window's new caption icon.
• bigIconHandle, an icon handle to the window's new taskbar icon.

The system displays the large icon in the ALT+TAB preview, and the small icon in the window caption.

Thumbnail and peek Preview

Image shows a custom thumbnail, displaying the current time (live), see the examples folder.

The thumbnail preview is the live display of a window which is shown when you hover the mouse cursor over the window's taskbar button. The peek preview is the live display of the window which is shown when you hover the mouse cursor over the thumbnail preview. The thumbnail preview is also shown in the ALT+TAB and WIN+TAB menus. You can change these preview to display the bitmap(s) of your choise,

enableCustomThumbnailPreview(bitmapOrBitmapFunc[, rate:=0, autoDeleteBitmap:=true, addBorder:=false])

• bitmapOrBitmapFunc, a bitmap handle to use as a static image in the preview, or a func object. This function should return a bitmap handle to be used as thumbnail preview for the interface's window.
• rate, the rate in ms at which the bitmap will be updated, bitmapFunc will be called every rate ms, requesting a new bitmap handle in return. Set rate:=0 if passing a bitmap as bitmapOrBitmapFunc.
• autoDeleteBitmap, set to true to let the interface dispose of the bitmap when it is finished with it.
• addBorder, set to true to draw a frame around the bitmap.

The bitmapFunc is called with three parameters, max width and height of the requested bitmap, and a reference to the interface. Example,

myBitmapFunc(w,h,ref){
	hBitmap := makeBitmap(w,h)	; Make a bitmap
	return hBitmap			; Return it to the interface, it will dispose of it unless autoDeleteBitmap:=false
}

Note: if not also providing a custom peek preview, it is recommended that you call the method disallowPeek() (see below).

To restore the preview to its default state, call

disableCustomThumbnailPreview()

For the peek preview, use

enableCustomPeekPreview(bitmapOrBitmapFunc, [rate:=0,x:="",y:="",autoDeleteBitmap:=true, addBorder:=false])

• bitmapOrBitmapFunc, same as enableCustomThumbnailPreview().
• rate, same as for enableCustomThumbnailPreview().
• x, y, offset for the bitmap.
• autoDeleteBitmap, same as for enableCustomThumbnailPreview().
• addBorder, same as for enableCustomThumbnailPreview().

If you have previously called disallowPeek(), call allowPeek() before calling enableCustomPeekPreview(). Restore the peek preview by calling,

disableCustomPeekPreview()

The default thumbnail preview shows a live preview of the entire window, this preview can be clipped to show a custom rectangle of the window,

setThumbnailClip(left:="",top:="",right:="",bottom:="")

• left, the x-coordinate of the upper-left corner of the rectangle. (x1)
• top, the y-coordinate of the upper-left corner of the rectangle. (y1)
• right, the x-coordinate of the lower-right corner of the rectangle. (x2)
• bottom, the y-coordinate of the lower-right corner of the rectangle. (y2)

When clipping the prevew, please mind DPI scaling.

Some related dwm functions for the peek preview,

disallowPeek(){	; Do not show peek preview for the window.

allowPeek(){	; Re-enable the peek preview for the window.

excludeFromPeek(){  ; Prevents a window from fading to a glass sheet when peek is invoked.

unexcludeFromPeek(){ ; Enables a window to fade into a glass sheet when peek is invoked.

Progress bar

Displays or updates a progress bar behind a taskbar icon to show the specific percentage completed of some operation. To set the amount of progress, use

setProgress([value:=0])

• value in the range (0,100). Where 0 means no progress, and 100 means full (completed) progress.

For changing the color of the progress, use,

SetProgressType([type:="Normal"])

• type, string, valid options are one of,

• Off, to remove the progress bar.

• Normal or green, for green progress bar

• Error or red, for red progress bar

• Paused, Pause or yellow, for yellow progress bar

• INDETERMINATE, from msdn: The progress indicator does not grow in size, but cycles repeatedly along the length of the taskbar button

To set the color behind taskbar icon call this method, specifing either, green, red or yellow for color, or omit parameters to restore,

setTaskbarIconColor([color:="off"])

Flashing the taskbar icon

A more configurable flash than ahk's built-in gui flash.

flashTaskbarIcon([color:="off", nFlashes:=5, flashTime:=250, offTime:=250]){

• color, the color of the flash, valid color options are green, red and yellow.
• nFlashes, the number of flashes.
• flashTime, in ms, the time the flash is showing.
• offTime, in ms, the time the flash is not showing

Uses a timer to let script run in parallel, use Sleep() if undesired. These paramters are not trivial to tweak. In particular, note that flashing to quickly, may omit the effect.

Informative tooltip.

Specifies or updates the text of the tooltip that is displayed when the mouse pointer hovers over a thumbnail preview.

setThumbnailToolTip([text:=""])

• Text, string specifying the new text to show as tooltip when mouse cursor hovers over the thumbnail preview. Omit parameters to remove the tooltip.

Templates.

For automatically attaching template interfaces to selected (WinTitle) windows when they are created.

[tn :=] makeTemplate(templateFunction [,WinTitle:="",excludeWinTitle:=""])

• templateFunction, this function is called when a new window, matching WinTitle and not matching excludeWinTitle, is created. The function recieves the handle (hWnd) to the new window, and defines an interface for it.
• WinTitle, matching criteria for qualifying a window for the template, can be an array of WinExist paramters, i.e., ["WinTitle", "WinText", "ExcludeTitle", "ExcludeText"]
• excludeWinTitle, matching criteria for disqualifying a window for the template, can also be an array of WinExist paramters.
• tn, return value, template number, the number of the template.

To remove templates, use

removeTemplate(tn)

• tn, the template number to remove, as returned by makeTemplate().

For an example of template usage, see the MsgBox example in the examples folder.

Misc.

Mostly self-explanatory,

restoreTaskbar() ; Restores the taskbar for the window. 

stopThisButtonMonitor()	; This will dismiss the button callbacks.

restartThisButtonMonitor() ; This will reenable the button click callbacks.
	
exemptFromHook() ; Exempt this interface from the hook which monitor when a window is destroyed.
	
unexemptFromHook() ; The inverse of the above.

getLastError() ; returns the last exception object.

Class methods, affects all interfaces

clearAll() ; Clear all interfaces and com

stopAllButtonMonitor() ; Disable all button message monitoring.

restartAllButtonMonitor() ; Turns on all button message monitor, deafult is on, hence no need to call if you didn't turn it off