#lang scribble/manual

@(require racket/base
          racket/class
          scribble/core
          (for-label racket/base
                     racket/class
                     "../wv-dialog.rkt"
                     "../wv-window.rkt"))

@title[#:tag "wv-dialog"]{wv-dialog}
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]

@defmodule[racket-webview/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. Closing a dialog does not quit the application by default.

@section[#:tag "wv-dialog-overview"]{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]. A dialog also changes the inherited @racket[quit-on-close] default to @racket[#f].

@section[#:tag "wv-dialog-class-wv-dialog"]{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[([quit-on-close any/c #f])]{

Creates a dialog window.

The inherited @racket[quit-on-close] initialization argument defaults to
@racket[#f] for dialogs. Closing a dialog therefore closes only that dialog and
does not release @racket[webview-wait-for-quit]. Pass @racket[#t] explicitly
only when closing this dialog should terminate the application.
}

@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%].
}
}