Tuesday, June 4, 2013

Displaying a Custom Message in the Notification Area using Windows PowerShell

Use Windows PowerShell to display messages in the notification area. If you couldn’t, then we’d have had no reason to put together a script like this one:

[void] [System.Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms")

$objNotifyIcon = New-Object System.Windows.Forms.NotifyIcon

$objNotifyIcon.Icon = "C:\Scripts\Forms\Folder.ico"
$objNotifyIcon.BalloonTipIcon = "Error"
$objNotifyIcon.BalloonTipText = "A file needed to complete the operation could not be found."
$objNotifyIcon.BalloonTipTitle = "File Not Found"

$objNotifyIcon.Visible = $True

We start out by using the following line of code to load an instance of the .NET Framework class System.Windows.Forms:

[void] [System.Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms")

The [void] at the beginning on this line of code simply keeps status messages from appearing on the screen when we load the System.Windows.Form class.
After loading the System.Windows.Forms class we use the New-Object cmdlet to create an instance of the System.Windows.Forms.NotifyIcon class; as you might expect, this is the .NET class that actually lets us configure and display a notification in the notification area:

$objNotifyIcon = New-Object System.Windows.Forms.NotifyIcon

Following that we need to define several properties of our notice. In particular, we need to assign values to the following items:
This is the icon that appears in the notification area. The icon must be 16 pixels high by 16 pixels wide. If you have icon-editing software you can create your own icon; if not, try searching your computer (or the Internet) for .ICO files. Just make sure you specify the full path to the icon file when assigning a value to the Icon property: $objNotifyIcon.Icon = "C:\Scripts\Forms\Folder.ico".
This is the icon that appears inside your notice (see the illustration below). You can choose between the following operating system-supplied icons: InfoWarning; and Error. In our example, we’ve set the BalloonTipIcon to Error.
The actual message to be displayed. For this particular script we’ve set the BalloonTipText to “A file needed to complete the operation could not be found.”
The title of your notice. For our example, that’s File Not Found.

Or, to put it this all a little more visually:

After setting the Visible property to True ($True), all we have to do now is call the ShowBalloonTip method and display the notice:


A couple notes about the ShowBalloonTip method. For one thing, did you notice the parameter 10000 that we passed to ShowBalloonTip? Well, in theory, that indicates the number of milliseconds that we want our notice to stay on screen before automatically disappearing. Because there are 1000 milliseconds in every second, a value of 10000 means that, theoretically, we want the message to stay onscreen for 10 seconds, and then bid everyone a hasty goodbye.

That seems simple enough. So then why do we keep saying things like “in theory” and “theoretically”? That’s because there are some outside factors that come into play here. For example, the operating system imposes minimum and maximum values when it comes to displaying items in the notification area; typically a notice must remain onscreen for at least 10 seconds but no more than 30 seconds. What does that mean? Let’s put it this way: suppose you passed ShowBalloonTip the value 300000, thinking that would keep the notice displayed for 5 minutes (300,000 milliseconds). In reality, though, it’s highly unlikely that the notice will stay onscreen that long; instead, the operating system will probably dismiss it long before then. Likewise, suppose you set the parameter value to 1, thinking that you’ll show the notice for just 1 millisecond and then take it away. That’s not going to work, either: Windows will make sure that the notice is displayed for the minimum-allowed time before disposing of it.

On top of that, these times also depend on the amount of activity taking place on the computer. If the system appears to be idle then the countdown won’t begin until the computer actually does something. In that case, the notice could end up being displayed for hours.

Note. Of course, you can always dismiss a notice simply by clicking on it. Speaking of which, we should point out that any time a notification times-out the message will disappear, but the icon will remain in the notification area, at least until you pass the mouse through that area. However, if you dismiss a notice by clicking on it the icon will also disappear.

Regardless of how long it actually stays on screen, your notification will look something like this:

Another thing to keep in mind here is that your script will continue to run while the notice is displayed; the script won’t automatically pause and wait for the notice to disappear. That shouldn’t cause any problems; it’s just something you should be aware of.

No comments:

Post a Comment