tray-item

The class of tray-item objects. A tray-item instance is used for each item that a standalone Common Graphics application places into the system "tray", also known as the Taskbar Notification Area. This is the area at the rightmost end of the system taskbar that contains small icons with custom mouse behavior for various applications.

A Common Graphics application can add an item to the tray by calling make-instance to create a tray-item and then calling add-tray-item to add it to the tray. It may be removed later with remove-tray-item and then added again and removed any number of times. in-tray-p returns whether a tray-item is currently in the tray.

A tray-item generally needs an icon to display, which may be specified either by passing an icon handle as the :icon initarg to make-instance, or later by calling (setf tray-item-icon). An optional tooltip may also be specified either with the :tooltip initarg or by calling (setf tray-item-tooltip). A name for identifying the tray-item programmatically may be specified by passing a symbol as the :name initarg or by calling (setf name).

When the user moves the mouse over the tray icon or clicks on it, the generic function tray-item-message is called. An application may supply tray-item-message methods to handle the mouse events in a custom way.

Microsoft Windows note: to make it easy for the user to select a choice or to cancel a pop-up menu, you may want to ensure that a window from the same process has the keyboard focus, or at least that such a window is present on the screen. In Microsoft Windows, keypresses will apply to a pop-up menu only if the window that currently has the keyboard focus was created in the process that popped up the menu. Otherwise the Escape key will not dismiss the menu, and a choice cannot be made with the keyboard. Clicking the mouse outside a pop-up menu will dismiss the menu only if there is at least one currently visible (not shrunk) top-level window that was created in the process that popped up the menu.

Here is a complete (though trivial) example:

;;; Define a tray-item subclass in order to specialize a
;;; custom tray-item-message method on it.
(defclass my-tray-item (tray-item)())

(defclass my-frame (frame-window)())

(defmethod tray-item-message ((tray-item my-tray-item)
                              (window my-frame)
                              message)
  (case message
    
    ;; On a left click, select the application window.
    (#.mouse-left-down
     (select-window window)
     (set-foreground-window window))
    
    ;; On a right click, pop up a menu of background colors
    ;; for the application window.  Popping up a menu on a
    ;; down click appears not to work when the tray icon's
    ;; associated window is selected, so use an up click.
    (#.mouse-right-up
     (let* ((menu (open-menu
                   (list (make-instance 'menu-item
                           :name :yellow
                           :title "~Yellow"
                           :value yellow)
                         (make-instance 'menu-item
                           :name :green
                           :title "~Green"
                           :value green)
                         (make-instance 'menu-item
                           :name :cyan
                           :title "~Cyan"
                           :value cyan))
                   'pop-up-menu (screen *system*)))
            (color (pop-up-menu menu window)))
       (close menu)
       (when color
         (setf (background-color window) color)
         (invalidate window))))))

;;; Test the above application code.

(setq window (make-window :tray-test
               :class 'my-frame
               :title "Tray Test"))

(setq ti (make-instance 'my-tray-item
           :icon information-icon
           :tooltip "Click left or right"))

(add-tray-item ti :window window)

;; Try out the tray icon here ...

(remove-tray-item ti)

GTK Note

Tray items are not implemented on the GTK platform, where we see no way to implement them. You should use #+mswindows to conditionalize any tray-item code.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.