1 USING: ui.gadgets ui.gestures help.markup help.syntax
2 kernel classes strings opengl.gl models math.geometry.rect ;
6 { $class-description "An object which displays itself on the screen and acts on user input gestures. Gadgets have the following slots:"
8 { { $snippet "pref-dim" } " - a cached value for " { $link pref-dim } "; do not read or write this slot directly." }
9 { { $snippet "parent" } " - the gadget containing this one, or " { $link f } " if this gadget is not part of the visible gadget hierarchy." }
10 { { $snippet "children" } " - a vector of child gadgets. Do not modify this vector directly, instead use " { $link add-gadget } ", " { $link add-gadgets } ", " { $link unparent } " or " { $link clear-gadget } "." }
11 { { $snippet "orientation" } " - an orientation specifier. This slot is used by layout gadgets." }
12 { { $snippet "layout-state" } " - stores the layout state of the gadget. Do not read or write this slot directly, instead call " { $link relayout } " and " { $link relayout-1 } " if the gadget needs to be re-laid out." }
13 { { $snippet "visible?" } " - a boolean indicating if the gadget should display and receive user input." }
14 { { $snippet "root?" } " - if set to " { $link t } ", layout changes in this gadget will not propagate to the gadget's parent." }
15 { { $snippet "clipped?" } " - a boolean indicating if clipping will be enabled when drawing this gadget's children." }
16 { { $snippet "interior" } " - an object whose class implements the " { $link draw-interior } " generic word." }
17 { { $snippet "boundary" } " - an object whose class implements the " { $link draw-boundary } " generic word." }
18 { { $snippet "model" } " - a " { $link model } " or " { $link f } "; see " { $link "ui-control-impl" } }
20 "Gadgets subclass the " { $link rect } " class, and thus all instances have " { $snippet "loc" } " and " { $snippet "dim" } " instances holding their location and dimensions." }
22 "Other classes may inherit from " { $link gadget } " in order to re-implement generic words such as " { $link draw-gadget* } " and " { $link user-input* } ", or to define gestures with " { $link set-gestures } "." } ;
25 { $var-description "The current clipping rectangle." } ;
28 { $values { "gadget" gadget } }
29 { $contract "Draws the gadget by making OpenGL calls. The top-left corner of the gadget should be drawn at the location stored in the " { $link origin } " variable." }
30 { $notes "This word should not be called directly. To force a gadget to redraw, call " { $link relayout-1 } "." } ;
33 { $values { "interior" object } { "gadget" gadget } }
34 { $contract "Draws the interior of a gadget by making OpenGL calls. The " { $snippet "interior" } " slot may be set to objects implementing this generic word." } ;
37 { $values { "boundary" object } { "gadget" gadget } }
38 { $contract "Draws the boundary of a gadget by making OpenGL calls. The " { $snippet "boundary" } " slot may be set to objects implementing this generic word." } ;
41 { $class-description "A class implementing the " { $link draw-boundary } " and " { $link draw-interior } " generic words to draw a solid outline or a solid fill, respectively. The " { $snippet "color" } " slot stores a color specifier." } ;
44 { $class-description "A class implementing the " { $link draw-interior } " generic word to draw a smoothly shaded transition between colors. The " { $snippet "colors" } " slot stores a sequence of color specifiers and the gradient is drawn in the direction given by the " { $snippet "orientation" } " slot of the gadget." } ;
47 { $class-description "A class implementing the " { $link draw-boundary } " and " { $link draw-interior } " generic words to draw a solid outline or a solid filled polygon, respectively. Instances of " { $link polygon } " have two slots:"
49 { { $snippet "color" } " - a color specifier" }
50 { { $snippet "points" } " - a sequence of points" }
55 { $values { "color" "a color specifier" } { "points" "a sequence of points" } }
56 { $description "Creates a new instance of " { $link polygon } "." } ;
58 HELP: <polygon-gadget>
59 { $values { "color" "a color specifier" } { "points" "a sequence of points" } { "gadget" "a new " { $link gadget } } }
60 { $description "Creates a gadget which is drawn as a solid filled polygon. The gadget's size is the minimum bounding box containing all the points of the polygon." } ;
63 { $values { "font" "a font specifier" } { "open-font" object } }
64 { $description "Loads a font if it has not already been loaded, otherwise outputs the existing font." }
65 { $errors "Throws an error if the font does not exist." } ;
68 { $values { "open-font" "a value output by " { $link open-font } } { "string" string } { "w" "a positive integer" } }
69 { $description "Outputs the width of a string." } ;
72 { $values { "open-font" "a value output by " { $link open-font } } { "text" "a string or an array of strings" } { "dim" "a pair of integers" } }
73 { $description "Outputs the dimensions of a piece of text, which is either a single-line string or an array of lines." } ;
76 { $values { "font" "a font specifier" } { "string" string } { "loc" "a pair of integers" } }
77 { $description "Draws a line of text." } ;
80 { $values { "font" "a font specifier" } { "text" "a string or an array of strings" } { "loc" "a pair of integers" } }
81 { $description "Draws text. Text is either a single-line string or an array of lines." } ;
83 ARTICLE: "gadgets-polygons" "Polygon gadgets"
84 "A polygon gadget renders a simple shaded polygon."
85 { $subsection <polygon-gadget> }
86 "Some pre-made polygons:"
87 { $subsection arrow-up }
88 { $subsection arrow-right }
89 { $subsection arrow-down }
90 { $subsection arrow-left }
91 { $subsection close-box }
92 "Polygon gadgets are rendered by the " { $link polygon } " pen protocol implementation." ;
94 ARTICLE: "ui-paint" "Customizing gadget appearance"
95 "The UI carries out the following steps when drawing a gadget:"
97 { "The " { $link draw-interior } " generic word is called on the value of the " { $snippet "interior" } " slot." }
98 { "The " { $link draw-gadget* } " generic word is called on the gadget." }
99 { "The gadget's visible children are drawn, determined by calling " { $link visible-children } " on the gadget." }
100 { "The " { $link draw-boundary } " generic word is called on the value of the " { $snippet "boundary" } " slot." }
102 "Now, each one of these steps will be covered in detail."
103 { $subsection "ui-pen-protocol" }
104 { $subsection "ui-paint-custom" } ;
106 ARTICLE: "ui-pen-protocol" "UI pen protocol"
107 "The " { $snippet "interior" } " and " { $snippet "boundary" } " slots of a gadget facilitate easy factoring and sharing of drawing logic. Objects stored in these slots must implement the pen protocol:"
108 { $subsection draw-interior }
109 { $subsection draw-boundary }
110 "The default value of these slots is the " { $link f } " singleton, which implements the above protocol by doing nothing."
112 "Some other pre-defined implementations:"
113 { $subsection solid }
114 { $subsection gradient }
115 { $subsection polygon }
116 "Custom implementations must follow the guidelines set forth in " { $link "ui-paint-custom" } "." ;
118 ARTICLE: "text-rendering" "Rendering text"
119 "Unlike OpenGL, Factor's FreeType binding only includes the bare essentials, and there is rarely any need to directly call words in the " { $vocab-link "freetype" } " vocabulary directly. Instead, the UI provides high-level wrappers."
121 "Font objects are never constructed directly, and instead are obtained by calling a word:"
122 { $subsection open-font }
124 { $subsection text-dim }
125 { $subsection text-height }
126 { $subsection text-width }
128 { $subsection draw-string }
129 { $subsection draw-text } ;
131 ARTICLE: "ui-paint-custom" "Implementing custom drawing logic"
132 "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:"
133 { $subsection draw-gadget* }
134 "Custom drawing code has access to the full OpenGL API in the " { $vocab-link "opengl" } " vocabulary."
136 "The UI uses a co-ordinate system where the y axis is oriented down. The OpenGL " { $link GL_MODELVIEW } " matrix is not saved or restored when rendering a gadget. Instead, the origin of the gadget relative to the OpenGL context is stored in a variable:"
137 { $subsection origin }
138 "Custom drawing implementations can translate co-ordinates manually, or save and restore the " { $link GL_MODELVIEW } " matrix."
140 "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."
142 "Gadgets must not draw outside of their bounding box, however clipping is not enforced by default, for performance reasons. This can be changed by setting the " { $snippet "clipped?" } " slot to " { $link t } " in the gadget's constructor."
144 "Saving the " { $link GL_MODELVIEW } " matrix and enabling/disabling flags can be done in a clean way using the combinators documented in the following section."
145 { $subsection "gl-utilities" }
146 { $subsection "text-rendering" } ;
148 ABOUT: "ui-paint-custom"