extra/ui/gadgets/worlds/worlds-docs.factor

   1 USING: ui.gadgets ui.render ui.gestures ui.backend help.markup
   2 help.syntax models opengl strings ;
   3 IN: ui.gadgets.worlds
   4
   5 HELP: origin
   6 { $var-description "Within the dynamic extent of " { $link draw-world } ", holds the co-ordinate system origin for the gadget currently being drawn." } ;
   7
   8 HELP: hand-world
   9 { $var-description "Global variable. The " { $link world } " containing the gadget at the mouse location." } ;
  10
  11 HELP: set-title
  12 { $values { "string" string } { "world" world } }
  13 { $description "Sets the title bar of the native window containing the world." }
  14 { $notes "This word should not be called directly by user code. Instead, change the " { $link world-title } " model; see " { $link "models" } "." } ;
  15
  16 HELP: set-fullscreen?
  17 { $values { "?" "a boolean" } { "world" world } }
  18 { $description "Sets and unsets fullscreen mode for the world." }
  19 { $notes "Find a world using " { $link find-world } "." } ;
  20
  21 HELP: fullscreen?
  22 { $values { "world" world } { "?" "a boolean" } }
  23 { $description "Queries the world to see if it is running in fullscreen mode." } ;
  24
  25 HELP: raise-window
  26 { $values { "world" world } }
  27 { $description "Makes the native window containing the given world the front-most window." }
  28 { $notes "To raise the window containing a specific gadget, use " { $link find-world } " to find the world containing the gadget first." } ;
  29
  30 HELP: select-gl-context
  31 { $values { "handle" "a backend-specific handle" } }
  32 { $description "Selects an OpenGL context to be the implicit destination for subsequent GL rendering calls. This word is called automatically by the UI before drawing a " { $link world } "." } ;
  33
  34 HELP: flush-gl-context
  35 { $values { "handle" "a backend-specific handle" } }
  36 { $description "Ensures all GL rendering calls made to an OpenGL context finish rendering to the screen. This word is called automatically by the UI after drawing a " { $link world } "." } ;
  37
  38 HELP: focus-path
  39 { $values { "world" world } { "seq" "a new sequence" } }
  40 { $description "If the top-level window containing the world has focus, outputs a sequence of parents of the currently focused gadget, otherwise outputs " { $link f } "." }
  41 { $notes "This word is used to avoid sending " { $link gain-focus } " gestures to a gadget which requests focus on an unfocused top-level window, so that, for instance, a text editing caret does not appear in this case." } ;
  42
  43 HELP: world
  44 { $class-description "A gadget which appears at the top of the gadget hieararchy, and in turn may be displayed in a native window. Worlds delegate to " { $link gadget } " instances and have the following slots:"
  45     { $list
  46         { { $link world-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." }
  47         { { $link world-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." }
  48         { { $link world-title } " - a string to be displayed in the title bar of the native window containing the world." }
  49         { { $link world-status } " - a " { $link model } " holding a string to be displayed in the world's status bar." }
  50         { { $link world-focus } " - the current owner of the keyboard focus in the world." }
  51         { { $link world-focused? } " - a boolean indicating if the native window containing the world has keyboard focus." }
  52         { { $link world-fonts } " - a hashtable mapping font instances to vectors of " { $link sprite } " instances." }
  53         { { $link world-handle } " - a backend-specific native handle representing the native window containing the world, or " { $link f } " if the world is not grafted." }
  54         { { $link world-loc } " - the on-screen location of the native window containing the world. The co-ordinate system here is backend-specific." }
  55     }
  56 } ;
  57
  58 HELP: <world>
  59 { $values { "gadget" gadget } { "title" string } { "status" model } { "world" "a new " { $link world } } }
  60 { $description "Creates a new " { $link world } " delegating to the given gadget." } ;
  61
  62 HELP: find-world
  63 { $values { "gadget" gadget } { "world" "a " { $link world } " or " { $link f } } }
  64 { $description "Finds the " { $link world } " containing the gadget, or outputs " { $link f } " if the gadget is not grafted." } ;
  65
  66 HELP: draw-world
  67 { $values { "world" world } }
  68 { $description "Redraws a world." }
  69 { $notes "This word should only be called by the UI backend. To force a gadget to redraw from user code, call " { $link relayout-1 } "." } ;