From a0253106b118383740cd26239f0919f0665d43a0 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Thu, 19 Feb 2009 18:01:26 -0600 Subject: [PATCH] ui.gadgets.status-bar: write some docs and add notion of status message ownership to avoid some subtle race issues with completion popup and listener's keyboard help --- .../gadgets/status-bar/status-bar-docs.factor | 29 +++++++++++++++++-- basis/ui/gadgets/worlds/worlds-docs.factor | 3 +- basis/ui/gadgets/worlds/worlds.factor | 16 ++++++---- basis/ui/ui-docs.factor | 1 + 4 files changed, 41 insertions(+), 8 deletions(-) diff --git a/basis/ui/gadgets/status-bar/status-bar-docs.factor b/basis/ui/gadgets/status-bar/status-bar-docs.factor index 6203cd474e..f5a6409fca 100644 --- 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: { $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 ac066593e1..e3c1226f22 100644 --- 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 9b836bc127..0a875cf7c8 100644 --- a/basis/ui/gadgets/worlds/worlds.factor +++ b/basis/ui/gadgets/worlds/worlds.factor @@ -10,18 +10,24 @@ 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 - ] [ 2drop ] if ; + dup find-world dup [ + dup status>> [ + [ (>>status-owner) ] [ status>> set-model ] bi + ] [ 3drop ] if + ] [ 3drop ] if ; -: hide-status ( gadget -- ) f swap show-status ; +: hide-status ( gadget -- ) + dup find-world dup [ + [ status-owner>> eq? ] keep + '[ f _ [ (>>status-owner) ] [ status>> set-model ] 2bi ] when + ] [ 2drop ] if ; ERROR: no-world-found ; diff --git a/basis/ui/ui-docs.factor b/basis/ui/ui-docs.factor index 7e432657d4..6e5fe6baaf 100644 --- 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"