{ $var-description "Within the dynamic extent of " { $link draw-world } ", holds the co-ordinate system origin for the gadget currently being drawn." } ;
HELP:hand-world
{ $var-description "Global variable. The " { $link world } " containing the gadget at the mouse location." } ;
{ $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 } "." } ;
{ $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." } ;
{ $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 } "." } ;
{ $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." } ;
{ $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:"
{ "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." }
{ "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" } "." }
}
{
{ $slot "title" }
{ "a string to be displayed in the title bar of the native window containing the world." }
}
{
{ $slot "status" }
{ "a " { $link model } " holding a string to be displayed in the world's status bar." }
}
{
{ $slot "status-owner" }
{ "the gadget that displayed the most recent status message." }
}
{
{ $slot "focus" }
{ "the current owner of the keyboard focus in the world." }
}
{
{ $slot "focused?" }
{ "a boolean indicating if the native window containing the world has keyboard focus." }
}
{
{ $slot "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." }
}
{
{ $slot "handle" }
{ "a backend-specific native handle representing the native window containing the world, or " { $link f } " if the world is not grafted." }
}
{
{ $slot "window-loc" }
{ "the on-screen location of the native window containing the world. The co-ordinate system here is backend-specific." }
}
{
{ $slot "window-controls" }
{ "the set of " { $link "ui.gadgets.worlds-window-controls" } " with which the world window was created." }
{ $description "Makes the OpenGL context of the gadget's containing native window the current OpenGL context." }
{ $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." } ;
{ $description "Called immediately after " { $snippet "world" } "'s OpenGL context has been created. The world's OpenGL context is current when this method is called." } ;
HELP:end-world
{ $values { "world" world } }
{ $description "Called immediately before " { $snippet "world" } "'s OpenGL context is destroyed. The world's OpenGL context is current when this method is called." } ;
HELP:resize-world
{ $values { "world" world } }
{ $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." } ;
HELP:draw-world*
{ $values { "world" world } }
{ $description "Called when " { $snippet "world" } " needs to be redrawn. The world's OpenGL context is current when this method is called." } ;
"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:"
"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:"
"Custom drawing code has access to the full OpenGL API in the " { $vocab-link "opengl" } " vocabulary."
$nl
"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:"
"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" } "."
