#lang scribble/manual

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

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

@defmodule[wv-settings]

Settings wrapper used by the webview library.

This module exports the @racket[wv-settings%] class, which provides a small
object-oriented interface over an @racket[ini] settings backend. Settings are
accessed relative to a context.

@section{Overview}

A @racket[wv-settings%] object combines:

@itemlist[#:style 'compact
 @item{an @racket[ini] settings object}
 @item{a @racket[symbol] identifying the settings context}]

Keys used in this class are symbols.

@section{Class: wv-settings%}

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

Wraps an @racket[ini] settings object for one context.

The class delegates all reads and writes to the supplied @racket[ini] object.

@defconstructor[([ini (is-a?/c ini%)]
                 [wv-context symbol?])]{

Creates a settings wrapper.

@racket[ini] must provide compatible @racket[get] and @racket[set!] methods.
@racket[wv-context] is the context symbol used for contextual settings access.
}

@defmethod[(get [key symbol?] [default-value any/c] ...) any/c]{

Returns the value associated with @racket[key] in the current context.

If no default value is supplied, the call delegates to:

@racketblock[
(send ini get wv-context key)
]

If a default value is supplied, only the first extra argument is used, and the
call delegates to:

@racketblock[
(send ini get wv-context key default)
]
}

@defmethod[(set! [key symbol?] [value any/c]) any/c]{

Stores @racket[value] under @racket[key] in the current context.

Delegates to:

@racketblock[
(send ini set! wv-context key value)
]
}

@defmethod[(get/global [key symbol?] [default-value any/c] ...) any/c]{

Returns the value associated with @racket[key] in the global settings section.

If no default value is supplied, the call delegates to:

@racketblock[
(send ini get 'global key)
]

If a default value is supplied, only the first extra argument is used, and the
call delegates to:

@racketblock[
(send ini get 'global key default)
]
}

@defmethod[(set/global! [key symbol?] [value any/c]) any/c]{

Stores @racket[value] under @racket[key] in the global settings section.

Delegates to:

@racketblock[
(send ini set! 'global key value)
]
}

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

Creates a new @racket[wv-settings%] object sharing the same @racket[ini]
backend but using @racket[context] as its context.
}

@defmethod[(context) symbol?]{

Returns the current context symbol.
}
}