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

   1 USING: ui.gadgets ui.render ui.text ui.text.private
   2 ui.gestures ui.backend help.markup help.syntax
   3 models opengl sequences strings destructors ;
   4 IN: ui.gadgets.worlds
   5
   6 HELP: user-input
   7 { $values { "string" string } { "world" world } }
   8 { $description "Calls " { $link user-input* } " on every parent of the world's currently-focused child." } ;
   9
  10 HELP: origin
  11 { $var-description "Within the dynamic extent of " { $link draw-world } ", holds the co-ordinate system origin for the gadget currently being drawn." } ;
  12
  13 HELP: hand-world
  14 { $var-description "Global variable. The " { $link world } " containing the gadget at the mouse location." } ;
  15
  16 HELP: grab-input
  17 { $values { "gadget" gadget } }
  18 { $description "Sets the " { $link world } " containing " { $snippet "gadget" } " to grab mouse and keyboard input while focused." }
  19 { $notes "Normal mouse gestures may not be available while input is grabbed." } ;
  20
  21 HELP: ungrab-input
  22 { $values { "gadget" gadget } }
  23 { $description "Sets the " { $link world } " containing " { $snippet "gadget" } " not to grab mouse and keyboard input while focused." } ;
  24
  25 { grab-input ungrab-input } related-words
  26
  27 HELP: set-title
  28 { $values { "string" string } { "world" world } }
  29 { $description "Sets the title bar of the native window containing the world." } ;
  30
  31 HELP: set-gl-context
  32 { $values { "world" world } }
  33 { $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 } "." } ;
  34
  35 HELP: window-resource
  36 { $values { "resource" disposable } { "resource" disposable } }
  37 { $description "Marks " { $snippet "resource" } " to be destroyed with " { $link dispose } " when the window with the currently active OpenGL context (set by " { $link set-gl-context } ") is closed. " { $snippet "resource" } " is left unmodified at the top of the stack." } ;
  38
  39 HELP: flush-gl-context
  40 { $values { "handle" "a backend-specific handle" } }
  41 { $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 } "." } ;
  42
  43 HELP: focus-path
  44 { $values { "gadget" gadget } { "seq" "a new sequence" } }
  45 { $description "If the gadget has focus, outputs a sequence of parents of the currently focused gadget, otherwise outputs " { $link f } "." }
  46 { $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." } ;
  47
  48 HELP: world
  49 { $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:"
  50     { $list
  51         { { $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." }
  52         { { $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" } "." }
  53         { { $snippet "title" } " - a string to be displayed in the title bar of the native window containing the world." }
  54         { { $snippet "status" } " - a " { $link model } " holding a string to be displayed in the world's status bar." }
  55         { { $snippet "status-owner" } " - the gadget that displayed the most recent status message." }
  56         { { $snippet "focus" } " - the current owner of the keyboard focus in the world." }
  57         { { $snippet "focused?" } " - a boolean indicating if the native window containing the world has keyboard focus." }
  58         { { $snippet "fonts" } " - a hashtable used by the " { $link font-renderer } "." }
  59         { { $snippet "grab-input?" } " - if set to " { $link t } ", the world will hide the mouse cursor and disable normal mouse input while focused. Use " { $link grab-input } " and " { $link ungrab-input } " to change this setting." }
  60         { { $snippet "handle" } " - a backend-specific native handle representing the native window containing the world, or " { $link f } " if the world is not grafted." }
  61         { { $snippet "window-loc" } " - the on-screen location of the native window containing the world. The co-ordinate system here is backend-specific." }
  62         { { $snippet "window-controls" } " - the set of " { $link "ui.gadgets.worlds-window-controls" } " with which the world window was created." }
  63     }
  64 } ;
  65
  66 HELP: <world>
  67 { $values { "world-attributes" world-attributes } { "world" "a new " { $link world } } }
  68 { $description "Creates a new " { $link world } " or world subclass with the given attributes." } ;
  69
  70 HELP: find-world
  71 { $values { "gadget" gadget } { "world/f" { $maybe world } } }
  72 { $description "Finds the " { $link world } " containing the gadget, or outputs " { $link f } " if the gadget is not grafted." } ;
  73
  74 HELP: draw-world
  75 { $values { "world" world } }
  76 { $description "Redraws a world." }
  77 { $notes "This word should only be called by the UI backend. To force a gadget to redraw from user code, call " { $link relayout-1 } "." } ;
  78
  79 HELP: find-gl-context
  80 { $values { "gadget" gadget } }
  81 { $description "Makes the OpenGL context of the gadget's containing native window the current OpenGL context." }
  82 { $notes "This word should be called from " { $link graft* } " and " { $link ungraft* } " methods which need to allocate and deallocate OpenGL resources, such as textures, display lists, and so on." } ;
  83
  84 HELP: begin-world
  85 { $values { "world" world } }
  86 { $description "Called immediately after " { $snippet "world" } "'s OpenGL context has been created. The world's OpenGL context is current when this method is called." } ;
  87
  88 HELP: end-world
  89 { $values { "world" world } }
  90 { $description "Called immediately before " { $snippet "world" } "'s OpenGL context is destroyed. The world's OpenGL context is current when this method is called." } ;
  91
  92 HELP: resize-world
  93 { $values { "world" world } }
  94 { $description "Called when the window containing " { $snippet "world" } " is resized. The " { $snippet "loc" } " and " { $snippet "dim" } " slots of " { $snippet "world" } " will be updated with the world's new position and size. The world's OpenGL context is current when this method is called." } ;
  95
  96 HELP: draw-world*
  97 { $values { "world" world } }
  98 { $description "Called when " { $snippet "world" } " needs to be redrawn. The world's OpenGL context is current when this method is called." } ;
  99
 100 ARTICLE: "ui.gadgets.worlds-subclassing" "Subclassing worlds"
 101 "The " { $link world } " gadget can be subclassed, giving Factor code full control of the window's OpenGL context. The following generic words can be overridden to replace standard UI behavior:"
 102 { $subsections
 103     begin-world
 104     end-world
 105     resize-world
 106     draw-world*
 107 }
 108 "See the " { $vocab-link "spheres" } " and " { $vocab-link "bunny" } " demos for examples." ;
 109
 110 ARTICLE: "ui-paint-custom" "Implementing custom drawing logic"
 111 "The UI uses OpenGL to render gadgets. Custom rendering logic can be plugged in with the " { $link "ui-pen-protocol" } ", or by implementing a generic word:"
 112 { $subsections draw-gadget* }
 113 "Custom drawing code has access to the full OpenGL API in the " { $vocab-link "opengl" } " vocabulary."
 114 $nl
 115 "Gadgets which need to allocate and deallocate OpenGL resources such as textures, display lists, and so on, should perform the allocation in the " { $link graft* } " method, and the deallocation in the " { $link ungraft* } " method. Since those words are not necessarily called with the gadget's OpenGL context active, a utility word can be used to find and make the correct OpenGL context current:"
 116 { $subsections find-gl-context }
 117 "OpenGL state must not be altered as a result of drawing a gadget, so any flags which were enabled should be disabled, and vice versa. To take full control of the OpenGL context, see " { $link "ui.gadgets.worlds-subclassing" } "."
 118 { $subsections
 119     "ui-paint-coord"
 120     "ui.gadgets.worlds-subclassing"
 121     "gl-utilities"
 122     "text-rendering"
 123 } ;
 124