From 16ddc461b4c2dbb528a785dc0a5dc19cf3db5f0b Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Tue, 10 Mar 2009 17:28:34 -0500 Subject: [PATCH] Document ui.gadgets.glass and fix help lint failures in UI docs --- basis/ui/gadgets/glass/glass-docs.factor | 55 +++++++++++++++++++ basis/ui/gadgets/glass/glass.factor | 2 +- basis/ui/gadgets/menus/menus-docs.factor | 2 +- .../gadgets/status-bar/status-bar-docs.factor | 2 +- basis/ui/ui-docs.factor | 1 + 5 files changed, 59 insertions(+), 3 deletions(-) create mode 100644 basis/ui/gadgets/glass/glass-docs.factor diff --git a/basis/ui/gadgets/glass/glass-docs.factor b/basis/ui/gadgets/glass/glass-docs.factor new file mode 100644 index 0000000000..bd9028d414 --- /dev/null +++ b/basis/ui/gadgets/glass/glass-docs.factor @@ -0,0 +1,55 @@ +IN: ui.gadgets.glass +USING: help.markup help.syntax ui.gadgets math.rectangles ; + +HELP: show-glass +{ $values { "owner" gadget } { "child" gadget } { "visible-rect" rect } } +{ $description "Displays " { $snippet "child" } " in the glass layer of the window containing " { $snippet "owner" } "." + $nl + "The child's position is calculated with a heuristic:" + { $list + "The child must fit inside the window" + { "The child must not obscure " { $snippet "visible-rect" } ", which is a rectangle whose origin is relative to " { $snippet "owner" } } + { "The child must otherwise be as close as possible to the edges of " { $snippet "visible-rect" } } + } + "For example, when displaying a menu, " { $snippet "visible-rect" } " is a single point at the mouse location, and when displaying a completion popup, " { $snippet "visible-rect" } " contains the bounds of the text element being completed." +} ; + +HELP: hide-glass +{ $values { "child" gadget } } +{ $description "Hides a gadget displayed in a glass layer." } ; + +HELP: hide-glass-hook +{ $values { "gadget" gadget } } +{ $description "Called when a gadget displayed in a glass layer is hidden. The gadget can perform cleanup tasks here." } ; + +HELP: pass-to-popup +{ $values { "gesture" "a gesture" } { "owner" "the popup's owner" } { "?" "a boolean" } } +{ $description "Resends the gesture to the popup displayed by " { $snippet "owner" } ". The owner must have a " { $slot "popup" } " slot. Outputs " { $link f } " if the gesture was handled, " { $link t } " otherwise." } ; + +HELP: show-popup +{ $values { "owner" gadget } { "popup" gadget } { "visible-rect" rect } } +{ $description "Displays " { $snippet "popup" } " in the glass layer of the window containing " { $snippet "owner" } " as a popup." + $nl + "This word differs from " { $link show-glass } " in two respects:" + { $list + { "The popup is stored in the owner's " { $slot "popup" } " slot; the owner can call " { $link pass-to-popup } " to pass keyboard gestures to the popup" } + { "Pressing " { $snippet "ESC" } " with the popup visible will hide it" } + } +} ; + +ARTICLE: "ui.gadgets.glass" "Glass layers" +"The " { $vocab-link "ui.gadgets.glass" } " vocabulary implements support for displaying gadgets in the glass layer of a window. The gadget can be positioned arbitrarily within the glass layer, and while it is visible, mouse clicks outside of the glass layer are intercepted to hide the glass layer. Multiple glass layers can be active at a time; they behave as if stacked on top of each other." +$nl +"This feature is used for completion popups and " { $link "ui.gadgets.menus" } " in the " { $link "ui-tools" } "." +$nl +"Displaying a gadget in a glass layer:" +{ $subsection show-glass } +"Hiding a gadget in a glass layer:" +{ $subsection hide-glass } +"Callback generic invoked on the gadget when its glass layer is hidden:" +{ $subsection hide-glass-hook } +"Popup gadgets add support for forwarding keyboard gestures from an owner gadget to the glass layer:" +{ $subsection show-popup } +{ $subsection pass-to-popup } ; + +ABOUT: "ui.gadgets.glass" \ No newline at end of file diff --git a/basis/ui/gadgets/glass/glass.factor b/basis/ui/gadgets/glass/glass.factor index a8f438c85e..af169235b4 100644 --- a/basis/ui/gadgets/glass/glass.factor +++ b/basis/ui/gadgets/glass/glass.factor @@ -71,7 +71,7 @@ popup H{ { T{ key-down f f "ESC" } [ hide-glass ] } } set-gestures -: pass-to-popup ( gesture interactor -- ? ) +: pass-to-popup ( gesture owner -- ? ) popup>> focusable-child resend-gesture ; : show-popup ( owner popup visible-rect -- ) diff --git a/basis/ui/gadgets/menus/menus-docs.factor b/basis/ui/gadgets/menus/menus-docs.factor index d7297217ed..ad0881a382 100644 --- a/basis/ui/gadgets/menus/menus-docs.factor +++ b/basis/ui/gadgets/menus/menus-docs.factor @@ -16,7 +16,7 @@ HELP: show-commands-menu { $notes "Useful for right-click context menus." } ; ARTICLE: "ui.gadgets.menus" "Popup menus" -"The " { $vocab-link "ui.gadgets.menus" } " vocabulary implements popup menus." +"The " { $vocab-link "ui.gadgets.menus" } " vocabulary displays popup menus in " { $link "ui.gadgets.glass" } "." { $subsection } { $subsection show-menu } { $subsection show-commands-menu } ; diff --git a/basis/ui/gadgets/status-bar/status-bar-docs.factor b/basis/ui/gadgets/status-bar/status-bar-docs.factor index f5a6409fca..57c69c2a66 100644 --- a/basis/ui/gadgets/status-bar/status-bar-docs.factor +++ b/basis/ui/gadgets/status-bar/status-bar-docs.factor @@ -3,7 +3,7 @@ ui.gadgets ui.gadgets.worlds ui ; IN: ui.gadgets.status-bar HELP: show-status -{ $values { "string" string } { "gadget" gadget } } +{ $values { "string/f" 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 } "." } ; diff --git a/basis/ui/ui-docs.factor b/basis/ui/ui-docs.factor index d08dea299e..f2b6154745 100644 --- a/basis/ui/ui-docs.factor +++ b/basis/ui/ui-docs.factor @@ -171,6 +171,7 @@ ARTICLE: "ui-layouts" "Gadget hierarchy and layouts" { $subsection "ui-frame-layout" } { $subsection "ui-book-layout" } "Advanced topics:" +{ $subsection "ui.gadgets.glass" } { $subsection "ui-null-layout" } { $subsection "ui-incremental-layout" } { $subsection "ui-layout-impl" }