ui.gadgets.status-bar: write some docs and add notion of status message ownership...

diff --git a/basis/ui/gadgets/status-bar/status-bar-docs.factor b/basis/ui/gadgets/status-bar/status-bar-docs.factor
index 6203cd474ee5b2cb055b1370b6714d59e7cd92b5..f5a6409fcaf79b265ac39dd42e1eccc6f2c19eb0 100644 (file)
--- a/basis/ui/gadgets/status-bar/status-bar-docs.factor
+++ b/basis/ui/gadgets/status-bar/status-bar-docs.factor
@@ -1,8 +1,33 @@
-USING: help.markup help.syntax models
-ui.gadgets ui.gadgets.worlds ;
+USING: help.markup help.syntax models strings
+ui.gadgets ui.gadgets.worlds ui ;
 IN: ui.gadgets.status-bar
 
+HELP: show-status
+{ $values { "string" string } { "gadget" gadget } }
+{ $description "Displays a status message in the gadget's world." }
+{ $notes "The status message will only be visible if the window was opened with " { $link open-status-window } ", and not " { $link open-window } "." } ;
+
+HELP: hide-status
+{ $values { "gadget" gadget } }
+{ $description "Hides the status message in the gadget's world." }
+{ $notes "The gadget passed in must be the gadget passed to " { $link show-status } ", otherwise the word does nothing. This ensures that one gadget does not hide another gadget's status message." } ;
+
 HELP: <status-bar>
 { $values { "model" model } { "gadget" "a new " { $link gadget } } }
 { $description "Creates a new " { $link gadget } " displaying the model value, which must be a string or " { $link f } "." }
 { $notes "If the " { $snippet "model" } " is " { $snippet "status" } ", this gadget will display mouse over help for " { $link "ui.gadgets.presentations" } "." } ;
+
+HELP: open-status-window
+{ $values { "gadget" gadget } { "title" string } }
+{ $description "Like " { $link open-window } ", with the additional feature that the new window iwll have a status bar displaying the value stored in the world's " { $slot "status" } " slot." }
+{ $see-also show-status hide-status } ;
+
+ARTICLE: "ui.gadgets.status-bar" "Status bars and mouse-over help"
+"The " { $vocab-link "ui.gadgets.status-bar" } " vocabulary implements a word to display windows with a status bar."
+{ $subsection open-status-window }
+"Gadgets can use a pair of words to show and hide status bar messages. These words will work in any gadget, but will have no effect unless the gadget is displayed inside a window with a status bar."
+{ $subsection show-status }
+{ $subsection hide-status }
+{ $link "ui.gadgets.presentations" } " use the status bar to display object summary." ;
+
+ABOUT: "ui.gadgets.status-bar"
\ No newline at end of file

diff --git a/basis/ui/gadgets/worlds/worlds-docs.factor b/basis/ui/gadgets/worlds/worlds-docs.factor
index ac066593e140bda2cd591351cc8e00234adfd940..e3c1226f2216c8e5477c75ffc5aba511f9f5666a 100644 (file)
--- a/basis/ui/gadgets/worlds/worlds-docs.factor
+++ b/basis/ui/gadgets/worlds/worlds-docs.factor
@@ -35,9 +35,10 @@ HELP: world
 { $class-description "A gadget which appears at the top of the gadget hieararchy, and in turn may be displayed in a native window. Worlds have the following slots:"
     { $list
         { { $snippet "active?" } " - if set to " { $link f } ", the world will not be drawn. This slot is set to " { $link f } " if an error is thrown while drawing the world; this prevents multiple debugger windows from being shown." }
-        { { $snippet "glass" } " - a glass pane in front of the primary gadget, used to implement behaviors such as popup menus which are hidden when the mouse is clicked outside the menu." }
+        { { $snippet "layers" } " - a sequence of glass panes in front of the primary gadget, used to implement behaviors such as popup menus which are hidden when the mouse is clicked outside the menu. See " { $link "ui.gadgets.glass" } "." }
         { { $snippet "title" } " - a string to be displayed in the title bar of the native window containing the world." }
         { { $snippet "status" } " - a " { $link model } " holding a string to be displayed in the world's status bar." }
+        { { $snippet "status-owner" } " - the gadget that displayed the most recent status message." }
         { { $snippet "focus" } " - the current owner of the keyboard focus in the world." }
         { { $snippet "focused?" } " - a boolean indicating if the native window containing the world has keyboard focus." }
         { { $snippet "fonts" } " - a hashtable used by the " { $link font-renderer } "." }

diff --git a/basis/ui/gadgets/worlds/worlds.factor b/basis/ui/gadgets/worlds/worlds.factor
index 9b836bc1276302105f997412d8ce28eb97f3269d..0a875cf7c855afec69835fe986d9c01497e152be 100644 (file)
--- a/basis/ui/gadgets/worlds/worlds.factor
+++ b/basis/ui/gadgets/worlds/worlds.factor
@@ -10,19 +10,25 @@ IN: ui.gadgets.worlds
 TUPLE: world < track
 active? focused?
 layers
-title status
+title status status-owner
 text-handle handle images
 window-loc ;
 
 : find-world ( gadget -- world/f ) [ world? ] find-parent ;
 
 : show-status ( string/f gadget -- )
-    find-world dup [
-        status>> dup [ set-model ] [ 2drop ] if
+    dup find-world dup [
+        dup status>> [
+            [ (>>status-owner) ] [ status>> set-model ] bi
+        ] [ 3drop ] if
+    ] [ 3drop ] if ;
+
+: hide-status ( gadget -- )
+    dup find-world dup [
+        [ status-owner>> eq? ] keep
+        '[ f _ [ (>>status-owner) ] [ status>> set-model ] 2bi ] when
     ] [ 2drop ] if ;
 
-: hide-status ( gadget -- ) f swap show-status ;
-
 ERROR: no-world-found ;
 
 : find-gl-context ( gadget -- )

diff --git a/basis/ui/ui-docs.factor b/basis/ui/ui-docs.factor
index 7e432657d4e7d230b15a512923697a1cdd0da2ad..6e5fe6baafe66ac9a62f8fc02a3e1be4d532a331 100644 (file)
--- a/basis/ui/ui-docs.factor
+++ b/basis/ui/ui-docs.factor
@@ -84,6 +84,7 @@ ARTICLE: "building-ui" "Building user interfaces"
 { $subsection "ui-layouts" }
 { $subsection "gadgets" }
 { $subsection "ui-windows" }
+{ $subsection "ui.gadgets.status-bar" }
 { $see-also "models" } ;
 
 ARTICLE: "gadgets" "Pre-made UI gadgets"