implemented

scrbl/racket-tray.scrbl

@@ -6,39 +6,92 @@
                      racket-tray))
 
 @title{Racket Tray}
-@author{hnmdijkema}
+@author{Hans Dijkema / hans@dijkewijk.nl}
 
 @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.
+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))])
+                  [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]. @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
+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.
 }
 
-@defproc[(tray-close [tray any/c]) void?]{
-Removes the tray icon and releases the Windows resources associated with it.
-}
+@section{Changing and Closing a Tray Icon}
 
 @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.
+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 an item, while @racket['separator] or
-@racket[#f] creates a separator. Each callback is a zero-argument procedure.
+@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.