98 lines
3.5 KiB
Racket
98 lines
3.5 KiB
Racket
#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.
|