documentation

scrbl/rgba.scrbl

@@ -0,0 +1,96 @@
+#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)"
+]
+}