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

   1 USING: destructors help.markup help.syntax math models strings
   2 ui.backend ui.gadgets ui.gestures ui.render ;
   3 IN: ui.gadgets.worlds
   4
   5 HELP: user-input
   6 { $values { "string" string } { "world" world } }
   7 { $description "Calls " { $link user-input* } " on every parent of the world's currently-focused child." } ;
   8
   9 HELP: origin
  10 { $var-description "Within the dynamic extent of " { $link draw-world } ", holds the co-ordinate system origin for the gadget currently being drawn." } ;
  11
  12 HELP: hand-world
  13 { $var-description "Global variable. The " { $link world } " containing the gadget at the mouse location." } ;
  14
  15 HELP: grab-input
  16 { $values { "gadget" gadget } }
  17 { $description "Sets the " { $link world } " containing " { $snippet "gadget" } " to grab mouse and keyboard input while focused." }
  18 { $notes "Normal mouse gestures may not be available while input is grabbed." } ;
  19
  20 HELP: ungrab-input
  21 { $values { "gadget" gadget } }
  22 { $description "Sets the " { $link world } " containing " { $snippet "gadget" } " not to grab mouse and keyboard input while focused." } ;
  23
  24 { grab-input ungrab-input } related-words
  25
  26 HELP: set-title
  27 { $values { "string" string } { "world" world } }
  28 { $description "Sets the title bar of the native window containing the world." } ;
  29
  30 HELP: set-gl-context
  31 { $values { "world" world } }
  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: window-resource
  35 { $values { "resource" disposable } }
  36 { $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." } ;
  37
  38 HELP: flush-gl-context
  39 { $values { "handle" "a backend-specific handle" } }
  40 { $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 } "." } ;
  41
  42 HELP: focus-path
  43 { $values { "gadget" gadget } { "seq" "a new sequence" } }
  44 { $description "If the gadget has focus, outputs a sequence of parents of the currently focused gadget, otherwise outputs " { $link f } "." }
  45 { $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." } ;
  46
  47 HELP: world
  48 { $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:"
  49   { $table
  50     {
  51         { $slot "active?" }
  52         { "an " { $link integer } " initially set to 0. The active " { $link ui-backend } " increases the value in steps up to 100 while the native window containing the world is being initialized but not yet visible on the screen. The world is only redrawn when the value is 100 which prevents redundant redraws from happening during initialization. The slot is set to 0 if an error is thrown while drawing the world; this prevents multiple debugger windows from being shown." }
  53     }
  54     {
  55         { $slot "layers" }
  56         { "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" } "." }
  57     }
  58     {
  59         { $slot "title" }
  60         { "a string to be displayed in the title bar of the native window containing the world." }
  61     }
  62     {
  63         { $slot "status" }
  64         { "a " { $link model } " holding a string to be displayed in the world's status bar." }
  65     }
  66     {
  67         { $slot "status-owner" }
  68         { "the gadget that displayed the most recent status message." }
  69     }
  70     {
  71         { $slot "focus" }
  72         { "the current owner of the keyboard focus in the world." }
  73     }
  74     {
  75         { $slot "focused?" }
  76         { "a boolean indicating if the native window containing the world has keyboard focus." }
  77     }
  78     {
  79         { $slot "grab-input?" }
  80         { "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." }
  81     }
  82     {
  83         { $slot "handle" }
  84         { "a backend-specific native handle representing the native window containing the world, or " { $link f } " if the world is not grafted." }
  85     }
  86     {
  87         { $slot "window-loc" }
  88         { "the on-screen location of the native window containing the world. The co-ordinate system here is backend-specific." }
  89     }
  90     {
  91         { $slot "window-controls" }
  92         { "the set of " { $link "ui.gadgets.worlds-window-controls" } " with which the world window was created." }
  93     }
  94   }
  95 } ;
  96
  97 HELP: <world>
  98 { $values { "world-attributes" world-attributes } { "world" "a new " { $link world } } }
  99 { $description "Creates a new " { $link world } " or world subclass with the given attributes." } ;
 100
 101 HELP: find-world
 102 { $values { "gadget" gadget } { "world/f" { $maybe world } } }
 103 { $description "Finds the " { $link world } " containing the gadget, or outputs " { $link f } " if the gadget is not grafted." } ;
 104
 105 HELP: draw-world
 106 { $values { "world" world } }
 107 { $description "Redraws a world." }
 108 { $notes "This word should only be called by the UI backend. To force a gadget to redraw from user code, call " { $link relayout-1 } "." } ;
 109
 110 HELP: find-gl-context
 111 { $values { "gadget" gadget } }
 112 { $description "Makes the OpenGL context of the gadget's containing native window the current OpenGL context." }
 113 { $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." } ;
 114
 115 HELP: begin-world
 116 { $values { "world" world } }
 117 { $description "Called immediately after " { $snippet "world" } "'s OpenGL context has been created. The world's OpenGL context is current when this method is called." } ;
 118
 119 HELP: end-world
 120 { $values { "world" world } }
 121 { $description "Called immediately before " { $snippet "world" } "'s OpenGL context is destroyed. The world's OpenGL context is current when this method is called." } ;
 122
 123 HELP: resize-world
 124 { $values { "world" world } }
 125 { $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." } ;
 126
 127 HELP: draw-world*
 128 { $values { "world" world } }
 129 { $description "Called when " { $snippet "world" } " needs to be redrawn. The world's OpenGL context is current when this method is called." } ;
 130
 131 HELP: ui-error-hook
 132 { $var-description "A quotation that is called if an error occurs in the UI updating thread." }
 133 { $see-also ui-error } ;
 134
 135 ARTICLE: "ui.gadgets.worlds-subclassing" "Subclassing worlds"
 136 "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:"
 137 { $subsections
 138     begin-world
 139     end-world
 140     resize-world
 141     draw-world*
 142 }
 143 "See the " { $vocab-link "spheres" } " and " { $vocab-link "bunny" } " demos for examples." ;
 144
 145 ARTICLE: "ui-paint-custom" "Implementing custom drawing logic"
 146 "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:"
 147 { $subsections draw-gadget* }
 148 "Custom drawing code has access to the full OpenGL API in the " { $vocab-link "opengl" } " vocabulary."
 149 $nl
 150 "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:"
 151 { $subsections find-gl-context }
 152 "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" } "."
 153 { $subsections
 154     "ui-paint-coord"
 155     "ui.gadgets.worlds-subclassing"
 156     "gl-utilities"
 157     "text-rendering"
 158 } ;