wv tray docs

scrbl/wv-tray.scrbl

@@ -0,0 +1,99 @@
+#lang scribble/manual
+
+@(require (for-label racket/base
+                     racket/class
+                     racket/contract
+                     "../wv-tray.rkt"
+                     "../menu.rkt"))
+
+@title{Tray Icons}
+
+@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
+
+@defmodule[(file "../wv-tray.rkt")]
+
+The @racketmodname[(file "../wv-tray.rkt")] module provides the
+@racket[wv-tray%] class. A tray object represents a native system tray
+icon backed by the webview runtime.
+
+@defclass[wv-tray% object% ()]{
+
+Creates a native tray icon.
+
+@bold{Initialization fields}
+
+@itemlist[#:style 'compact
+ @item{@racket[icon] — mandatory}
+ @item{@racket[tooltip] — default @racket[""]}
+ @item{@racket[menu] — default @racket[#f]}]
+
+If a menu is provided, it is installed during initialization.
+
+@bold{Events}
+
+These methods can be overridden.
+
+@defmethod[(activated [reason symbol?]) any/c]{
+Called when the tray icon is activated. The @racket[reason] is derived
+from the native event.
+}
+
+@defmethod[(message-clicked) any/c]{
+Called when a tray message is clicked.
+}
+
+@defmethod[(menu-item-chosen [id symbol?]) any/c]{
+Called when a menu item is chosen without a registered callback.
+}
+
+@defmethod[(unhandled-event [evt hash?]) any/c]{
+Called for unhandled native events.
+}
+
+@bold{Commands}
+
+@defmethod[(show) (is-a?/c wv-tray%)]{
+Shows the tray icon and returns the tray object.
+}
+
+@defmethod[(hide) (is-a?/c wv-tray%)]{
+Hides the tray icon and returns the tray object.
+}
+
+@defmethod[(close) (is-a?/c wv-tray%)]{
+Closes the tray icon and returns the tray object.
+}
+
+@defmethod[(set-icon! [icon-file path-string?]) (is-a?/c wv-tray%)]{
+Changes the tray icon and returns the tray object.
+}
+
+@defmethod[(set-tooltip! [text string?]) (is-a?/c wv-tray%)]{
+Changes the tooltip and returns the tray object.
+}
+
+@defmethod[(show-message [title string?]
+                         [message string?])
+           (is-a?/c wv-tray%)]{
+Shows a native tray message and returns the tray object.
+}
+
+@defmethod[(set-menu! [menu-def any/c]) (is-a?/c wv-tray%)]{
+Installs a tray menu and returns the tray object.
+}
+
+@defmethod[(connect-menu! [id symbol?]
+                          [callback procedure?])
+           (is-a?/c wv-tray%)]{
+Registers a callback for a menu item and returns the tray object.
+}
+
+@defmethod[(disconnect-menu! [id symbol?]) (is-a?/c wv-tray%)]{
+Removes a menu callback and returns the tray object.
+}
+
+@defmethod[(handle) any/c]{
+Returns the native tray handle.
+}
+
+}

scrbl/wv-window.scrbl

@@ -55,6 +55,7 @@ API.
                  [settings (send wv-context settings
                                  (string->symbol (format "~a" html-path)))]
                  [title string? "Racket Webview Window"]
+                 [icon (or/c path-string? #f) #f]
                  [width (or/c exact-integer? #f) #f]
                  [height (or/c exact-integer? #f) #f]
                  [x (or/c exact-integer? #f) #f]
@@ -78,7 +79,9 @@ After construction, the class:
  @item{creates the underlying webview window}
  @item{installs the internal event handler}
  @item{sets the title}
- @item{initializes position and size from settings or defaults}]
+ @item{Applies the icon during construction when it is not @racket[#f]}
+ @item{initializes position and size from settings or defaults}
+          ]
 
 If a parent is supplied, the underlying lower-level parent window is passed to
 @racket[webview-create].
@@ -148,13 +151,6 @@ Updates the internal size and stores the new dimensions in
 @racket[settings] under @racket['width] and @racket['height].
 }
 
-@defmethod[(window-state-changed [st symbol?]) any/c]{
-
-Called when the underlying window state changes.
-
-The default implementation returns @racket[#t].
-}
-
 @defmethod[(page-loaded [oke any/c]) any/c]{
 
 Called when a @racket['page-loaded] event is received.
@@ -223,6 +219,8 @@ window.
 Opens the developer tools and returns this window.
 }
 
+@bold{Window manipulation and information}
+
 @defmethod[(move [x exact-integer?] [y exact-integer?]) (is-a?/c wv-window%)]{
 
 Moves the window and returns this window.
@@ -238,6 +236,45 @@ Resizes the window and returns this window.
 Closes the window and returns this window.
 }
 
+@defmethod[(show) (is-a?/c wv-window%)]{Shows the window.}
+@defmethod[(present) (is-a?/c wv-window%)]{Presents the window.}
+@defmethod[(hide) (is-a?/c wv-window%)]{Hides the window.}
+@defmethod[(maximize) (is-a?/c wv-window%)]{Maximizes the window.}
+@defmethod[(minimize) (is-a?/c wv-window%)]{Minimizes the window.}
+@defmethod[(show-normal) (is-a?/c wv-window%)]{Restores normal state.}
+
+
+@defmethod[(window-state) symbol?]{
+  Returns the current native window state.
+ }
+
+@defmethod[(window-state-changed [st symbol?]) any/c]{
+  Called when the underlying window state changes.
+
+  Window states following calls to @racket{show}, @racket{present}, @racket{hide}, etc.:
+  @itemlist[#:style 'compact
+   @item{@racket{'normal}}
+   @item{@racket{'hidden}}
+   @item{@racket{'minimized}}
+   @item{@racket{'maximized}}
+   @item{@racket{'maximized-active} and}
+   @item{@racket{'normal-active}}
+            ]
+  are forwarded to @racket{window-state-changed}.
+ }
+
+@defmethod[(quit) (is-a?/c wv-window%)]{Quits the webview runtime.}
+
+
+@bold{Menu's and binding elements to events}
+
+@defmethod[(popup-menu! [menu-def is-wv-menu?]
+                        [x exact-integer?]
+                        [y exact-integer?])
+           any/c]{
+Shows @racket[menu-def] as a popup menu at @racket[x], @racket[y].
+}
+
 @defmethod[(bind! [selector (or/c symbol? string?)]
                   [events (or/c symbol? list?)]
                   [callback procedure?])
@@ -269,7 +306,7 @@ internal cache.
 The returned value is the list produced by @racket[webview-unbind!].
 }
 
-           @defmethod[(set-menu! [menu is-wv-menu?])
+@defmethod[(set-menu! [menu is-wv-menu?])
             (is-a?/c wv-window%)]{
 
 Installs @racket[menu] in this window and returns this window.
@@ -305,6 +342,20 @@ chosen.
 Sets the window title.
 }
 
+@defmethod[(set-icon! [icon-file path-string?]) any/c]{
+  Sets the window icon.
+ }
+
+
+@bold{Javascript methods}
+
+See also **Javascript syntax module**
+
+@defmethod[(run-js [js string?]) any/c]{ Runs JavaScript in the window. }
+@defmethod[(call-js [js string?]) any/c]{ Calls JavaScript in the window and returns the decoded result. }
+
+@bold{File dialog methods}
+
 @defmethod[(file-dialog-done [flag symbol?]
                              [file any/c]
                              [dir any/c]