basis/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: 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: set-title
  16 { $values { "string" string } { "world" world } }
  17 { $description "Sets the title bar of the native window containing the world." }
  18 { $notes "This word should not be called directly by user code. Instead, change the " { $snippet "title" } " slot model; see " { $link "models" } "." } ;
  19
  20 HELP: select-gl-context
  21 { $values { "handle" "a backend-specific handle" } }
  22 { $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 } "." } ;
  23
  24 HELP: flush-gl-context
  25 { $values { "handle" "a backend-specific handle" } }
  26 { $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 } "." } ;
  27
  28 HELP: focus-path
  29 { $values { "world" world } { "seq" "a new sequence" } }
  30 { $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 } "." }
  31 { $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." } ;
  32
  33 HELP: world
  34 { $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:"
  35     { $list
  36         { { $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." }
  37         { { $snippet "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." }
  38         { { $snippet "title" } " - a string to be displayed in the title bar of the native window containing the world." }
  39         { { $snippet "status" } " - a " { $link model } " holding a string to be displayed in the world's status bar." }
  40         { { $snippet "focus" } " - the current owner of the keyboard focus in the world." }
  41         { { $snippet "focused?" } " - a boolean indicating if the native window containing the world has keyboard focus." }
  42         { { $snippet "fonts" } " - a hashtable mapping font instances to vectors of " { $link sprite } " instances." }
  43         { { $snippet "handle" } " - a backend-specific native handle representing the native window containing the world, or " { $link f } " if the world is not grafted." }
  44         { { $snippet "window-loc" } " - the on-screen location of the native window containing the world. The co-ordinate system here is backend-specific." }
  45     }
  46 } ;
  47
  48 HELP: <world>
  49 { $values { "gadget" gadget } { "title" string } { "status" model } { "world" "a new " { $link world } } }
  50 { $description "Creates a new " { $link world } " delegating to the given gadget." } ;
  51
  52 HELP: find-world
  53 { $values { "gadget" gadget } { "world/f" { $maybe world } } }
  54 { $description "Finds the " { $link world } " containing the gadget, or outputs " { $link f } " if the gadget is not grafted." } ;
  55
  56 HELP: draw-world
  57 { $values { "world" world } }
  58 { $description "Redraws a world." }
  59 { $notes "This word should only be called by the UI backend. To force a gadget to redraw from user code, call " { $link relayout-1 } "." } ;
  60
  61 HELP: find-gl-context
  62 { $values { "gadget" gadget } }
  63 { $description "Makes the OpenGL context of the gadget's containing native window the current OpenGL context." }
  64 { $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." } ;
  65
  66 ARTICLE: "ui-paint-custom" "Implementing custom drawing logic"
  67 "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:"
  68 { $subsection draw-gadget* }
  69 "Custom drawing code has access to the full OpenGL API in the " { $vocab-link "opengl" } " vocabulary."
  70 $nl
  71 "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:"
  72 { $subsection find-gl-context }
  73 "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."
  74 { $subsection "ui-paint-coord" }
  75 { $subsection "gl-utilities" }
  76 { $subsection "text-rendering" } ;