basis/ui/gadgets/glass/glass-docs.factor

   1 IN: ui.gadgets.glass
   2 USING: help.markup help.syntax ui.gadgets math.rectangles ;
   3
   4 HELP: show-glass
   5 { $values { "owner" gadget } { "child" gadget } { "visible-rect" rect } }
   6 { $description "Displays " { $snippet "child" } " in the glass layer of the window containing " { $snippet "owner" } "."
   7   $nl
   8   "The child's position is calculated with a heuristic:"
   9   { $list
  10     "The child must fit inside the window"
  11     { "The child must not obscure " { $snippet "visible-rect" } ", which is a rectangle whose origin is relative to " { $snippet "owner" } }
  12     { "The child must otherwise be as close as possible to the edges of " { $snippet "visible-rect" } }
  13   }
  14   "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."
  15 } ;
  16
  17 HELP: hide-glass
  18 { $values { "child" gadget } }
  19 { $description "Hides a gadget displayed in a glass layer." } ;
  20
  21 HELP: hide-glass-hook
  22 { $values { "gadget" gadget } }
  23 { $description "Called when a gadget displayed in a glass layer is hidden. The gadget can perform cleanup tasks here." } ;
  24
  25 HELP: pass-to-popup
  26 { $values { "gesture" "a gesture" } { "owner" "the popup's owner" } { "?" "a boolean" } }
  27 { $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." } ;
  28
  29 HELP: show-popup
  30 { $values { "owner" gadget } { "popup" gadget } { "visible-rect" rect } }
  31 { $description "Displays " { $snippet "popup" } " in the glass layer of the window containing " { $snippet "owner" } " as a popup."
  32   $nl
  33   "This word differs from " { $link show-glass } " in two respects:"
  34   { $list
  35     { "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" }
  36     { "Pressing " { $snippet "ESC" } " with the popup visible will hide it" }
  37   }
  38 } ;
  39
  40 ARTICLE: "ui.gadgets.glass" "Glass layers"
  41 "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."
  42 $nl
  43 "This feature is used for completion popups and " { $link "ui.gadgets.menus" } " in the " { $link "ui-tools" } "."
  44 $nl
  45 "Displaying a gadget in a glass layer:"
  46 { $subsection show-glass }
  47 "Hiding a gadget in a glass layer:"
  48 { $subsection hide-glass }
  49 "Callback generic invoked on the gadget when its glass layer is hidden:"
  50 { $subsection hide-glass-hook }
  51 "Popup gadgets add support for forwarding keyboard gestures from an owner gadget to the glass layer:"
  52 { $subsection show-popup }
  53 { $subsection pass-to-popup } ;
  54
  55 ABOUT: "ui.gadgets.glass"