wxRuby Documentation Home


This class represents a taskbar icon. A taskbar icon is an icon that appears in the `system tray’ and responds to mouse clicks, optionally with a tooltip above it to help provide information. The “taskbar” and, particularly, the “system tray” are concepts which do not have exact equivalents on all so the class works differently on each.

On Microsoft Windows the TaskBarIcon appears in the system tray, which, by default, is in the lower right corner of the screen. On Windows, an application may continue whilst having no open Frames but only a TaskBarIcon. Therefore, if you want to end an application with a TaskBarIcon when all its Frames are closed, you also need to destroy the icon.

On Linux, various window managers may or may not have a system tray, and so a TaskBarIcon should be an optional component of a user interface. Don’t rely on the TaskBarIcon as the only way to provide access to your program’s functions. However, the TaskBarIcon is supported on all modern versions of the leading window managers, Gnome, KDE and XFCE.

On Mac OS X the TaskBarIcon is placed in the Dock, not in the notification area in the top right of the screen. Therefore this class provides a way to present a high-resolution (128×128) icon to represent the app in the Dock. Note that there is no class in WxWidgets which supports showing an icon in the notification area; doing this is explicitly forbidden by Apple’s UI guidelines.

Derived from



Event handling

To process input from a taskbar icon, use the following event handler methods to direct input to a block that takes a TaskBarIconEvent argument. Note that not all ports are required to send these events and so it’s better to override create_popup_menu if all that the application does is that it shows a popup menu in reaction to mouse click.

evt_taskbar_move() { | event | ... } Process aEVT_TASKBAR_MOVE event.
evt_taskbar_left_down() { | event | ... } Process aEVT_TASKBAR_LEFT_DOWN event.
evt_taskbar_left_up() { | event | ... } Process aEVT_TASKBAR_LEFT_UP event.
evt_taskbar_right_down() { | event | ... } Process aEVT_TASKBAR_RIGHT_DOWN event.
evt_taskbar_right_up() { | event | ... } Process aEVT_TASKBAR_RIGHT_UP event.
evt_taskbar_left_dclick() { | event | ... } Process aEVT_TASKBAR_LEFT_DCLICK event.
evt_taskbar_right_dclick() { | event | ... } Process aEVT_TASKBAR_RIGHT_DCLICK event.




Destroys the TaskBarIcon object, removing the icon if not already removed.


Menu create_popup_menu()

This method is called by the library when the user requests popup menu (on Windows and Unix platforms, this is when the user right-clicks the icon). Override this instance method in your own subclass of TaskBarIcon in order to provide popup menu associated with the icon.

If create_popup_menu returns nil (this happens by default), no menu is shown, otherwise the menu is displayed and then deleted by the library as soon as the user dismisses it. The events can be handled by a class derived from TaskBarIcon.



Permanently disposes of the TaskBarIcon, typically at an application’s end. You may need to call this method to exit an application on Windows.


Boolean is_icon_installed()

Returns true if set_icon was called with no subsequent remove_icon.


Boolean is_ok()

Returns true if the object initialized successfully.


Boolean popup_menu(Menu menu)

Pops up a menu at the current mouse position. The events can be handled by a class derived from TaskBarIcon.


It is recommended to override create_popup_menu callback instead of calling this method from event handler, because some ports (e.g. Cocoa) may not implement PopupMenu and mouse click events at all.


Boolean remove_icon()

Removes the icon previously set with set_icon.


Boolean set_icon(Icon icon,  String tooltip)

Sets the icon, and optional tooltip text.

[This page automatically generated from the Textile source at Wed Sep 09 02:21:27 +0100 2009]