#lang scribble/manual

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

@defmodule[wv-settings]

@title{Object-Oriented Interface: @racket[wv-settings%]}
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]

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

An OO wrapper around a settings backend implementing the
@racket[simple-ini/class] interface.

A @racket[wv-settings%] object represents a view on one settings section.
The supplied @racket[wv-context] value is used as the section identifier for
context-local settings.

The class delegates all actual storage operations to the supplied
@racket[ini] object.

@defconstructor[([ini object?]
                 [wv-context any/c])]{
Creates a new settings object.

The @racket[ini] argument is the backing settings object.

The @racket[wv-context] argument is used as the section identifier for
context-local settings.

The class assumes that @racket[ini] supports methods compatible with:

@itemlist[#:style 'compact
 @item{@racket[(send ini get section key)]}
 @item{@racket[(send ini get section key default)]}
 @item{@racket[(send ini set! section key value)]}
]

In typical use, @racket[ini] is an instance of a class from
@racket[simple-ini/class].
}

@defmethod*[([(get [key any/c]) any/c]
             [(get [key any/c] [default-value any/c]) any/c])]{
Returns the value associated with @racket[key] in the current section.

Without a default value, this method delegates to:

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

With a default value, it delegates to:

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

@defmethod*[([(set! [key any/c] [value any/c]) this])]{
Stores @racket[value] under @racket[key] in the current section.

This method delegates to:

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

@defmethod*[([(get/global [key any/c]) any/c]
             [(get/global [key any/c] [default-value any/c]) any/c])]{
Returns the value associated with @racket[key] in the global section.

Without a default value, this method delegates to:

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

With a default value, it delegates to:

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

@defmethod*[([(set/global! [key any/c] [value any/c]) this])]{
Stores @racket[value] under @racket[key] in the global section.

This method delegates to:

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

@defmethod*[([(clone [context any/c]) (is-a?/c wv-settings%)])]{
Creates a new @racket[wv-settings%] object using the same
@racket[ini] backend but another section identifier.

This method is equivalent to:

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

It is intended to support cheap creation of per-section settings views.
}

@defmethod*[([(context) any/c])]{
Returns the section identifier associated with this settings object.
}

} ; end class