#lang scribble/manual

@(require racket/base
          racket/class
          scribble/core
          (for-label racket/base
                     racket/string
                     racket/class
                     racket/file))

@;          "../private/wv-context.rkt")

@title{wv-context}
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]

@defmodule[wv-context]

@section{Overview}

The library is organized around two main concepts: contexts and windows.

A context represents the shared runtime environment for one or more webview
windows. It owns the underlying webview context, provides the base URL used by
those windows, and gives access to persistent settings through
@racketmodname[wv-settings].

This module exports the @racket[wv-context%] class.

@defclass[wv-context% object% ()]{

Represents a webview context.

A @racket[wv-context%] object is a thin class-based wrapper around the
higher-level context support provided by @racketmodname[racket-webview]. It
creates and stores a @racket[wv-context] value internally and provides methods
to access that value, its base URL, and a settings object.

@defconstructor[([base-path path-string?]
                 [file-getter procedure?
                              (webview-standard-file-getter base-path)]
                 [context-js procedure?
                             (λ () "")]
                 [boilerplate-js string?
                                 (webview-default-boilerplate-js context-js)]
                 [ini any/c
                      (error "You need to provide a 'ini' file settings interface for settings, e.g. simple-ini/class")])]{

Creates a new context object.

The constructor accepts the following initialization fields.

@itemlist[#:style 'compact
 @item{@racket[base-path] is the base path used by the default file getter.}
 @item{@racket[file-getter] is the procedure used to resolve files for the
       local web server. Its default value is
       @racket[(webview-standard-file-getter base-path)].}
 @item{@racket[context-js] is a procedure producing additional JavaScript for
       the context. Its default value is @racket[(λ () "")].}
 @item{@racket[boilerplate-js] is the JavaScript boilerplate installed into the
       underlying webview context. Its default value is
       @racket[(webview-default-boilerplate-js context-js)].}
 @item{@racket[ini] is the settings backend used to construct the associated
       @racket[wv-settings%] object. No default backend is provided; omitting it
       raises an error.}]

After @racket[super-new], the constructor creates the underlying
@racket[wv-context] value using @racket[webview-new-context], and then creates a
settings object using:

@racketblock[
(new wv-settings% [ini ini] [wv-context 'global])
]

The settings object is stored internally and used by the
@racket[settings] method.
}

@defmethod[(context) wv-context?]{

Returns the internal context value created by @racket[webview-new-context].

This is the underlying @racketmodname[racket-webview] context object used by
the rest of the library.
}

@defmethod[(settings [section symbol?]) wv-settings%]{

Returns a cloned settings object for @racket[section].

The method delegates to the internal @racket[wv-settings%] instance as:

@racketblock[
(send settings-obj clone section)
]

This allows per-section settings access while preserving the original settings
object stored by the context.
}

@defmethod[(base-url) string?]{

Returns the base URL of the underlying context.

The method delegates to @racket[wv-context-base-url] applied to the internal
context value.
}
}