#lang scribble/manual

@(require (for-label racket/base
                     racket/class
                     racket/gui/base
                     racket-tray))

@title{Racket Tray}
@author{hnmdijkema}

@defmodule[racket-tray]

Racket Tray provides a small system-tray API. Version 0.1 supports Windows.
The Windows implementation uses the native handle of an existing Racket GUI
top-level window and does not require an additional native library.

@defproc[(mk-tray [frame (is-a?/c top-level-window<%>)]
                  [icon-file path-string?]
                  [on-click-cb (or/c #f (-> any))])
         any/c]{
Creates a tray icon associated with @racket[frame]. @racket[icon-file] can be
a Windows @tt{.ico} file or a @tt{.png} file. PNG alpha transparency is
preserved. When the tray icon is activated, @racket[on-click-cb] is queued in
the eventspace of @racket[frame]. The returned value is passed to the other
procedures in this library.
}

@defproc[(tray-close [tray any/c]) void?]{
Removes the tray icon and releases the Windows resources associated with it.
}

@defproc[(tray-set-icon! [tray any/c]
                         [icon-file path-string?]) void?]{
Replaces the icon of @racket[tray] with the icon loaded from
@racket[icon-file]. Both @tt{.ico} and @tt{.png} files are accepted.
}

@defproc[(tray-set-menu! [tray any/c]
                         [menu any/c]) void?]{
Sets the context menu for @racket[tray]. @racket[menu] can be a
@racket[popup-menu%], @racket[#f], or a list. A list entry of the form
@racket[(list label callback)] creates an item, while @racket['separator] or
@racket[#f] creates a separator. Each callback is a zero-argument procedure.
}