#lang scribble/manual

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

@title{Racket Tray}
@author{Hans Dijkema / hans@dijkewijk.nl}

@defmodule[racket-tray]

Racket Tray provides a small API for adding a system tray icon to a Racket GUI
application. Version 0.1.1 supports Windows. The Windows implementation uses
the native @tt{HWND} of an existing Racket top-level window and requires no
additional native library.

@section{Creating a Tray Icon}

@defproc[(mk-tray [frame (is-a?/c top-level-window<%>)]
                  [icon-file path-string?]
                  [on-click-cb (or/c #f (-> any))]
                  [#:hide-on-minimize? hide-on-minimize? boolean? #f])
         any/c]{
Creates a tray icon associated with @racket[frame]. The frame must already
have a native window handle. A @racket[frame%] or @racket[dialog%] is suitable.

@racket[icon-file] can be a Windows @tt{.ico} file or a @tt{.png} file. PNG
alpha transparency is preserved when the image is converted to a native
Windows icon.

When the tray icon is activated, @racket[on-click-cb] is queued in the
eventspace of @racket[frame]. Use @racket[#f] when no activation callback is
needed.

When @racket[hide-on-minimize?] is true, minimizing the associated window
hides it after Windows reports @tt{SIZE_MINIMIZED}. Hiding the window removes
it from the taskbar while leaving its native handle alive for the tray icon.
When showing such a window again, an application can restore it with
@racket[(send frame iconize #f)] when @racket[(send frame is-iconized?)] is
true.

The returned value represents the tray icon and is accepted by the other
procedures in this library.
}

@section{Changing and Closing a Tray Icon}

@defproc[(tray-set-icon! [tray any/c]
                         [icon-file path-string?]) void?]{
Replaces the image of @racket[tray]. 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 a menu item. @racket['separator] and
@racket[#f] create a separator. Each callback must accept zero arguments.
}

@defproc[(tray-close [tray any/c]) void?]{
Removes @racket[tray], detaches its native window hook, and releases the
Windows icon resources owned by the tray object. Calling this procedure does
not close the associated Racket window.
}

@section{Closing a Window to the Tray}

Racket already provides @method[frame% on-close] for handling the close button
of a frame. A tray application normally overrides it and hides the frame:

@racketblock[
(define tray-frame%
  (class frame%
    (super-new)

    (define/override (on-close)
      (send this show #f))))
]

This is intentionally separate from @racket[#:hide-on-minimize?]. Closing a
window is already represented by a public Racket GUI callback, while Windows
does not expose minimizing through a corresponding public Racket callback.

@section{Example}

The package contains @filepath{examples/simple.rkt}. It demonstrates hiding a
frame on both minimize and close, restoring it from the tray, and terminating
the application only through the tray menu.

@section{Platform Support}

Version 0.1.1 implements Windows. Requiring @racketmodname[racket-tray] is safe
on other operating systems, but calling its tray operations reports that the
platform is not yet supported.