PoshTaskbarItem

PoshTaskbarItem is a PowerShell module that helps you make a simple UI for your script on the Windows taskbar.

Application icons on the Windows taskbar have some useful features such as ThumbButton, ProgressIndicator and overlay icons. PoshTaskbarItem enables you to utilize these taskbar item features from PowerShell without caring about WPF programming. It will help you create simple and easily accessible GUIs for your utility scripts.

Quick Example

The following code creates a taskbar icon showing a decreasing counter as an overlay badge. Clicking the icon resets the counter. This example is small but it should show a general idea of the module.

$counter = 10
$ti = New-TaskbarItem -Title 'Countdown' -OnClicked {
    $script:counter = 10
    UpdateUi
}

Set-TaskbarItemTimerFunction $ti -IntervalInMillisecond 1000 {
    $script:counter = [Math]::Max($script:counter-1, 0)
    UpdateUi
}

function UpdateUi
{
    Set-TaskbarItemOverlayBadge $ti -Text $script:counter -BackgroundColor 'LightSeaGreen'
    Set-TaskbarItemProgressIndicator $ti -Progress ($script:counter/10) -State Paused
}

Show-TaskbarItem $ti

Requirements

This module has been tested on:

• Windows 10 and 11
• Windows PowerShell 5.1 and PowerShell 7.2

Installation

PoshTaskbarItem is available on the PowerShell Gallery. You can install the module with the following command:

Install-Module -Name PoshTaskbarItem -Scope CurrentUser

Typical Code Structure

The following will be the typical code structure of a script that uses this module:

1. Create a TaskbarItem.
   • New-TaskbarItem
2. Set static information of the TaskbarItem including the TimerFunction.
   • Set-TaskbarItemTimerFunction
   • Add-TaskbarItemJumpTask
   • Add-TaskbarItemThumbButton
3. In the script block you specified to the TimerFunction or OnClicked callbacks, update the information of the TaskbarItem.
   • Set-TaskbarItemDescription
   • Set-TaskbarItemOverlayBadge
   • Set-TaskbarItemOverlayIcon
   • Set-TaskbarItemProgressIndicator
4. Show the TaskbarItem. The function does not return until the window is closed so everything needs to be handled in the callbacks.
   • Show-TaskbarItem

Features

In the following code examples, it is assumed that the TaskbarItem object is stored in the variable $ti.

$ti = New-TaskbarItem

Description

Set-TaskbarItemDescription $ti 'Description is shown here'

Description is a text displayed on top of the taskbar preview window. It is shown by a mouse over.

Thumb Button

$thumbButton = New-TaskbarItemThumbButton -Description 'Increment Badge Counter' -IconResourcePath 'imageres.dll' -IconResourceIndex 101 -OnClicked {
    Write-Host 'Clicked.'
}
Add-TaskbarItemThumbButton $ti $thumbButton

ThumbButtons are the buttons displayed at the bottom of the preview window. You can add maximum 7 ThumbButtons to a TaskbarItem.

Overlay Badge

Set-TaskbarItemOverlayBadge $ti -Text '2'

OverlayBadge is a text badge displayed on the taskbar icon. The badge size and the font size are changeable by parameters but 2 characters might be the maximum considering the space.

Overlay Icon

Set-TaskbarItemOverlayIcon $ti -IconResourcePath imageres.dll -IconResourceIndex 79

Instead of a text badge, you can also show an image as an overlay icon.

Icon Flashing

Start-TaskbarItemFlashing $ti -Count 3
# ...
Stop-TaskbarItemFlashing $ti

You can flash the taskbar icon to get more attention of the user.

Jump Task

$jumpTask = New-TaskbarItemJumpTask -Title 'Jump Task 1' -Description 'Description is shown here' -IconResourcePath 'notepad.exe' -ApplicationPath 'notepad.exe' -Arguments 'test.txt'
Add-TaskbarItemJumpTask $ti $jumpTask

JumpTask is a shortcut to an application that is shown in the context menu of the taskbar icon. Windows remembers the JumpTask settings so if the app is pined on the taskbar, it can also be executed when the app is not running.

Changing Application Icons

If you run a script that uses PoshTaskbarItem, the PowerShell icon is shown on the taskbar by default. If you want to assign a new icon to your script, you have to create a shortcut that runs your script. You would also want to hide the PowerShell console so the command to create the shortcut will be like this:

New-TaskbarItemShortcut -Path 'D:\YourApp.lnk' -IconResourcePath 'imageres.dll' -IconResourceIndex 144 -TargetPath 'powershell.exe' -Arguments '-ExecutionPolicy Bypass -WindowStyle Hidden -File D:\YourScript.ps1' -WindowStyle Minimized

IconResourcePath

Some of the functions take IconResourcePath and IconResourceIndex parameters to specify icon images. For IconResourcePath, you can use a relative path from the current directory, a relative path from $env:PATH or full path to a file that contains icon resources. The supported files are .dll, .exe, .ico and image files (.png, .bmp, .tif, .gif and .jpg). Depending on the function, image files are converted to .ico files which are placed next to the original image files. IconResourceIndex is a zero-based index value that specifies which one to use in case the resource file has multiple icon resources.

On Windows 10 or 11, imageres.dll or shell32.dll has a lot of useful icons. You can see what kind of icons they have from the 'Change Icon' button in the shortcut property.

Timer Function

Show-TaskbarItem function does not return until the taskbar item window is closed so if you need to do something periodically while the window is open, you have to use the Timer Function.

Set-TaskbarItemTimerFunction $ti -IntervalInMillisecond 1000 {
    Write-Host 'Tick'
}

The Timer Function is called on the UI thread with the interval time specified by a parameter. The function is not guaranteed to be executed exactly when the time interval occurs, but it is guaranteed to not be executed before the time interval occurs. Because it is called on the UI thread, it should not do anything that takes long time to complete.

Help and more Examples

Get-Command can list all the available functions in the module:

Get-Command -Module PoshTaskbarItem

To get the detailed help of a function, please try:

Get-Help Add-TaskbarItemJumpTask -Full

For more code examples, please see the scripts under Examples folder and an example project, Posh Work Time Tracker.