1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
5 <title>javafx.scene.control</title>
6 </head>
7 <body>
8 <p>The JavaFX User Interface Controls (UI Controls or just Controls) are
9 specialized Nodes in the JavaFX Scenegraph especially suited for reuse in
10 many different application contexts. They are designed to be highly
11 customizable visually by designers and developers. They are designed to work
12 well with layout systems. Examples of prominent controls include {@link javafx.scene.control.Button Button},
13 {@link javafx.scene.control.Label Label}, {@link javafx.scene.control.ListView ListView}, and {@link javafx.scene.control.TextField TextField}.</p>
14
15 <p>Since Controls are {@link javafx.scene.Node Nodes} in the scenegraph,
16 they can be freely mixed with {@link javafx.scene.Group Groups},
17 {@link javafx.scene.image.ImageView Images},
18 {@link javafx.scene.media.MediaView Media},
19 {@link javafx.scene.text.Text Text}, and
20 {@link javafx.scene.shape.Shape basic geometric shapes}. While
21 writing new UI Controls is not trivial, using and styling them
22 is very easy, especially to existing web developers.</p>
23
24 <p>The remainder of this document will describe the basic architecture of
25 the JavaFX UI Control library, how to style existing controls, write custom
26 skins, and how to use controls to build up more complicated user interfaces.
27 </p>
28
29 <h2>Architecture</h2>
30
31 <p>Controls follow the classic MVC design pattern. The {@link javafx.scene.control.Control Control} is
32 the "model". It contains both the state and the functions which manipulate
33 that state. The Control class itself does not know how it is rendered or
34 what the user interaction is. These tasks are delegated to the
35 {@link javafx.scene.control.Skin Skin} ("view"), which may internally separate
36 out the view and controller functionality into separate classes, although
37 at present there is no public API for the "controller" aspect.</p>
38
39 <p>All Controls extend from the Control class, which is in turn a
40 {@link javafx.scene.Parent Parent} node, and which is a
41 {@link javafx.scene.Node Node}. Every Control has a reference to a single Skin, which
42 is the view implementation for the Control. The Control delegates to the
43 Skin the responsibility of computing the min, max, and pref sizes of the
44 Control, the baseline offset, and hit testing (containment and
45 intersection). It is also the responsibility of the Skin, or a delegate of
46 the Skin, to implement and repond to all relevant key
47 events which occur on the Control when it contains the focus.</p>
48
49 <h2>Control</h2>
50
51 <p>Control extends from {@link javafx.scene.Parent Parent}, and as such, is
52 not a leaf node. From the perspective of a developer or designer the Control
53 can be thought of as if it were a leaf node in many cases. For example, the
54 developer or designer can consider a Button as if it were a Rectangle or
55 other simple leaf node.</p>
56
57 <p>Since a Control is resizable, a Control
58 will be <strong>auto-sized to its preferred size</strong> on each scenegraph
59 pulse. Setting the width and height of the Control does not affect its
60 preferred size. When used in a layout container, the layout constraints
61 imposed upon the Control (or manually specified on the Control) will
62 determine how it is positioned and sized.</p>
63
64 <p>The Skin of a Control can be changed at any time. Doing so will mark the
65 Control as needing to be laid out since changing the Skin likely has changed
66 the preferred size of the Control. If no Skin is specified at the time that
67 the Control is created, then a default CSS-based skin will be provided for
68 all of the built-in Controls.</p>
69
70 <p>Each Control may have an optional tooltip specified. The Tooltip is a
71 Control which displays some (usually textual) information about the control
72 to the user when the mouse hovers over the Control from some period of time.
73 It can be styled from CSS the same as with other Controls.</p>
74
75 <p>{@code focusTraversable} is overridden in Control to be true by default,
76 whereas with Node it is false by default. Controls which should not be
77 focusable by default (such as Label) override this to be false.</p>
78
79 <p>The getMinWidth, getMinHeight, getPrefWidth, getPrefHeight, getMaxWidth,
80 and getMaxHeight functions are delegated directly to the Skin. The
81 baselineOffset method is delegated to the node of the skin. It is not
82 recommended that subclasses alter these delegations.</p>
83
84 <h2>Styling Controls</h2>
85
86 <p>There are two methods for customizing the look of a Control. The most
87 difficult and yet most flexible approach is to write a new Skin for the
88 Control which precisely implements the visuals which you
89 desire for the Control. Consult the Skin documentation for more details.</p>
90
91 <p>The easiest and yet very powerful method for styling the built in
92 Controls is by using CSS. Please note that in this release the following
93 CSS description applies only to the default Skins provided for the built
94 in Controls. Subsequent releases will make this generally available for
95 any custom third party Controls which desire to take advantage of these
96 CSS capabilities.</p>
97
98 <p>Each of the default Skins for the built in Controls is comprised of
99 multiple individually styleable areas or regions. This is much like an
100 HTML page which is made up of <div>'s and then styled from
101 CSS. Each individual region may be drawn with backgrounds, borders, images,
102 padding, margins, and so on. The JavaFX CSS support includes the ability
103 to have multiple backgrounds and borders, and to derive colors. These
104 capabilities make it extremely easy to alter the look of Controls in
105 JavaFX from CSS.</p>
106
107 <p>The colors used for drawing the default Skins of the built in Controls
108 are all derived from a base color, an accent color and a background
109 color. Simply by modifying the base color for a Control you can alter the
110 derived gradients and create Buttons or other Controls which visually fit
111 in with the default Skins but visually stand out.</p>
112
113 <p>As with all other Nodes in the scenegraph, Controls can be styled by
114 using an external stylesheet, or by specifying the style directly on the
115 Control. Although for examples it is easier to express and understand by
116 specifying the style directly on the Node, it is recommended to use an
117 external stylesheet and use either the styleClass or id of the Control,
118 just as you would use the "class" or id of an HTML element with HTML
119 CSS.</p>
120
121 <p>Each UI Control specifies a styleClass which may be used to
122 style controls from an external stylesheet. For example, the Button
123 control is given the "button" CSS style class. The CSS style class names
124 are hyphen-separated lower case as opposed to camel case, otherwise, they
125 are exactly the same. For example, Button is "button", RadioButton is
126 "radio-button", Tooltip is "tooltip" and so on.</p>
127
128 <p>The class documentation for each Control defines the default Skin
129 regions which can be styled. For further information regarding the CSS
130 capabilities provided with JavaFX, see the
131 <a href="../doc-files/cssref.html">CSS Reference Guide</a>.</p>
132 </body>
133 </html>