#lang scribble/manual

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

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

@defmodule[rgba]

RGBA color support used by the webview library.

This module exports a transparent @racket[rgba] structure together with
predicates and conversion procedures for working with CSS-style color values.

@section{Overview}

An @racket[rgba] value represents a color using red, green, blue, and alpha
components.

The module provides:

@itemlist[#:style 'compact
 @item{the @racket[rgba] structure type}
 @item{predicates for validating component values}
 @item{conversion from strings to @racket[rgba] values}
 @item{conversion from @racket[rgba] values to CSS color strings}]

The intended external representation is the CSS form:

@racketblock[
"rgba(r,g,b,a)"
]

@section{Predicates}

@defproc[(rgba/color? [v any/c]) boolean?]{

Recognizes valid red, green, and blue component values.

A valid color component is an exact integer in the range from @racket[0] to
@racket[255], inclusive.
}

@defproc[(rgba/alpha? [v any/c]) boolean?]{

Recognizes valid alpha component values.

A valid alpha component is a real number in the range from @racket[0] to
@racket[1], inclusive.
}

@section{Structure Type}

@defstruct*[rgba ([r rgba/color?]
                  [g rgba/color?]
                  [b rgba/color?]
                  [a rgba/alpha?])]{

Represents one RGBA color value.

The fields @racket[r], @racket[g], and @racket[b] are the red, green, and blue
components. The field @racket[a] is the alpha component.

The structure is transparent.
}

@section{Conversion}

@defproc[(rgba->string [c rgba?]) string?]{

Converts @racket[c] to a CSS color string.

The result has the form:

@racketblock[
"rgba(r,g,b,a)"
]
}

@defproc[(string->rgba [s string?]) (or/c rgba? #f)]{

Attempts to parse @racket[s] as a CSS RGBA color string.

If parsing succeeds, the result is an @racket[rgba] value. If parsing fails, the
result is @racket[#f].

The accepted input format is the one produced by @racket[rgba->string], namely:

@racketblock[
"rgba(r,g,b,a)"
]
}