documentation

scrbl/wv-dialog.scrbl

@@ -0,0 +1,83 @@
+#lang scribble/manual
+
+@(require racket/base
+          racket/class
+          scribble/core
+          (for-label racket/base
+                     racket/class
+                     "../private/wv-window.rkt"))
+
+@title{wv-dialog}
+@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
+
+@defmodule[wv-dialog]
+
+Dialog-window wrapper built on top of @racket[wv-window%].
+
+This module exports the @racket[wv-dialog%] class. It is a specialized window
+class whose initial size and position are derived from its parent window.
+
+@section{Overview}
+
+A @racket[wv-dialog%] object is a @racket[wv-window%] that initializes itself as
+a dialog relative to its parent window.
+
+The class inherits the window lifecycle, event handling, navigation, and dialog
+support from @racket[wv-window%]. Its only specialization in the current source
+is the implementation of @racket[init-size].
+
+@section{Class: wv-dialog%}
+
+@defclass[wv-dialog% wv-window% ()]{
+
+Represents a dialog window centered relative to its parent window.
+
+The class inherits the fields @racket[parent], @racket[settings],
+@racket[wv-context], @racket[html-path], @racket[x], @racket[y],
+@racket[width], and @racket[height] from @racket[wv-window%].
+
+@defconstructor[()]{
+
+Creates a dialog window.
+
+The constructor does not define additional initialization arguments of its own.
+Construction is delegated to @racket[wv-window%] through @racket[super-new].
+}
+
+@defmethod[(init-size) any/c]{
+
+Initializes the dialog size and position relative to its parent window.
+
+The method reads the parent window geometry from the inherited @racket[parent]
+field:
+
+@itemlist[#:style 'compact
+ @item{@racket[x] and @racket[y] of the parent window}
+ @item{@racket[width] and @racket[height] of the parent window}]
+
+It then determines the dialog width and height from @racket[settings], using the
+keys @racket['width] and @racket['height]. If a stored value is absent, the
+constructor fields @racket[width] and @racket[height] are used if present.
+Otherwise both dimensions default to @racket[400].
+
+The dialog position is then computed so that the dialog is centered within the
+parent window:
+
+@racketblock[
+(let ((xx (/ (- pw dw) 2))
+      (yy (/ (- ph dh) 2)))
+  ...)
+]
+
+The resulting coordinates are rounded, converted to exact integers, and applied
+using:
+
+@racketblock[
+(send this move x y)
+(send this resize dw dh)
+]
+
+This method overrides the inherited @racket[init-size] implementation from
+@racket[wv-window%].
+}
+}