From b7bad6b2bbddafb3ba2f871ff91e20d606f359ea Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Thu, 11 Dec 2008 18:32:40 -0800
Subject: [PATCH] Metadata and docs for ui.offscreen

---
 extra/ui/offscreen/authors.txt           |  1 +
 extra/ui/offscreen/offscreen-docs.factor | 63 ++++++++++++++++++++++++
 extra/ui/offscreen/offscreen.factor      |  5 +-
 extra/ui/offscreen/summary.txt           |  1 +
 extra/ui/offscreen/tags.txt              |  3 ++
 5 files changed, 72 insertions(+), 1 deletion(-)
 create mode 100644 extra/ui/offscreen/authors.txt
 create mode 100644 extra/ui/offscreen/offscreen-docs.factor
 create mode 100644 extra/ui/offscreen/summary.txt
 create mode 100644 extra/ui/offscreen/tags.txt

diff --git a/extra/ui/offscreen/authors.txt b/extra/ui/offscreen/authors.txt
new file mode 100644
index 0000000000..f13c9c1e77
--- /dev/null
+++ b/extra/ui/offscreen/authors.txt
@@ -0,0 +1 @@
+Joe Groff
diff --git a/extra/ui/offscreen/offscreen-docs.factor b/extra/ui/offscreen/offscreen-docs.factor
new file mode 100644
index 0000000000..5d800981bf
--- /dev/null
+++ b/extra/ui/offscreen/offscreen-docs.factor
@@ -0,0 +1,63 @@
+! Copyright (C) 2008 Joe Groff.
+! See http://factorcode.org/license.txt for BSD license.
+USING: help.markup help.syntax kernel quotations ui.gadgets
+graphics.bitmap strings ui.gadgets.worlds ;
+IN: ui.offscreen
+
+HELP: <offscreen-world>
+{ $values
+     { "gadget" gadget } { "title" string } { "status" "a boolean" }
+     { "world" offscreen-world }
+}
+{ $description "Constructs an " { $link offscreen-world } " gadget with " { $snippet "gadget" } " as its only child. Generally you should use " { $link open-offscreen } " or " { $link do-offscreen } " instead of calling this word directly." } ;
+
+HELP: close-offscreen
+{ $values
+     { "world" offscreen-world }
+}
+{ $description "Releases the resources used by the rendering buffer for " { $snippet "world" } "." } ;
+
+HELP: do-offscreen
+{ $values
+     { "gadget" gadget } { "quot" quotation }
+}
+{ $description "Constructs an " { $link offscreen-world } " around " { $snippet "gadget" } " with " { $link open-offscreen } ", calls " { $snippet "quotation" } " with the world on the top of the stack, and cleans up the world with " { $link close-offscreen } " at the end of " { $snippet "quotation" } "." } ;
+
+HELP: gadget>bitmap
+{ $values
+     { "gadget" gadget }
+     { "bitmap" bitmap }
+}
+{ $description "Renders " { $snippet "gadget" } " to an " { $link offscreen-world } " and creates a " { $link bitmap } " from its contents." } ;
+
+HELP: offscreen-world
+{ $class-description "The class of " { $link world } " objects that render to an offscreen buffer." } ;
+
+HELP: offscreen-world>bitmap
+{ $values
+     { "world" offscreen-world }
+     { "bitmap" bitmap }
+}
+{ $description "Saves a copy of the contents of " { $snippet "world" } " to a " { $link bitmap } " object." } ;
+
+HELP: open-offscreen
+{ $values
+     { "gadget" gadget }
+     { "world" offscreen-world }
+}
+{ $description "Creates and sets up an " { $link offscreen-world } " with " { $snippet "gadget" } " as its only child." } ;
+
+{ offscreen-world open-offscreen close-offscreen do-offscreen } related-words
+
+ARTICLE: "ui.offscreen" "Offscreen UI rendering"
+"The " { $vocab-link "ui.offscreen" } " provides words for rendering gadgets to an offscreen buffer so that bitmaps can be made from their contents."
+{ $subsection offscreen-world }
+"Opening gadgets offscreen:"
+{ $subsection open-offscreen }
+{ $subsection close-offscreen }
+{ $subsection do-offscreen }
+"Creating bitmaps from offscreen buffers:"
+{ $subsection offscreen-world>bitmap }
+{ $subsection gadget>bitmap } ;
+
+ABOUT: "ui.offscreen"
diff --git a/extra/ui/offscreen/offscreen.factor b/extra/ui/offscreen/offscreen.factor
index be6638bed8..3897df71fa 100755
--- a/extra/ui/offscreen/offscreen.factor
+++ b/extra/ui/offscreen/offscreen.factor
@@ -1,5 +1,6 @@
 USING: accessors continuations graphics.bitmap kernel math
-sequences ui.gadgets ui.gadgets.worlds ui ui.backend ;
+sequences ui.gadgets ui.gadgets.worlds ui ui.backend
+destructors ;
 IN: ui.offscreen
 
 TUPLE: offscreen-world < world ;
@@ -23,6 +24,8 @@ M: offscreen-world ungraft*
 : close-offscreen ( world -- )
     ungraft notify-queued ;
 
+M: offscreen-world dispose close-offscreen ;
+
 : offscreen-world>bitmap ( world -- bitmap )
     offscreen-pixels bgra>bitmap ;
 
diff --git a/extra/ui/offscreen/summary.txt b/extra/ui/offscreen/summary.txt
new file mode 100644
index 0000000000..51ef124d97
--- /dev/null
+++ b/extra/ui/offscreen/summary.txt
@@ -0,0 +1 @@
+Offscreen world gadgets for rendering UI elements to bitmaps
diff --git a/extra/ui/offscreen/tags.txt b/extra/ui/offscreen/tags.txt
new file mode 100644
index 0000000000..b796ebde91
--- /dev/null
+++ b/extra/ui/offscreen/tags.txt
@@ -0,0 +1,3 @@
+unportable
+ui
+graphics