06/08/13Introduction to FXML | JavaFX 2.2 R e le ase : JavaFX 2.2 Introduction to FXML Last updated: 6/21/2012 Contents Overview Elements Class Instance Elements Instance Declarations <fx:include> <fx:constant> <fx:reference> <fx:copy> <fx:root> Property Elements Property Setters Read-Only List Properties Read-Only Map Properties Default Properties Static Properties Define Blocks Attributes Instance Properties Location Resolution Resource Resolution Variable Resolution Escape Sequences Expression Binding Static Properties Event Handlers Script Event Handlers Controller Method Event Handlers Scripting Controllers @FXML Nested Controllers FXMLLoader Custom Components Overview FXML is a scriptable, XML-based markup language for constructing Java object graphs. It provides a convenient alternative to constructing such graphs in procedural code, and is ideally suited to defining the user interface of a JavaFX application, since the hierarchical structure of an XML document closely parallels the structure of the JavaFX scene graph. This document introduces the FXML markup language and explains how it can be used to simplify development of JavaFX applications. docs.oracle.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml.html 1/15 or they can be imported using the "import" processing instruction (PI). L a b e lclass into the current FXML document’s namespace: < ? i m p o r tj a v a f x . s c e n e . For example. For example. Scripting is discussed in a later section. Property elements are discussed in more detail later in this section. Properties can also be set using nested property elements. u t i l .oracle. f x m l . the following PI imports the j a v a f x . L a b e land sets its "text" property to "Hello. s c e n e . copying existing values. it is not wrapped and its g e t ( )and p u t ( )methods are invoked directly. c o n t r o l . l a n g .scene. L a b e l ? > This PI imports all classes from the javafx. Instance Declarations If an element's tag name begins with an uppercase letter (and it is not a "static" property setter. u t i l . Builders are discussed in more detail later. S t r i n gas well as each of the primitive wrapper types define a v a l u e O f ( )method and can be constructed in FXML as follows: docs. Class Instance Elements Class instances can be constructed in FXML in several ways. an XML element represents one of the following: A class instance A property of a class instance A "static" property A "define" block A block of script code Class instances.06/08/13 Introduction to FXML | JavaFX 2. the FXML loader uses an instance of c o m . the following FXML creates an instance of H a s h M a pand sets its "foo" and "bar" values to "123" and "456".html 2/15 . c o n t r o l . s c e n e .com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. j a v a . If an element represents a type that already implements M a p(such as j a v a .W o r l d ! " / > Note that the L a b e l ’s "text" property in this example is set using an XML attribute. World!": < ? i m p o r tj a v a f x . which simply create a new instance of a class by name. The most common is via instance declaration elements. As in Java. Classes that don't conform to Bean conventions can also be constructed in FXML.control package into the current namespace: < ? i m p o r tj a v a f x . respectively: < H a s h M a pf o o = " 1 2 3 "b a r = " 4 5 6 " / > fx:value The f x : v a l u eattribute can be used to initialize an instance of a type that does not have a default constructor but provides a static v a l u e O f ( S t r i n g )method. Each is discussed in more detail below. it creates an instance of that class. H a s h M a p ). it is considered an instance declaration. j a v a f x . This (currently) private class implements the j a v a . B e a n A d a p t e rto wrap an instantiated object and invoke its setter methods. static properties. class names can be fully-qualified (including the package name). and including external FXML files. s c e n e . and define blocks are discussed in this section below. using an object called a "builder". s u n . Maps Internally. c o n t r o l . instance properties. described later). Other ways of creating class instances include referencing existing values. s c e n e . When the FXML loader (also introduced later) encounters such an element. c o n t r o l . The following is a simple but complete example that creates an instance of j a v a f x . c o n t r o l .2 Elements In FXML. M a pinterface and allows a caller to get and set Bean property values as key/value pairs. L a b e l ? > < L a b e lt e x t = " H e l l o . For example. * ? > Any class that adheres to JavaBean constructor and property naming conventions can be readily instantiated and configured using FXML. Property attributes are discussed in a later section. 2 < S t r i n gf x : v a l u e = " H e l l o . objects constructed by a builder are not instantiated until the element's closing tag is reached.06/08/13 Introduction to FXML | JavaFX 2. B u i l d e rinterface defines a single method named b u i l d ( )which is responsible for constructing the actual object: p u b l i ci n t e r f a c eB u i l d e r < T >{ p u b l i cTb u i l d ( ) . This factory is capable of creating and configuring most immutable JavaFX types.html 3/15 . s c e n e . B u i l d e r F a c t o r yis responsible for producing builders that are capable of instantiating a given type: p u b l i ci n t e r f a c eB u i l d e r F a c t o r y{ p u b l i cB u i l d e r < ? >g e t B u i l d e r ( C l a s s < ? >t y p e ) . For example. Values with no leading slash are considered relative to the path of the current document. 0 < / r e d > < g r e e n > 0 .if a B u i l d e rimplements the M a pinterface. The j a v a f x . is provided in the j a v a f x . 0 < / b l u e > < / C o l o r > The C o l o rinstance cannot be fully constructed until all three of the color components are known. f x m lpackage.oracle. unlike Bean types. J a v a F X B u i l d e r F a c t o r y . p a i n t . Otherwise. 0 " / > < B o o l e a nf x : v a l u e = " f a l s e " / > Custom classes that define a static v a l u e O f ( S t r i n g )method can also be constructed this way. <fx:include> The < f x : i n c l u d e >tag creates an object from FXML markup defined in another file. the p u t ( )method is used to set the builder's attribute values. u t i l . the following markup uses the default builder to create an instance of the immutable j a v a f x . the builder is wrapped in a B e a n A d a p t e rand its properties are assumed to be exposed via standard Bean setters. the following markup creates an instance of an observable array list. no-arg factory method for producing class instances. 0 "b l u e = " 0 . u t i l . C o l o rclass: < C o l o rr e d = " 1 . For example. the Color object in the preceding example could also be written as: < C o l o r > < r e d > 1 . 0 "g r e e n = " 0 . For example.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. docs. It is used as follows: < f x : i n c l u d es o u r c e = " f i l e n a m e " / > where filename is the name of the FXML file to include. Builder support in FXML is provided by two interfaces. which are constructed when the element's start tag is processed. When processing markup for an object that will be constructed by a builder.W o r l d ! " / > < D o u b l ef x : v a l u e = " 1 . } A default builder factory. 0 " / > Note that. populated with three string values: < F X C o l l e c t i o n sf x : f a c t o r y = " o b s e r v a b l e A r r a y L i s t " > < S t r i n gf x : v a l u e = " A " / > < S t r i n gf x : v a l u e = " B " / > < S t r i n gf x : v a l u e = " C " / > < / F X C o l l e c t i o n s > Builders A third means of creating instances of classes that do not conform to Bean conventions (such as those representing immutable values) is a "builder". 0 < / g r e e n > < b l u e > 0 . Values that begin with a leading slash character are treated as relative to the classpath. the B u i l d e rinstances are treated like value objects . fx:factory The f x : f a c t o r yattribute is another means of creating objects whose classes do not have a default constructor. } Aj a v a f x . The value of the attribute is the name of a static. The builder design pattern delegates object construction to a mutable helper class (called a "builder") that is responsible for manufacturing instances of the immutable type. This is because all of the required arguments may not be available until the element has been fully processed. Note the use of the "fx" namespace prefix. c o n t r o l . the following markup assigns a previously-defined I m a g einstance named "myImage" to the "image" property of an I m a g e V i e wcontrol: < I m a g e V i e w > < i m a g e > < f x : r e f e r e n c es o u r c e = " m y I m a g e " / > < / i m a g e > < / I m a g e V i e w > Note that. docs. s c e n e . <fx:copy> The < f x : c o p y >element creates a copy of an existing element.oracle. f x m lcontains the following: < ? i m p o r tj a v a f x . The source type must define a copy constructor that will be used to construct the copy from the source value. * ? > < B u t t o nt e x t = " M yB u t t o n " / > the resulting scene graph would contain a V B o xas a root object with a single B u t t o nas a child node. c o m / f x m l " > < c h i l d r e n > < f x : i n c l u d es o u r c e = " m y _ b u t t o n . * ? > < ? i m p o r tj a v a f x . Resource resolution is discussed in a later section. such as when adding the reference to a collection: < A r r a y L i s t > < f x : r e f e r e n c es o u r c e = " e l e m e n t 1 " / > < f x : r e f e r e n c es o u r c e = " e l e m e n t 2 " / > < f x : r e f e r e n c es o u r c e = " e l e m e n t 3 " / > < / A r r a y L i s t > For most other cases. it is used with the fx:id attribute or a script variable. It is used in conjunction with either the f x : i dattribute or with a script variables. s c e n e . * ? > < V B o xx m l n s : f x = " h t t p : / / j a v a f x . the following markup sets the value of the "minWidth" property of aB u t t o ninstance to the value of the N E G A T I V E _ I N F I N I T Yconstant defined by the j a v a .com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. Wherever this tag appears. s c e n e . Other features provided by the "fx" namespace are described in the following sections. The "source" attribute of the < f x : r e f e r e n c e >element specifies the name of the object to which the new element will refer. l a y o u t . f x : r e f e r e n c eis generally only used when a reference value must be specified as an element. given the following markup: < ? i m p o r tj a v a f x . D o u b l eclass: < B u t t o n > < m i n H e i g h t > < D o u b l ef x : c o n s t a n t = " N E G A T I V E _ I N F I N I T Y " / > < / m i n H e i g h t > < / B u t t o n > <fx:reference> The < f x : r e f e r e n c e >element creates a new reference to an existing element. f x m l " / > < / c h i l d r e n > < / V B o x > If m y _ b u t t o n .html 4/15 . using an attribute is simpler and more concise. This is a reserved prefix that defines a number of elements and attributes that are used for internal processing of an FXML source file. <fx:constant> The < f x : c o n s t a n t >element creates a reference to a class constant. It is generally declared on the root element of a FXML document. For example. < f x : i n c l u d e >also supports attributes for specifying the name of the resource bundle that should be used to localize the included content. c o n t r o l . Like < f x : r e f e r e n c e > .2 For example. both of which are discussed in more detail in later sections. l a n g . it will effectively be replaced by the value of the named element. as well as the character set used to encode the source file. since it is also possible to dereference a variable using the attribute variable resolution operator (discussed later in the Attributes section).06/08/13 Introduction to FXML | JavaFX 2. For example. The element's "source" attribute specifies the name of the object that will be copied. W o r l d ! " / > Property elements are generally used when the property value is a complex type that can't be represented using a simple string-based attribute value. < f x : r o o t >is used primarily when creating custom controls that are backed by FXML markup. the following FXML creates an instance of the L a b e lclass and sets the value of the label's "text" property to "Hello.W o r l d ! < / t e x t > < / L a b e l > This produces the same result as the earlier example which used an attribute to set the "text" property: < ? i m p o r tj a v a f x . s c e n e . World!": < ? i m p o r tj a v a f x . L i s tand has no corresponding setter method. so this element is provided primarily for use by application developers.html 5/15 . A property element may represent one of the following: A property setter A read-only list property A read-only map property Property Setters If an element represents a property setter. This may change in a future release. s c e n e . The contents of a read-only list element are automatically added to the list as they are processed.2 At the moment.06/08/13 Introduction to FXML | JavaFX 2. or when the character length of the value is so long that specifying it as an attribute would have a negative impact on readability. * ? > < G r o u px m l n s : f x = " h t t p : / / j a v a f x . This is discussed in more detail in the FXMLLoader section. s c e n e . and will also convert S t r i n gto C l a s sor S t r i n gto E n u m . However. no JavaFX platform classes provide such a copy constructor. The FXML loader uses the c o e r c e ( )method of B e a n A d a p t e rto perform any required type conversions.oracle. s c e n e . Property Elements Elements whose tag names begin with a lowercase letter represent object properties. L a b e l ? > < L a b e l > < t e x t > H e l l o . c o n t r o l . For example. the "children" property of j a v a f x . and attributes (whose values are also text). Type Coercion FXML uses "type coercion" to convert property values to the appropriate type as needed.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. c o m / f x m l " > < c h i l d r e n > < R e c t a n g l ef x : i d = " r e c t a n g l e "x = " 1 0 "y = " 1 0 "w i d t h = " 3 2 0 "h e i g h t = " 2 4 0 " f i l l = " # f f 0 0 0 0 " / > docs. s c e n e . c o n t r o l . * ? > < ? i m p o r tj a v a f x . Additional conversions can be implemented by defining a static v a l u e O f ( )method on the target type. Read-Only List Properties A read-only list property is a Bean property whose getter returns an instance of j a v a . text. Type coercion is required because the only data types supported by XML are elements. Java supports a number of different data types including built-in primitive value types as well as extensible reference types. G r o u pis a read-only list property representing the group's child nodes: < ? i m p o r tj a v a f x . u t i l . It is only valid as the root node of an FXML document. <fx:root> The < f x : r o o t >element creates a reference to a previously defined root element. For example. L a b e l ? > < L a b e lt e x t = " H e l l o . the contents of the element (which must be either a text node or a nested class instance element) are passed as the value to the setter for the property. s h a p e . This method is capable of performing basic primitive type conversions such as S t r i n gto b o o l e a nor i n tto d o u b l e . . s c e n e .2 . . Static properties are properties that only make sense in a particular context. u t i l . For example. s h a p e . V B o x ) defines a default property of "children". < / c h i l d r e n > < / G r o u p > As each sub-element of the < c h i l d r e n >element is read. c o n t r o l . Static properties are prefixed with the name of class that defines them.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. s c e n e . the loader will automatically add the sub-elements of the V B o xto the container's "children" collection: < ? i m p o r tj a v a f x . s c e n e . If an element's default property refers to a scalar value. s c e n e . The "properties" property of j a v a f x . For example. r o w I n d e x > < G r i d P a n e . l a y o u t . Static Properties An element may also represent a "static" property (sometimes called an "attached property"). the parent container of a control). . any sub-element of that element will be set as the value of the property. * ? > < V B o xx m l n s : f x = " h t t p : / / j a v a f x . The following FXML invokes the static setter for G r i d P a n e 's "rowIndex" and "columnIndex" properties: < G r i d P a n e > < c h i l d r e n > < L a b e lt e x t = " M yL a b e l " > < G r i d P a n e . * ? > < B u t t o n > < p r o p e r t i e sf o o = " 1 2 3 "b a r = " 4 5 6 " / > < / B u t t o n > Note that a read-only property whose type is neither a L i s tnor a M a pwill be treated as if it were a read-only map. c o l u m n I n d e x > < / L a b e l > < / c h i l d r e n > docs. For example. The following markup sets the "foo" and "bar" properties of a L a b e linstance to "123" and "456".html 6/15 . The attributes of a read-only map element are applied to the map when the closing tag is processed. l a y o u t . respectively: < ? i m p o r tj a v a f x . a < c h i l d r e n >element is not required. N o d eis an example of a read-only map property. Default Properties A class may define a "default property" using the @ D e f a u l t P r o p e r t yannotation defined in the j a v a f x . They are not intrinsic to the class to which they are applied. The return value of the getter method will be wrapped in a B e a n A d a p t e rand can be used in the same way as any other read-only map. P a n e(the superclass of j a v a f x . s c e n e . it is added to the list returned by G r o u p # g e t C h i l d r e n ( ) . but are defined by another class (often. b e a n s package.06/08/13 Introduction to FXML | JavaFX 2. Read-Only Map Properties A read-only map property is a bean property whose getter returns an instance of j a v a . s c e n e . S c r o l l P a n edefines a default property of "content". since j a v a f x . r o w I n d e x > 0 < / G r i d P a n e . < / V B o x > Note that default properties are not limited to collections. . . " / > < / S c r o l l P a n e > Taking advantage of default properties can significantly reduce the verbosity of FXML markup. M a pand has no corresponding setter method.oracle. c o n t r o l . c o m / f x m l " > < B u t t o nt e x t = " C l i c kM e ! " / > . the sub-element representing the default property can be omitted from the markup. . c o l u m n I n d e x > 0 < / G r i d P a n e . s c e n e . a scroll pane containing a T e x t A r e aas its content can be specified as follows: < S c r o l l P a n e > < T e x t A r e at e x t = " O n c eu p o nat i m e . * ? > < ? i m p o r tj a v a f x . If present. since j a v a f x . s e t C o l u m n I n d e x ( l a b e l . s e t T e x t ( " M yL a b e l " ) .0 ) . c o n t r o l . s e t R o w I n d e x ( l a b e l .B o r d e r P a n e . attributes can also be used to configure the properties of a class instance. when working with radio buttons. including A n c h o r P a n e . "y". "width". a d d ( l a b e l ) . so should not be added to the buttons' parent.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. static property elements are generally used when the property value cannot be efficiently represented by an attribute value. For example. g r i d P a n e . For example. As with instance properties. * ? > < B u t t o nt e x t = " C l i c kM e ! " / > As with property elements. G r i d P a n ethen uses these during layout to arrange its children appropriately. the "x". A define block can be used to create the button group without interfering with the overall structure of the document: < V B o x > < f x : d e f i n e > < T o g g l e G r o u pf x : i d = " m y T o g g l e G r o u p " / > < / f x : d e f i n e > < c h i l d r e n > < R a d i o B u t t o nt e x t = " A "t o g g l e G r o u p = " $ m y T o g g l e G r o u p " / > < R a d i o B u t t o nt e x t = " B "t o g g l e G r o u p = " $ m y T o g g l e G r o u p " / > < R a d i o B u t t o nt e x t = " C "t o g g l e G r o u p = " $ m y T o g g l e G r o u p " / > < / c h i l d r e n > < / V B o x > Elements in define blocks are usually assigned an ID that can be used to refer to the element's value later. it is common to define a T o g g l e G r o u pthat will manage the buttons' selection state. define similar properties. The calls to G r i d P a n e # s e t R o w I n d e x ( )and G r i d P a n e # s e t C o l u m n I n d e x ( )"attach" the index data to the L a b e l instance. G r i d P a n e . L a b e ll a b e l=n e wL a b e l ( ) . Other containers.oracle. Otherwise. and the "fill" value will be converted to a C o l o r : docs. Instance Properties Like property elements. Attributes An attribute in FXML may represent one of the following: A property of a class instance A "static" property An event handler Each are discussed in more detail in the following sections. s c e n e . property attributes support type coercion.0 ) .2 < / T a b P a n e > This translates roughly to the following in Java: G r i d P a n eg r i d P a n e=n e wG r i d P a n e ( ) . When the following markup is processed. and "height" values will be converted to doubles. IDs are discussed in more detail in later sections. Define Blocks The < f x : d e f i n e >element is used to create objects that exist outside of the object hierarchy but may need to be referred to elsewhere. g e t C h i l d r e n ( ) . the following markup creates a B u t t o nwhose text reads "Click Me!": < ? i m p o r tj a v a f x . static property attributes (discussed in a later section) will generally produce more concise and readable markup. G r i d P a n e . l a b e l .html 7/15 . This group is not part of the scene graph itself. and S t a c k P a n e .06/08/13 Introduction to FXML | JavaFX 2. The location resolution operator (represented by an "@" prefix to the attribute value) is used to specify that an attribute value should be treated as a location relative to the current file rather than a simple string. Variable Resolution An FXML document defines a variable namespace in which named elements and script variables may be uniquely identified. a builder is required to construct it. Resource names are identified by a "%" prefix. resource substitution can be performed at load time for localization purposes. as shown below: < f x : d e f i n e > < T o g g l e G r o u pf x : i d = " m y T o g g l e G r o u p " / > < / f x : d e f i n e > . The following operators are supported and are discussed in more detail below: Location resolution Resource resolution Variable resolution Location Resolution As strings.2 < R e c t a n g l ef x : i d = " r e c t a n g l e "x = " 1 0 "y = " 1 0 "w i d t h = " 3 2 0 "h e i g h t = " 2 4 0 " f i l l = " # f f 0 0 0 0 " / > Unlike property elements.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. Another key difference between property attributes and property elements in FXML is that attributes support a number of "resolution operators" that extend their functionality. which can't be set until all of the tabs have been added). p n g " / > < / i m a g e > < / I m a g e V i e w > Since I m a g eis an immutable object. which is assumed to be located at a path relative to the current FXML file: < I m a g e V i e w > < i m a g e > < I m a g eu r l = " @ m y _ i m a g e . Alternatively. Resource Resolution In FXML. then coerced to an I m a g eusing the v a l u e O f ( )method. Variable references are identified by a "$" prefix. XML attributes cannot natively represent typed location information such as a URL. p n g . For example. property attributes are not applied until the closing tag of their respective element is reached. . the source of an image resource. it is often necessary to specify such locations in markup.html 8/15 . < R a d i o B u t t o nt e x t = " A "t o g g l e G r o u p = " $ m y T o g g l e G r o u p " / > < R a d i o B u t t o nt e x t = " B "t o g g l e G r o u p = " $ m y T o g g l e G r o u p " / > < R a d i o B u t t o nt e x t = " C "t o g g l e G r o u p = " $ m y T o g g l e G r o u p " / > docs. R e s o u r c e B u n d l e . the selected index of a T a b P a n econtrol. This is done primarily to facilitate the case where an attribute value depends on some information that won't be available until after the element's content has been completely processed (for example. The variable resolution operator allows a caller to replace an attribute value with an instance of a named object before the corresponding setter method is invoked. When provided with an instance of j a v a . p n g " / > The value of the "image" attribute would be converted to a URL by the FXML loader. the FXML loader will replace instances of resource names with their localespecific values.oracle. u t i l . However. which are applied as they are processed.06/08/13 Introduction to FXML | JavaFX 2. as shown below: < L a b e lt e x t = " % m y T e x t " / > If the loader is given a resource bundle defined as follows: m y T e x t=T h i si st h et e x t ! the output of the FXML loader would be a L a b e linstance containing the text "This is the text!". . if I m a g ewere to define a v a l u e O f ( U R L )factory method. the following markup creates an ImageView and populates it with image data from m y _ i m a g e . the image view could be populated as follows: < I m a g e V i e wi m a g e = " @ m y _ i m a g e . for example. t e x t } " / > As the user types in the text input.06/08/13 Introduction to FXML | JavaFX 2. this is sufficient. In many cases. the only limitation being that it is not possible to create an expression binding to a static property. c o l u m n I n d e x = " 0 " / > < / c h i l d r e n > < / T a b P a n e > In addition to being more concise. the label's text content will be automatically updated. the following markup binds the value of a text input's "text" property to the "text" property of a L a b e linstance: < T e x t F i e l df x : i d = " t e x t F i e l d " / > < L a b e lt e x t = " $ { t e x t F i e l d . . Each are discussed below. but is followed by a set of curly braces which wrap the expression value. For example. such as the "toggleGroup" attribute shown above. the character can be escaped by prepending it with a leading backslash ("\") character. For example. FXML supports two types of event handler attributes: script event handlers and controller method event handlers. Additionally.oracle. Escape Sequences If the value of an attribute begins with one of the resource resolution prefixes. For example. or in script code. support location. For example. resource. Event Handlers Event handler attributes are a convenient means of attaching behaviors to document elements. 0 0 " / > Expression Binding Attribute variables as shown above are resolved once at load time. Support for more complex expressions involving boolean or other operators may be added in the future.00": < L a b e lt e x t = " \ $ 1 0 . this value will also be passed to the objects s e t I d ( )method. the following script-based handler for the button's "onAction" event uses JavaScript to write the text "You clicked me!" to the console when the user presses the button: < ? l a n g u a g ej a v a s c r i p t ? > . An expression binding also begins with the variable resolution operator. similar to event handlers in HTML. Static Properties Attributes representing static properties are handled similarly to static property elements and use a similar syntax. . discussed in a later section.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. the following markup creates a L a b e linstance whose text reads "$10. Later updates to the variables value are not automatically reflected in any properties to which the value was assigned. like instance property attributes. if the object's type defines an "id" property. static property attributes.2 Assigning an f x : i dvalue to an element creates a variable in the document's namespace that can later be referred to by variable dereference attributes. Script Event Handlers A script event handler is an event handler that executes script code when the event is fired. the earlier G r i d P a n emarkup shown earlier to demonstrate static property elements could be rewritten as follows: < G r i d P a n e > < c h i l d r e n > < L a b e lt e x t = " M yL a b e l "G r i d P a n e . r o w I n d e x = " 0 "G r i d P a n e . as can any observable property (via an "onPropertyChange" attribute). < V B o x > docs. it is often convenient to "bind" a property value to a variable or expression such that changes to the variable are automatically propagated to the target property. Only simple expressions that resolve to property values or page variables are currently supported. however. Expression bindings can be used for this purpose. and variable resolution operators. Any class that defines as e t O n E v e n t ( )method can be assigned an event handler in markup.html 9/15 . c o n t r o l .oracle. Controllers are discussed in more detail in a later section. this does not apply to external scripts. c o m / f x m l " > < c h i l d r e n > < B u t t o nt e x t = " C l i c kM e ! "o n A c t i o n = " # h a n d l e B u t t o n A c t i o n " / > < / c h i l d r e n > < / V B o x > Note the use of the f x : c o n t r o l l e rattribute on the root element. which may be implemented using any number of supported scripting languages. However. p r i n t l n ( " Y o uc l i c k e dm e ! " ) . and Clojure. o u t . In general. l a n g . p u b l i cc l a s sM y C o n t r o l l e r{ p u b l i cv o i dh a n d l e B u t t o n A c t i o n ( A c t i o n E v e n te v e n t ){ S y s t e m . the following markup defines a function called h a n d l e B u t t o n A c t i o n ( )that is called by the action handler attached to the B u t t o nelement: < ? l a n g u a g ej a v a s c r i p t ? > < ? i m p o r tj a v a f x . f o o . S y s t e m . For example: < V B o xf x : c o n t r o l l e r = " c o m . For example.2 < c h i l d r e n > < B u t t o nt e x t = " C l i c kM e ! " o n A c t i o n = " j a v a . e v e n t . M y C o n t r o l l e r " x m l n s : f x = " h t t p : / / j a v a f x .html 10/15 . If M y C o n t r o l l e ris defined as follows: p a c k a g ec o m . f o o . E v e n tand should return void (similar to an event delegate in C#). " / > < / c h i l d r e n > < / V B o x > Note the use of the language processing instruction at the beginning of the code snippet. s c e n e . and can only be specified once per document.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. a handler method should conform to the signature of a standard event handler. This attribute is used to associate a controller class with the document. including JavaScript.06/08/13 Introduction to FXML | JavaFX 2. it should take a single argument of a type that extends j a v a f x . Scripting The < f x : s c r i p t >tag allows a caller to import scripting code into or embed script within a FXML file. A page language must be specified whenever inline script is used in an FXML document. among others. This PI tells the FXML loader which scripting language should be used to execute the event handler. Script code is often used to define event handlers directly in markup or in an associated source file. that is. The event argument often carries important and useful information about the nature of the event. A controller method event handler is specified by a leading hash symbol followed by the name of the handler method. c o m / f x m l " > < f x : s c r i p t > docs. * ? > < V B o xx m l n s : f x = " h t t p : / / j a v a f x . l a y o u t . it is optional and may be omitted if desired. Any JVM scripting language can be used. p r i n t l n ( ' Y o uc l i c k e dm e ! ' ) . A controller is an object that is associated with the deserialized contents of an FXML document and is responsible for coordinating the behaviors of the objects (often user interface elements) defined by the document. Scripting is discussed in more detail in the next section. Controller Method Event Handlers A controller method event handler is a method defined by a document's "controller". Groovy. s c e n e . and the text "You clicked me!" will be written to the console. however. o u t . since event handlers can often be written more concisely in more loosely-typed scripting languages than they can in a statically-typed language such as Java. * ? > < ? i m p o r tj a v a f x . } } the h a n d l e B u t t o n A c t i o n ( )will be called when the user presses the button. < / f x : s c r i p t > . " / > < / c h i l d r e n > < / V B o x > Clicking the button triggers the event handler. s c e n e .06/08/13 Introduction to FXML | JavaFX 2. } < / f x : s c r i p t > < c h i l d r e n > < B u t t o nt e x t = " C l i c kM e ! "o n A c t i o n = " h a n d l e B u t t o n A c t i o n ( e v e n t ) . so it can also be used to dynamically configure the structure of the resulting output. o u t . since many text editors support syntax highlighting for the various scripting languages supported by the JVM.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. p r i n t l n ( ' Y o uc l i c k e dm e ! ' ) . Script code may also be defined in external files. As a simple example.html 11/15 . } It is often preferable to separate code from markup in this way. Script code is executed as it is processed. strongly-typed language such as Java. f u n c t i o nh a n d l e B u t t o n A c t i o n ( e v e n t ){ S y s t e m . . l a n g . controllers are often used to implement event handlers for user interface elements defined in markup: docs. the f x : c o n t r o l l e rattribute allows a caller to associate a "controller" class with an FXML document. . As discussed earlier. which invokes the function. s c e n e . " . the following FXML includes a script block that defines a variable named "labelText". The previous example could be split into an FXML file and a JavaScript source file with no difference in functionality: example. producing output identical to the previous examples. * ? > < ? i m p o r tj a v a f x .fxml < ? i m p o r tj a v a f x . p r i n t l n ( ' Y o uc l i c k e dm e ! ' ) . " / > < / c h i l d r e n > < / V B o x > example. l a n g . l a y o u t .oracle. S y s t e m ) .js i m p o r t C l a s s ( j a v a . either inline or defined in external files. The value of this variable is used to populate the text property of a L a b e linstance: < f x : s c r i p t > v a rm y T e x t=" T h i si st h et e x to fm yl a b e l . c o n t r o l . As shown earlier. < L a b e lt e x t = " $ m y T e x t " / > Controllers While it can be convenient to write simple event handlers in script. Note that script blocks are not limited to defining event handler functions. c o m / f x m l " > < f x : s c r i p ts o u r c e = " e x a m p l e . j s " / > < c h i l d r e n > < B u t t o nt e x t = " C l i c kM e ! "o n A c t i o n = " h a n d l e B u t t o n A c t i o n ( e v e n t ) . It can also help improve readability of the source code and markup. f u n c t i o nh a n d l e B u t t o n A c t i o n ( e v e n t ){ S y s t e m .2 i m p o r t C l a s s ( j a v a . o u t . A controller is a compiled class that implements the "code behind" the object hierarchy defined by the document. S y s t e m ) . it is often preferable to define more complex application logic in a compiled. * ? > < V B o xx m l n s : f x = " h t t p : / / j a v a f x . the controllers from the previous examples could be rewritten as follows: p a c k a g ec o m . f o o . when more control over the behavior of the controller and the elements it manages is required. o u t . it is sufficient to simply declare event handlers in this manner.html 12/15 . c o m / f x m l " > < c h i l d r e n > < B u t t o nf x : i d = " b u t t o n "t e x t = " C l i c kM e ! " / > < / c h i l d r e n > < / V B o x > p a c k a g ec o m . The button instance variable is injected by the loader as the document is read.oracle. This allows the implementing class to perform any necessary post-processing on the content. M y C o n t r o l l e r " x m l n s : f x = " h t t p : / / j a v a f x . p u b l i cc l a s sM y C o n t r o l l e r{ p u b l i cv o i dh a n d l e B u t t o n A c t i o n ( A c t i o n E v e n te v e n t ){ S y s t e m . the j a v a f x . However. f o o . in the previous examples. this is not often an issue. f x m l . the controller can define an i n i t i a l i z e ( ) method. o u t . p u b l i cc l a s sM y C o n t r o l l e r{ @ F X M L p r i v a t ev o i dh a n d l e B u t t o n A c t i o n ( A c t i o n E v e n te v e n t ){ S y s t e m .com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. } } ) . f o o . For example. p r i n t l n ( " Y o uc l i c k e dm e ! " ) . as was done in the previous example. the controller member fields and event handler methods were declared as public so they can be set or invoked by the loader. p u b l i cc l a s sM y C o n t r o l l e ri m p l e m e n t sI n i t i a l i z a b l e{ p u b l i cB u t t o nb u t t o n . F X M Lannotation can be used. This annotation marks a protected or private class member as accessible to FXML. docs. For example. p r i n t l n ( " Y o uc l i c k e dm e ! " ) . It also provides the controller with access to the resources that were used to load the document and the location that was used to resolve relative paths within the document (commonly equivalent to the location of the document itself). } } @FXML Note that. } } In many cases. c o m / f x m l " > < c h i l d r e n > < B u t t o nt e x t = " C l i c kM e ! "o n A c t i o n = " # h a n d l e B u t t o n A c t i o n " / > < / c h i l d r e n > < / V B o x > p a c k a g ec o m . However. M y C o n t r o l l e r " x m l n s : f x = " h t t p : / / j a v a f x . @ O v e r r i d e p u b l i cv o i di n i t i a l i z e ( U R Ll o c a t i o n .2 < V B o xf x : c o n t r o l l e r = " c o m . o u t . the following code defines an i n i t i a l i z e ( )method that attaches an action handler to a button in code rather than via an event handler attribute. for developers who prefer more restricted visibility for controller fields or handler methods. f o o . The resulting application behavior is identical: < V B o xf x : c o n t r o l l e r = " c o m .06/08/13 Introduction to FXML | JavaFX 2. which will be called once on an implementing controller when the contents of its associated document have been completely loaded: p u b l i cv o i di n i t i a l i z e ( ) . s e t O n A c t i o n ( n e wE v e n t H a n d l e r < A c t i o n E v e n t > ( ){ @ O v e r r i d e p u b l i cv o i dh a n d l e ( A c t i o n E v e n te v e n t ){ S y s t e m . since a controller is generally only visible to the FXML loader that creates it.R e s o u r c e sr e s o u r c e s ) b u t t o n . p r i n t l n ( " Y o uc l i c k e dm e ! " ) . f o o . In practice. 2 } } p a c k a g ec o m . the h a n d l e B u t t o n A c t i o n ( )is tagged with @ F X M Lto allow markup defined in the controller's document to invoke it. . s e t A c c e s s i b l e ( )is a privileged operation that can only be executed in a secure context. docs. . o u t . @ F X M Lp r i v a t eD i a l o g C o n t r o l l e rd i a l o g C o n t r o l l e r .06/08/13 Introduction to FXML | JavaFX 2. . } when the controller's i n i t i a l i z e ( )method is called.fxml" include.fxml < V B o xf x : c o n t r o l l e r = " c o m . and the document is assumed to define a controller of type M y C o n t r o l l e r : U R Ll o c a t i o n=g e t C l a s s ( ) . to populate and show the dialog. This may change in a future release. g e t B u n d l e ( " c o m . Note that the @ F X M Lannotation can currently only be used with trusted code. e x a m p l e " ) . } } ) . < / V B o x > MainController. the following code loads an FXML file from a location on the classpath relative to the loading class and localizes it with a resource bundle named "com.java p u b l i cc l a s sM a i n C o n t r o l l e re x t e n d sC o n t r o l l e r{ @ F X M Lp r i v a t eW i n d o wd i a l o g . f x m l " ) . f x m l " / > . s e t O n A c t i o n ( n e wE v e n t H a n d l e r < A c t i o n E v e n t > ( ){ @ O v e r r i d e p u b l i cv o i dh a n d l e ( A c t i o n E v e n te v e n t ){ S y s t e m . } } In the first version.html 13/15 .example". Nested Controllers Controller instances for nested FXML documents loaded via the < f x : i n c l u d e >element are mapped directly to member fields of the including controller. given the following code: main_window_content.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. the d i a l o gfield will contain the root element loaded from the "dialog.foo. The type of the root element is assumed to be a subclass of j a v a f x . M a i n C o n t r o l l e r " > < f x : i n c l u d ef x : i d = " d i a l o g "s o u r c e = " d i a l o g .oracle. This allows a developer to easily access functionality defined by an include (such as a dialog window presented by an application's main window controller). g e t R e s o u r c e ( " e x a m p l e . f o o . For example. In the second example. Because the FXML loader relies on reflection to set member fields and invoke member methods. FXMLLoader The F X M L L o a d e rclass is responsible for actually loading an FXML source file and returning the resulting object graph. f o o . R e s o u r c e B u n d l er e s o u r c e s=R e s o u r c e B u n d l e . it must call s e t A c c e s s i b l e ( )on any non-public F i e l d . For example. . s c e n e . p r i n t l n ( " Y o uc l i c k e dm e ! " ) . the button field is annotated to allow the loader to set its value. The i n i t i a l i z e ( )method is similarly annotated. . @ F X M L p r o t e c t e dv o i di n i t i a l i z e ( ) b u t t o n . for example. P a n e . l a y o u t . and the d i a l o g C o n t r o l l e rfield will contain the include's controller. p u b l i cc l a s sM y C o n t r o l l e ri m p l e m e n t sI n i t i a l i z a b l e{ @ F X M Lp r i v a t eB u t t o nb u t t o n . The main controller can then invoke methods on the included controller. f o o . or StAX) to load an FXML document. x m l . s c e n e . rather than loaded into an intermediate DOM structure and then post-processed. s t r e a mAPI (also known as the Streaming API for XML. In the following example. the contents of C u s t o m C o n t r o lwill be populated with the contents of the previous FXML document: p a c k a g ef x m l . The caller may similarly provide a value for the document's controller by calling s e t C o n t r o l l e r ( ) . f x m l . p r o p e r t y . b e a n s . g e t R e s o u r c e ( " c u s t o m _ c o n t r o l .html 14/15 . s e t C o n t r o l l e r ( t h i s ) . s c e n e . the following markup defines the structure of a simple custom control containing a T e x t F i e l dand a B u t t o ninstance. i m p o r tj a v a . l a y o u t . When the document is loaded. Note that the output of an F X M L L o a d e r # l o a d ( )operation is an instance hierarchy that reflects the actual named classes in the document. l a y o u t . f x m l L o a d e r . f x m l " ) ) . and sets itself as both the root and controller of the FXML document in its constructor. s c e n e . V B o x "x m l n s : f x = " h t t p : / / j a v a f x . * ? > < ? i m p o r tj a v a f x . P a n er o o t=( P a n e ) f x m l L o a d e r . rather than delegating creation of these values to F X M L L o a d e r itself. The value of this element is obtained by calling the g e t R o o t ( )method of F X M L L o a d e r . l a y o u t . w 3 c . i m p o r tj a v a f x . respectively. These two methods are commonly used together when creating custom FXML-based components.r e s o u r c e s ) . f x m l L o a d e r . StAX is an extremely efficient event-based XML parsing API that is conceptually similar to its W3C predecessor. S t r i n g P r o p e r t y . SAX. g e t ( ) . c o m / f x m l " > < T e x t F i e l df x : i d = " t e x t F i e l d " / > < B u t t o nt e x t = " C l i c kM e "o n A c t i o n = " # d o S o m e t h i n g " / > < / f x : r o o t > As mentioned earlier. Custom Components The s e t R o o t ( )and s e t C o n t r o l l e r ( )methods of F X M L L o a d e rallow a caller to inject document root and controller values.2 F X M L L o a d e rf x m l L o a d e r=n e wF X M L L o a d e r ( l o c a t i o n . the < f x : r o o t >tag creates a reference to a previously defined root element. the C u s t o m C o n t r o lclass extends V B o x(the type declared by the < f x : r o o t >element). p u b l i cC u s t o m C o n t r o l ( ){ F X M L L o a d e rf x m l L o a d e r=n e wF X M L L o a d e r ( g e t C l a s s ( ) . l o a d ( ) . Prior to calling l o a d ( ) . i m p o r tj a v a f x . F X M L . F X M L L o a d e r . It allows an FXML document to be processed in a single pass. s e t R o o t ( t h i s ) . The root container is defined as an instance of j a v a f x . c o n t r o l .oracle. but (from an API perspective) appear identically to controls implemented programmatically. i o . i m p o r tj a v a f x . c o n t r o l . This allows a developer to easily create reusable controls that are internally implemented using markup. T e x t F i e l d . g e t C o n t r o l l e r ( ) . into the document namespace. s c e n e . }c a t c h( I O E x c e p t i o ne x c e p t i o n ){ t h r o wn e wR u n t i m e E x c e p t i o n ( e x c e p t i o n ) . f x m l . docs. I O E x c e p t i o n . s c e n e . p u b l i cc l a s sC u s t o m C o n t r o le x t e n d sV B o x{ @ F X M Lp r i v a t eT e x t F i e l dt e x t F i e l d . s c e n e . i m p o r tj a v a f x . l a y o u t .06/08/13 Introduction to FXML | JavaFX 2. V B o x : < ? i m p o r tj a v a f x . which sets the value that will be used as the document's controller when the document is read.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. M y C o n t r o l l e rc o n t r o l l e r=( M y C o n t r o l l e r ) f x m l L o a d e r . d o mnodes representing those classes. * ? > < f x : r o o tt y p e = " j a v a f x . l o a d ( ) . For example. V B o x . s c e n e . t r y{ f x m l L o a d e r . } } p u b l i cS t r i n gg e t T e x t ( ){ r e t u r nt e x t P r o p e r t y ( ) . F X M L L o a d e ruses the j a v a x . Internally. * ? > < ? i m p o r tj a v a f x . the caller must specify this value via a call to s e t R o o t ( ) . not o r g . i m p o r tj a v a f x . Oracle and/or its affiliates.2 } p u b l i cv o i ds e t T e x t ( S t r i n gv a l u e ){ t e x t P r o p e r t y ( ) . g e t C h i l d r e n ( ) .g. FXML < H B o x > < C u s t o m C o n t r o lt e x t = " H e l l oW o r l d ! " / > < / H B o x > Copyright (c) 2008. just like any other control. docs.: Java H B o xh b o x=n e wH B o x ( ) .com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml. } } Now. C u s t o m C o n t r o lc u s t o m C o n t r o l=n e wC u s t o m C o n t r o l ( ) . s e t ( v a l u e ) . 2013. callers can use instances of this control in code or in markup. All rights reserved. t e x t P r o p e r t y ( ) . h b o x .oracle. } @ F X M L p r o t e c t e dv o i dd o S o m e t h i n g ( ){ S y s t e m . p r i n t l n ( " T h eb u t t o nw a sc l i c k e d ! " ) .06/08/13 Introduction to FXML | JavaFX 2. Use is subject to license terms. } p u b l i cS t r i n g P r o p e r t yt e x t P r o p e r t y ( ){ r e t u r nt e x t F i e l d .html 15/15 . a d d ( c u s t o m C o n t r o l ) . o u t . e. c u s t o m C o n t r o l . s e t T e x t ( " H e l l oW o r l d ! " ) .