Johan Vos, Stephen Chin, Weiqi Gao, James Weaver, Dean Iverson Pro Java FX 9 A Definitiv
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 356
| Download | |
| Open PDF In Browser | View PDF |
Pro JavaFX 9
A Definitive Guide to Building Desktop,
Mobile, and Embedded Java Clients
—
Fourth Edition
—
Johan Vos
Stephen Chin
Weiqi Gao
James Weaver
Dean Iverson
Pro JavaFX 9
A Definitive Guide to Building Desktop,
Mobile, and Embedded Java Clients
Fourth Edition
Johan Vos
Stephen Chin
Weiqi Gao
James Weaver
Dean Iverson
Pro JavaFX 9: A Definitive Guide to Building Desktop, Mobile, and Embedded Java Clients
Johan Vos Stephen Chin
Leuven, Belgium BELMONT, California, USA
Weiqi Gao James Weaver
Ballwin, Missouri, USA
Marion, Indiana, USA
Dean Iverson
Fort Collins, Colorado, USA
ISBN-13 (pbk): 978-1-4842-3041-1
https://doi.org/10.1007/978-1-4842-3042-8
ISBN-13 (electronic): 978-1-4842-3042-8
Library of Congress Control Number: 2017963349
Copyright © 2018 by Johan Vos, Stephen Chin, Weiqi Gao, James Weaver, and Dean Iverson
This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the
material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation,
broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage
and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or
hereafter developed.
Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with
every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an
editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark.
The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are
not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to
proprietary rights.
While the advice and information in this book are believed to be true and accurate at the date of publication,
neither the authors nor the editors nor the publisher can accept any legal responsibility for any errors or
omissions that may be made. The publisher makes no warranty, express or implied, with respect to the material
contained herein.
Cover image by Freepik (www.freepik.com)
Managing Director: Welmoed Spahr
Editorial Director: Todd Green
Acquisitions Editor: Steve Anglin
Development Editor: Matthew Moodie
Technical Reviewers: Mark Heckler and Jonathan Giles
Coordinating Editor: Mark Powers
Copy Editor: Kimberly Burton-Weisman
Distributed to the book trade worldwide by Springer Science+Business Media New York,
233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax (201) 348-4505, e-mail
orders-ny@springer-sbm.com, or visit www.springeronline.com. Apress Media, LLC is a California LLC
and the sole member (owner) is Springer Science + Business Media Finance Inc (SSBM Finance Inc).
SSBM Finance Inc is a Delaware corporation.
For information on translations, please e-mail rights@apress.com, or visit http://www.apress.com/
rights-permissions.
Apress titles may be purchased in bulk for academic, corporate, or promotional use. eBook versions
and licenses are also available for most titles. For more information, reference our Print and eBook Bulk
Sales web page at http://www.apress.com/bulk-sales.
Any source code or other supplementary material referenced by the author in this book is available to
readers on GitHub via the book's product page, located at www.apress.com/9781484230411. For more
detailed information, please visit http://www.apress.com/source-code.
Printed on acid-free paper
Contents
About the Authors���������������������������������������������������������������������������������������������������� ix
About the Technical Reviewers������������������������������������������������������������������������������� xi
Acknowledgments������������������������������������������������������������������������������������������������� xiii
Foreword�����������������������������������������������������������������������������������������������������������������xv
Introduction�����������������������������������������������������������������������������������������������������������xvii
■Chapter
■
1: Getting a Jump-Start in JavaFX����������������������������������������������������������� 1
A Brief History of JavaFX�������������������������������������������������������������������������������������������������� 1
Prepare Your JavaFX Journey������������������������������������������������������������������������������������������� 4
Required Tools���������������������������������������������������������������������������������������������������������������������������������������� 4
JavaFX, the Community�������������������������������������������������������������������������������������������������������������������������� 5
Use the Official Specifications���������������������������������������������������������������������������������������������������������������� 5
Scenic View�������������������������������������������������������������������������������������������������������������������������������������������� 6
Developing Your First JavaFX Program: Hello Earthrise��������������������������������������������������� 7
Compiling and Running from the Command Line����������������������������������������������������������������������������������� 8
Understanding the Hello Earthrise Program������������������������������������������������������������������������������������������� 9
Building and Running the Program with NetBeans������������������������������������������������������������������������������ 16
Developing Your Second JavaFX Program: “More Cowbell!”������������������������������������������ 20
Building and Running the Audio Configuration Program���������������������������������������������������������������������� 20
The Behavior of the Audio Configuration Program������������������������������������������������������������������������������� 21
Understanding the Audio Configuration Program��������������������������������������������������������������������������������� 22
Colors and Gradients���������������������������������������������������������������������������������������������������������������������������� 25
The Model Class for the Audio Configuration Example������������������������������������������������������������������������� 26
Using InvalidationListeners and Lambda Expressions�������������������������������������������������������������������������� 27
iii
■ Contents
Surveying JavaFX Features�������������������������������������������������������������������������������������������� 29
Summary������������������������������������������������������������������������������������������������������������������������ 30
Resources���������������������������������������������������������������������������������������������������������������������� 31
■Chapter
■
2: Creating a User Interface in JavaFX��������������������������������������������������� 33
Programmatic vs. Declarative Creation of the User Interface���������������������������������������� 33
Introduction to Node-Centric UIs������������������������������������������������������������������������������������ 33
Setting the Stage������������������������������������������������������������������������������������������������������������ 34
Understanding the Stage Class������������������������������������������������������������������������������������������������������������ 34
Using the Stage Class: The StageCoach Example�������������������������������������������������������������������������������� 35
Understanding the StageCoach Program��������������������������������������������������������������������������������������������� 39
Making a Scene�������������������������������������������������������������������������������������������������������������� 46
Using the Scene Class: The OnTheScene Example������������������������������������������������������������������������������� 46
Understanding the OnTheScene Program�������������������������������������������������������������������������������������������� 48
Handling Input Events���������������������������������������������������������������������������������������������������� 56
Surveying Mouse, Keyboard, Touch, and Gesture Events and
Handlers����������������������������������������������������������������������������������������������������������������������������������������������� 56
Understanding the KeyEvent Class������������������������������������������������������������������������������������������������������� 57
Understanding the MouseEvent Class�������������������������������������������������������������������������������������������������� 57
Understanding the TouchEvent Class��������������������������������������������������������������������������������������������������� 58
Understanding the GestureEvent Class������������������������������������������������������������������������������������������������ 58
Animating Nodes in the Scene��������������������������������������������������������������������������������������� 58
Using a Timeline for Animation������������������������������������������������������������������������������������������������������������� 59
Using the Transition Classes for Animation������������������������������������������������������������������������������������������ 64
The Zen of Node Collision Detection����������������������������������������������������������������������������������������������������� 71
Summary������������������������������������������������������������������������������������������������������������������������ 81
Resources���������������������������������������������������������������������������������������������������������������������� 81
■Chapter
■
3: Properties and Bindings��������������������������������������������������������������������� 83
Forerunners of JavaFX Binding�������������������������������������������������������������������������������������� 83
A Motivating Example����������������������������������������������������������������������������������������������������� 84
iv
■ Contents
Understanding Key Interfaces and Concepts����������������������������������������������������������������� 87
Understanding the Observable Interface���������������������������������������������������������������������������������������������� 88
Understanding the ObservableValue Interface������������������������������������������������������������������������������������� 89
Understanding the WritableValue Interface������������������������������������������������������������������������������������������ 90
Understanding the ReadOnlyProperty Interface����������������������������������������������������������������������������������� 90
Understanding the Property Interface�������������������������������������������������������������������������������������������������� 90
Understanding the Binding Interface���������������������������������������������������������������������������������������������������� 92
Type-Specific Specializations of Key Interfaces������������������������������������������������������������� 93
A Common Theme for Type-Specific Interfaces������������������������������������������������������������������������������������ 94
Commonly Used Classes���������������������������������������������������������������������������������������������������������������������� 97
Creating Bindings����������������������������������������������������������������������������������������������������������� 98
Understanding the Bindings Utility Class���������������������������������������������������������������������������������������������� 98
Understanding the Fluent Interface API���������������������������������������������������������������������������������������������� 102
Understanding the JavaFX Beans Convention�������������������������������������������������������������� 112
The JavaFX Beans Specification��������������������������������������������������������������������������������������������������������� 113
Understanding the Eagerly Instantiated Properties Strategy�������������������������������������������������������������� 113
Understanding the Lazily Instantiated Properties Strategy���������������������������������������������������������������� 117
Using Selection Bindings�������������������������������������������������������������������������������������������������������������������� 119
Adapting JavaBeans Properties to JavaFX Properties������������������������������������������������� 122
Understanding JavaBeans Properties������������������������������������������������������������������������������������������������� 122
Understanding the JavaFX Property Adapters������������������������������������������������������������������������������������ 124
Summary���������������������������������������������������������������������������������������������������������������������� 127
Resources�������������������������������������������������������������������������������������������������������������������� 128
■Chapter
■
4: Using Scene Builder to Create a User Interface������������������������������� 129
Setting the Stage with FXML���������������������������������������������������������������������������������������� 130
Creating a User Interface Graphically with JavaFX Scene Builder����������������������������������������������������� 130
Understanding the FXML File�������������������������������������������������������������������������������������������������������������� 131
Understanding the Controller�������������������������������������������������������������������������������������������������������������� 135
Understanding the FXMLLoader��������������������������������������������������������������������������������������������������������� 138
v
■ Contents
Understanding the FXML Loading Facility�������������������������������������������������������������������� 140
Understanding the FXMLLoader Class������������������������������������������������������������������������������������������������ 141
Understanding the @FXML Annotation����������������������������������������������������������������������������������������������� 146
Exploring the Capabilities of FXML Files���������������������������������������������������������������������� 149
The Deserialization Power of the FXML Format���������������������������������������������������������������������������������� 149
Understanding Default and Static Properties������������������������������������������������������������������������������������� 156
Understanding Attribute Resolutions and Bindings���������������������������������������������������������������������������� 156
Using Multiple FXML Files������������������������������������������������������������������������������������������������������������������ 161
Creating Custom Components Using fx:root��������������������������������������������������������������������������������������� 168
Event Handling Using Scripting or Controller Properties�������������������������������������������������������������������� 173
Using JavaFX Scene Builder����������������������������������������������������������������������������������������� 175
Overview of JavaFX Scene Builder����������������������������������������������������������������������������������������������������� 176
Understanding the Menu Bar and Items��������������������������������������������������������������������������������������������� 176
Understanding the Library Panel�������������������������������������������������������������������������������������������������������� 182
Understanding the Document Panel��������������������������������������������������������������������������������������������������� 185
Understanding the Content Panel������������������������������������������������������������������������������������������������������� 187
Understanding the Inspector Panel���������������������������������������������������������������������������������������������������� 188
Summary���������������������������������������������������������������������������������������������������������������������� 191
Resources�������������������������������������������������������������������������������������������������������������������� 191
■Chapter
■
5: Collections and Concurrency����������������������������������������������������������� 193
Understanding Observable Collections and Arrays������������������������������������������������������ 193
Understanding ObservableList������������������������������������������������������������������������������������������������������������ 194
Handling Change Events in ListChangeListener��������������������������������������������������������������������������������� 198
Understanding ObservableMap���������������������������������������������������������������������������������������������������������� 202
Understanding ObservableSet������������������������������������������������������������������������������������������������������������ 206
Understanding ObservableArrays������������������������������������������������������������������������������������������������������� 209
Using Factory and Utility Methods from FXCollections����������������������������������������������������������������������� 213
Using the JavaFX Concurrency Framework������������������������������������������������������������������ 218
Identifying the Threads in a JavaFX Application��������������������������������������������������������������������������������� 218
Fixing Unresponsive UIs��������������������������������������������������������������������������������������������������������������������� 224
Understanding the javafx.concurrent Framework������������������������������������������������������������������������������ 230
vi
■ Contents
Mixing JavaFX with Other GUI Toolkits������������������������������������������������������������������������� 251
Embedding JavaFX Scenes in Swing Applications����������������������������������������������������������������������������� 251
Embedding JavaFX Scenes in SWT Applications�������������������������������������������������������������������������������� 258
Embedding Swing Components in JavaFX Applications��������������������������������������������������������������������� 267
Summary���������������������������������������������������������������������������������������������������������������������� 273
Resources�������������������������������������������������������������������������������������������������������������������� 275
■Chapter
■
6: Creating Charts in JavaFX���������������������������������������������������������������� 277
Structure of the JavaFX Chart API�������������������������������������������������������������������������������� 277
Using the JavaFX PieChart������������������������������������������������������������������������������������������� 279
The Simple Example��������������������������������������������������������������������������������������������������������������������������� 279
Some Modifications���������������������������������������������������������������������������������������������������������������������������� 282
Using the XYChart��������������������������������������������������������������������������������������������������������� 287
Using the ScatterChart����������������������������������������������������������������������������������������������������������������������� 288
Using the LineChart���������������������������������������������������������������������������������������������������������������������������� 294
Using the BarChart����������������������������������������������������������������������������������������������������������������������������� 295
Using the StackedBarChart����������������������������������������������������������������������������������������������������������������� 297
Using the AreaChart���������������������������������������������������������������������������������������������������������������������������� 299
Using the StackedAreaChart��������������������������������������������������������������������������������������������������������������� 300
Using the BubbleChart������������������������������������������������������������������������������������������������������������������������ 300
Summary���������������������������������������������������������������������������������������������������������������������� 305
Resources�������������������������������������������������������������������������������������������������������������������� 305
■Chapter
■
7: Connecting to Enterprise Services��������������������������������������������������� 307
Front-End and Back-End Platforms������������������������������������������������������������������������������ 307
Merging JavaFX and Java Enterprise Modules in the Same Environment������������������� 309
Using JavaFX to Call Remote (Web) Services��������������������������������������������������������������� 310
REST��������������������������������������������������������������������������������������������������������������������������������������������������� 310
Using External Libraries���������������������������������������������������������������������������������������������������������������������� 336
Summary���������������������������������������������������������������������������������������������������������������������� 341
Index��������������������������������������������������������������������������������������������������������������������� 343
vii
About the Authors
Johan Vos is a Java Champion who started to work with Java in 1995. As part of the Blackdown team, he
helped port Java to Linux. With LodgON, the company he cofounded, he has been mainly working on
Java-based solutions for social networking software. His main focus is on end-to-end Java, combining the
strengths of back-end systems and embedded devices. His favorite technologies are currently Java EE/
Glassfish at the back end and JavaFX at the front end. He contributes to a number of open source projects,
including DataFX and the Android port of JavaFX. Johan’s blog can be followed at http://blogs.lodgon.
com/johan, he tweets at http://twitter.com/johanvos, and can be reached at johan@lodgon.com.
Stephen Chin is a Java Ambassador at Oracle specializing in embedded and user interface technology and
the JavaOne Content Chair. He has been featured at Java conferences around the world including Devoxx,
JFokus, OSCON, JFall, GeeCON, JustJava, and JavaOne, where he three times received a Rock Star Award.
Stephen is an avid motorcyclist who has done several Pan-European evangelism tours, interviewing hackers
in their natural habitat and posting the videos on http://nighthacking.com. When he is not traveling, he
enjoys teaching kids how to do embedded and robot programming together with his 11-year-old daughter.
Weiqi Gao is a principal software engineer with Object Computing, Inc. in St. Louis, Missouri. He has
decades of software development experience and has been using Java technology since 1998. He is
interested in programming languages, object-oriented systems, distributed computing, and graphical user
interfaces. He is a member of the steering committee of the St. Louis Java Users Group. Weiqi holds a PhD in
mathematics.
James Weaver is an author, a speaker, a teacher, and a developer in rich Internet application technologies
such as JavaFX. He is also an Oracle engineer. He may be contacted at jim.weaver@javafxpert.com.
Dean Iverson has been writing software professionally for more than 15 years. He is employed by the
Virginia Tech Transportation Institute, where he is a senior researcher and rich client application developer.
He also has a small software consultancy called Pleasing Software Solutions, which he cofounded with
his wife.
ix
About the Technical Reviewers
Mark Heckler is a Java software architect/engineer with development experience in numerous
environments. He has worked for and with key players in the manufacturing, emerging markets, retail,
medical, telecom, and financial industries to develop and deliver critical capabilities on time and on
budget. Currently, he works primarily with enterprise customers using Java throughout the stack. He also
participates in open source development at every opportunity, being a JFXtras project committer, developer
of DialogFX and MonologFX, co-developer of Autonomous4j, and more. When Mark isn’t working with Java,
he enjoys sharing his experiences at conferences and via the Java Jungle web site (https://blogs.oracle.
com/javajungle), his personal web site (www.thehecklers.org), and Twitter (@MkHeck). Mark lives with his
very understanding wife, three kids, and dog in St. Louis, Missouri.
Jonathan Giles is a software engineer who has worked with Java and JavaFX for a very long time. He has
been responsible for large sections of the JavaFX toolkit stack since 2009, and as such, is intimately familiar
with it. He is a JavaOne Rockstar speaker and track lead, an initiator of many open source projects (such as
ControlsFX and Scenic View—both referenced in this book), and a technical reviewer of many Java-related
books. He blogs at jonathangiles.net, and can be found on Twitter @JonathanGiles.
xi
Acknowledgments
Writing a book is often done in spare time. I want to thank my wife, Kathleen, and our children, Merlijn
and Linde, for allowing me to spend evening and weekend time in front of my computer. I want to thank
authors Jim Weaver, Weiqi Gao, Stephen Chin, and Dean Iverson; technical reviewer Mark Heckler; and
the Apress team for their trust in me. A special thanks to my LodgON colleagues Joeri Sykora and Erwin
Morrhey for helping me with the examples. The JavaFX team at Oracle did a great job releasing JavaFX 8.
The combination of their efforts and those of the Java community makes JavaFX an excellent platform for an
increasing number of clients.
—Johan Vos
To my wife, Justine, and daughters, Cassandra and Priscilla, who supported me in writing this book on top of
all my other responsibilities. Also, a huge thanks to the entire author team, including our newest members,
Johan Vos and Mark Heckler, who both went above and beyond in their contributions to this title. Finally, a
great debt of gratitude to the JavaFX team and JVM language designers who have produced technology that
will profoundly change the way we design and code user interfaces going forward.
—Stephen Chin
I would like to thank my wife, Youhong Gong, for her support, understanding, and encouragement during
the writing process. My thanks also go to the author and technical review team: Johan Vos, Jim Weaver,
Stephen Chin, Dean Iverson, and Mark Heckler for making this book a fun project. I share with my coauthors
the appreciation for the JavaFX team at Oracle and the editorial team at Apress.
—Weiqi Gao
I would like to thank my family, Sondra, Alex, and Matt, for their support and understanding during yet
another writing project. You guys make this possible. I would also like to thank the writing and review
team of Jim Weaver, Stephen Chin, Weiqi Gao, Johan Vos, and Mark Heckler for their dedication and their
patience. The editorial team at Apress was, as usual, first rate and utterly professional. And, of course, none
of this would be possible without the hard work of an extremely talented team of engineers on the JavaFX
team at Oracle.
—Dean Iverson
To my wife Julie, daughters, Lori and Kelli, son, Marty, and grandchildren, Kaleb and Jillian. Thanks Merrill
and Barbara Bishir, Ken and Marilyn Prater, and Walter Weaver for being such wonderful examples. My
contributions to this book are dedicated to the memory of Merrill Bishir and Ken Prater. “I have told you
these things, so that in me you may have peace. In this world you will have trouble. But take heart! I have
overcome the world.” (John 16:33)
—James Weaver
xiii
Foreword
I remember it distinctly, like it was yesterday: standing center stage at Moscone Center when we launched
JavaFX at JavaOne 2007. We promised to build a world-class client platform for Java. With the world watching
with skeptical eyes and in a crowded client arena, we set out to build the dream. In hindsight, it was a rather
ambitious goal.
Fast-forward seven years, with the release of Java SE 8, we have taken a huge leap forward in fulfilling
that promise. As the vision unfolded, our product plans have shifted to match the evolving RIA market and
what developers and the Java community told us they were looking for. As someone who was there at the
inception of JavaFX and who has watched it mature over the last seven years to this current release, my
feelings are akin to a parent watching a toddler blossom.
James Weaver and Stephen Chin have been traveling through the evolution of JavaFX with me. They
have both presented on JavaFX at numerous international conferences and have been developing with
and blogging about JavaFX since 2007. James is a 30-year software veteran who has authored several books
on Java, as well as articles for Java Magazine and the Oracle Technology Network. He has also developed
numerous JavaFX applications for a wide variety of customers.
Stephen is passionate about open source technologies and is the founder of WidgetFX and JFXtras.
He also has a deep passion for improving development technologies and processes, as well as agile
development methodologies.
Johan Vos is cofounder of LodgON. He holds a PhD in applied physics and he has been a very prolific
member of the JavaFX community. His interest lies in the enterprise communication aspects of JavaFX,
combining the world of large servers with end-user devices. Johan’s analogy to physics: The grand unified
theory combines quantum mechanics (small) with relativity theory (large); similarly, in software, Java
combines JavaFX with Java EE.
Dean Iverson is a longtime client developer with a great eye for creating elegant user interfaces.
He develops GroovyFX libraries and is a contributor to the JFXtras project. He has been developing and
blogging about JavaFX since 2007. Weiqi Gao holds a PhD in mathematics. His expertise is in the language
aspects of JavaFX, as reflected in the chapters on properties and bindings, and collections and concurrency.
Today, the core JavaFX team at Oracle still has several of the developers who were part of the early
versions of JavaFX and we also have new engineers who have joined us. As we move ahead and open source
JavaFX, we are looking forward to having more developers and experts from the extended Java community
join us in making JavaFX the number one choice for client development.
I am proud and honored to be part of this key software technology. Given their length of experience and
depth of expertise in all aspects of JavaFX and across the Java platform, I cannot think of a better group of
authors to bring you JavaFX 8. I hope you will enjoy this book and find JavaFX as satisfying as I have found it
over the years. I hope it piques your interest sufficiently to join the JavaFX community in making JavaFX the
platform of choice for clients.
—Nandini Ramani
Vice President, Java Client Development
Oracle Corporation
xv
Introduction
As a developer, author, speaker, and advocate for JavaFX since its inception in 2007, I am very excited about
JavaFX 8. It was released in March 2014 as an integral part of Java SE 8, and is the successor to Java Swing. As
you’ll read in the pages of this book, JavaFX runs on desktops (Mac, Windows, Linux), as well as embedded
devices such as the Raspberry Pi. As the Internet of things (IoT) is increasingly realized, JavaFX is well
positioned to enable the user interface of IoT. Also, because of community projects led by folks such as Johan
Vos and Niklas Therning, developers are deploying JavaFX apps on Android and iOS devices.
The JavaFX community has many talented, passionate, and cordial developers, and I count it a privilege
to call them my colleagues. One such colleague, Johan Vos, is a coauthor of our Pro JavaFX 2 book, and is the
lead author of Pro JavaFX 8. It has been my pleasure to continue working with Johan on this book under his
leadership. Please join me in welcoming and congratulating him in this role, perhaps by tweeting him at
@JohanVos or posting a review of this book on Amazon. It is my hope that you’ll find this book both enjoyable
and instrumental in helping you learn JavaFX!
—James L. Weaver
Java Technology Ambassador
Oracle Corporation
xvii
CHAPTER 1
Getting a Jump-Start in JavaFX
Don’t ask what the world needs. Ask what makes you come alive, and go do it. Because
what the world needs is people who have come alive.
—Howard Thurman
At the annual JavaOne conference in May 2007, Sun Microsystems announced a new product family named
JavaFX. Its stated purpose includes enabling the development and deployment of content-rich applications
on consumer devices such as cell phones, televisions, in-dash car systems, and browsers. Josh Marinacci,
a software engineer at Sun, made the following statement, very appropriately, in a Java Posse interview:
“JavaFX is sort of a code word for reinventing client Java and fixing the sins of the past.” He was referring
to the fact that Java Swing and Java 2D have lots of capability, but are also very complex. Furthermore,
technologies have evolved a lot since Swing and Java 2D were created. Today’s client systems (desktops as
well as mobile and embedded devices) are equipped with powerful graphical processors—the GPU. JavaFX
takes advantage of the new features and performance increases offered by GPUs. By using FXML, JavaFX
allows us to simply and elegantly express user interfaces (UIs) with a declarative programming style. It also
leverages the full power of Java, because you can instantiate and use the millions of Java classes that exist
today. Add features such as binding the UI to properties in a model and change listeners that reduce the
need for setter methods, and you have a combination that will help restore Java to the client-side Internet
applications.
In this chapter, we give you a jump-start in developing JavaFX applications. After bringing you up to
date on the brief history of JavaFX, we show you how to get the required tools. We also explore some great
JavaFX resources and walk you through the process of compiling and running JavaFX applications. In the
process, you’ll learn a lot about the JavaFX application programming interface (API) as we walk through
application code together.
A Brief History of JavaFX
JavaFX started life as the brainchild of Chris Oliver when he worked for a company named SeeBeyond.
They had a need for richer user interfaces, so Chris created a language that he dubbed F3 (Form Follows
Function) for that purpose. In the article “Mind-Bendingly Cool Innovation” (cited in the “Resources”
section at the end of this chapter), Chris is quoted as follows: “When it comes to integrating people into
business processes, you need graphical user interfaces for them to interact with, so there was a use case for
graphics in the enterprise application space, and there was an interest at SeeBeyond in having richer user
interfaces.”
SeeBeyond was acquired by Sun, who subsequently changed the name of F3 to JavaFX, and announced
it at JavaOne 2007. Chris Oliver joined Sun during the acquisition and continued to lead the development of
JavaFX.
© Johan Vos, Stephen Chin, Weiqi Gao, James Weaver, and Dean Iverson 2018
J. Vos et al., Pro JavaFX 9, https://doi.org/10.1007/978-1-4842-3042-8_1
1
Chapter 1 ■ Getting a Jump-Start in JavaFX
The first version of JavaFX Script was an interpreted language, and was considered a prototype of the
compiled JavaFX Script language that was to come later. Interpreted JavaFX Script was very robust, and
there were two JavaFX books published in the latter part of 2007 based on that version. One was written in
Japanese, and the other was written in English (JavaFX Script: Dynamic Java Scripting for Rich Internet/
Client-Side Applications by Jim Weaver (Apress, 2007)).
While developers were experimenting with JavaFX and providing feedback for improvement, the JavaFX
Script compiler team at Sun was busy creating a compiled version of the language. This included a new set
of runtime API libraries. The JavaFX Script compiler project reached a tipping point in early December 2007,
which was commemorated in a blog post entitled “Congratulations to the JavaFX Script Compiler Team—
The Elephant Is Through the Door.” That phrase came from the JavaFX Script compiler project leader Tom
Ball in a blog post, which contained the following excerpt.
An elephant analogy came to me when I was recently grilled about exactly when the
JavaFX Script compiler team will deliver our first milestone release. “I can’t give you an
accurate date,” I said. “It’s like pushing an elephant through a door; until a critical mass
makes it past the threshold you just don’t know when you’ll be finished. Once you pass that
threshold, though, the rest happens quickly and in a manner that can be more accurately
predicted.”
A screenshot of the silly, compiled JavaFX application written by one of the authors, Jim Weaver, for that
post is shown in Figure 1-1, demonstrating that the project had in fact reached the critical mass to which
Tom Ball referred.
Figure 1-1. Screenshot for the “Elephant Is Through the Door” program
Much progress continued to be made on JavaFX in 2008:
2
•
The NetBeans JavaFX plug-in became available for the compiled version in
March 2008.
•
Many of the JavaFX runtime libraries (mostly focusing on the UI aspects of JavaFX)
were rewritten by a team that included some very talented developers from the
Java Swing team.
Chapter 1 ■ Getting a Jump-Start in JavaFX
•
In July 2008, the JavaFX Preview Software Development Kit (SDK) was released, and at
JavaOne 2008, Sun announced that the JavaFX 1.0 SDK would be released in fall 2008.
•
On December 4, 2008, the JavaFX 1.0 SDK was released. This event increased the
adoption rate of JavaFX by developers and IT managers because it represented a
stable codebase.
•
In April 2009, Oracle and Sun announced that Oracle would be acquiring Sun. The
JavaFX 1.2 SDK was released at JavaOne 2009.
•
In January 2010, Oracle completed its acquisition of Sun. The JavaFX 1.3 SDK was
released in April 2010, with JavaFX 1.3.1 being the last of the 1.3 releases.
At JavaOne 2010, JavaFX 2.0 was announced. The JavaFX 2.0 roadmap was published by Oracle and
included items such as the following.
•
Deprecate the JavaFX Script language in favor of using Java and the JavaFX 2.0 API.
This brings JavaFX into the mainstream by making it available to any language
(e.g., Java, Groovy, and JRuby) that runs on the Java Virtual Machine (JVM). As a
consequence, existing developers do not need to learn a new language, but they can
use existing skills and start developing JavaFX applications.
•
Make the compelling features of JavaFX Script, including binding to expressions,
available in the JavaFX 2.0 API.
•
Offer an increasingly rich set of UI components, building on the components already
available in JavaFX 1.3.
•
Provide a Web component for embedding HTML and JavaScript content into JavaFX
applications.
•
Enable JavaFX interoperability with Swing.
•
Rewrite the media stack from the ground up.
JavaFX 2.0 was released at JavaOne 2011, and has enjoyed a greatly increased adoption rate due to the
innovative features articulated previously.
JavaFX 8 marked another important milestone. JavaFX is now an integral part of the Java Platform,
Standard Edition.
•
This is a clear indication that JavaFX is considered mature enough, and that it is the
future of Java on the client.
•
This greatly benefits developers, as they don’t have to download two SDKs and tool
suites.
•
The new technologies in Java 8, in particular the lambda expressions, Stream API,
and default interface methods, are very usable in JavaFX.
•
Many new features have been added, including native 3D support, a printing API,
and some new controls including a datepicker.
•
Since the release of JavaFX 8, the JavaFX platform follows the same version and
release procedures as the Java Platform, Standard Edition. As a consequence, when
Java 9 was released, JavaFX 9 was released as well.
•
The main focus for Java 9 is modularity. The Java Platform, Standard Edition, has
become bigger and bigger, and not all applications require all classes to be available.
By modularizing the Java Platform, it is easier to create subsets of the Java platform
3
Chapter 1 ■ Getting a Jump-Start in JavaFX
that combine a number of modules that are sufficient to run a particular application.
This modularization effort was huge, and it took many years before it was complete.
All parts of the Java Platform, Standard Edition have been refactored into modules,
including the JavaFX 9 Platform APIs.
•
One of the consequences of the modularization is that it is now not allowed anymore
for code to depend on internal APIs of another module. This has far-reaching
consequences. Before JavaFX 9, Controls were often created by implementing
undocumented internal APIs. Those APIs were public, because they were used
internally by other JavaFX classes, in different packages. As a consequence,
developer could use them as well.
•
Since those internal APIs are now in modules that by default do not expose this
functionality, a new approach was needed for developers who want to create
custom controls. Hence, the JavaFX team was not only faced with moving all the
JavaFX public APIs into a number of modules, it also had to provide public APIs for
functionality that was previously accessed via internal APIs.
In Java 9, the JavaFX platform provides the following modules:
•
javafx.base
•
javafx.controls
•
javafx.fxml
•
javafx.graphics
•
javafx.jmx
•
javafx.media
•
javafx.swing
•
javafx.swt
•
javafx.web
•
jdk.packager
•
jdk.packager.services
Now that you’ve had the obligatory history lesson in JavaFX, let’s get one step closer to writing code by
showing you where some examples, tools, and other resources are.
Prepare Your JavaFX Journey
Required Tools
Because JavaFX is part of Java 9, you don’t have to download a separate JavaFX SDK. The whole JavaFX
API and implementation is part of the Java 9 SE SDK that can be downloaded from www.oracle.com/
technetwork/java/javase/downloads/index.html.
This SDK contains everything you need to develop, run, and package JavaFX applications. You can
compile JavaFX applications using command-line tools contained in the Java 9 SE SDK.
Most developers, however, prefer an integrated development environment (IDE) for increased
productivity. By definition, an IDE that supports Java 9 also supports JavaFX 9. Hence, you can use your
favorite IDE and develop JavaFX applications. In this book, we mainly use the NetBeans IDE, but other
4
Chapter 1 ■ Getting a Jump-Start in JavaFX
IDE’s, such as IntelliJ or Eclipse, can be used as well. The NetBeans IDE can be downloaded from
https://netbeans.org/downloads.
Many JavaFX developers, especially those working on user interfaces, prefer a WYSIWYG tool for
creating interfaces. Scene Builder is a stand-alone tool that allows you to design JavaFX interfaces rather
than coding them. We discuss Scene Builder in Chapter 4. Although Scene Builder produces FXML—and
we discuss FXML in Chapter 3 as well—that can be used in any IDE, NetBeans provides a tight integration
with Scene Builder. The Scene Builder tool can be downloaded at http://gluonhq.com/products/scenebuilder/.
JavaFX, the Community
JavaFX is not a closed-source project, developed in a secret bunker. To the contrary, JavaFX is being
developed in an open spirit, with an open source code base, open mailing lists, and an open and active
community sharing knowledge.
The source code is developed in the OpenJFX project, which is a subproject of the OpenJDK project in
which Java SE is being developed. If you want to examine the source code or the architecture, or if you want
to read the technical discussions on the mailing list, have a look at http://openjdk.java.net/projects/
openjfx.
The developer community is very active, both in OpenJFX as well as in application-specific areas. Many
JavaFX developers regularly blog about their JavaFX activities, and many non-Oracle products and projects
related to JavaFX are being created and maintained by this community.
In addition, blogs maintained by JavaFX engineers and developers are great resources for up-tothe-minute technical information on JavaFX. For example, Oracle JavaFX Engineer Jonathan Giles keep
the developer community apprised of the latest JavaFX innovations at http://fxexperience.com. The
“Resources” section at the end of this chapter contains the URLs of the blogs that the authors of this book
use to engage the JavaFX developer community.
Two important characteristics of the JavaFX Community are its own creativity and the desire to share.
There are a number of open-source efforts bringing added value to the JavaFX Platform. Because of good
cooperation between the JavaFX platform engineers and the external JavaFX developers, these open-source
projects fit very well with the official JavaFX platform.
Some of the most interesting efforts are listed here:
•
Gluon allows you to create iOS and Android applications using Java and JavaFX. As
a consequence, your JavaFX application can be used to create an app for Android
devices and for the iPhone or the iPad.
This mobile port of JavaFX is discussed in more detail in Chapter 12.
•
ControlsFX is a project working on adding high-quality controls and add-ons to the
JavaFX platform.
•
JFXtras.org is another project working on adding high-quality controls and add-ons
to the JavaFX platform.
It is worth mentioning that the JavaFX team is closely watching the efforts in both JFXtras.org and
ControlsFX, and ideas that start in one of those projects might make it into one of the next releases of JavaFX.
Take a few minutes to explore these sites. Next, we point out some valuable resources.
Use the Official Specifications
While developing JavaFX applications, it is very useful to have access to the API Javadoc documentation,
which is available at http://download.java.net/jdk9/jfxdocs/index.html and shown in Figure 1-2.
5
Chapter 1 ■ Getting a Jump-Start in JavaFX
Figure 1-2. JavaFX SDK API Javadoc
The API documentation in Figure 1-2, for example, shows how to use the Rectangle class, located in the
javafx.scene.shape package. Scrolling down this web page shows the properties, constructors, methods,
and other helpful information about the Rectangle class. By the way, this API documentation is available in
the Java 8 SE SDK that you downloaded, but we wanted you to know how to find it online as well.
Apart from the Javadoc, it is very useful to have the Cascading Style Sheets (CSS) style reference at hand as
well. This document explains all the style classes that can be applied to a particular JavaFX element. You can
find this document at http://download.java.net/jdk9/jfxdocs/javafx/scene/doc-files/cssref.html.
Scenic View
You already downloaded Scene Builder, which is the tool that allows you to create UIs by designing them,
rather than writing code. We expect that there will be more tools developed by companies and individuals
that help you create JavaFX applications. One of the first tools that was made available for free and that is
very helpful when debugging JavaFX applications is ScenicView, originally created by Amy Fowler at Oracle,
and later maintained by Jonathan Giles. You can download ScenicView at http://scenic-view.org/.
ScenicView is particularly helpful because it provides a convenient UI that allows developers to inspect
properties of nodes (i.e., dimensions, translations, CSS) at runtime.
Packaging and Distribution
The techniques used for delivering software to the end user are always changing. In the past, the preferred
way for delivering Java applications was via the Java Network Launch Protocol (JNLP). Doing so, both
applets and stand-alone applications can be installed on a client. However, there are a number of issues
6
Chapter 1 ■ Getting a Jump-Start in JavaFX
with this technique. The idea only works if the end user has a JVM installed that is capable of executing the
application. This is not always true. Even in the desktop world, where a system can be delivered preinstalled
with a JVM, there are issues with versioning and security. Indeed, some applications are hard-coded against
a specific version of the JVM. Although vulnerabilities in the JVM are in most cases fixed very fast, this still
requires the end user to always install the latest version of the JVM, which can be pretty frustrating.
On top of that, browser manufacturers are increasingly reluctant to support alternative embedded
platforms. In summary, relying on a browser and on a local, preinstalled JVM does not provide the best enduser experience.
The client software industry is shifting more and more toward the so-called app stores. In this concept,
applications can be downloaded and installed that are self-containing. They do not rely on preinstalled
execution environments. The principles originated in the mobile space, where Apple’s AppStore and
Android’s Play Store are leading the market. Especially in these markets, single-click installs have a huge
advantage over local downloads, unpacking, manual configuration, and more nightmares.
In Java terminology, a self-contained application means that the application is bundled together with a
JVM that is capable of running the application. In the past, this idea was often rejected because it made the
application bundle too big. However, with increasing memory and storage capacities, and with decreasing
costs of sending bytes over the Internet, this disadvantage is becoming less relevant.
There are a number of technologies being developed currently that help you bundle your application
with the correct JVM version and package it.
The standard technology for bundling Java applications with a Java Virtual Machine runtime is the
JavaPackager, which is developed inside the OpenJFX project area. JavaFXPackager contains an API for
creating self-contained bundles. This tool is used by NetBeans, and it can be used to generate self-contained
bundles with just a few clicks.
Now that you have the tools installed, we show you how to create a simple JavaFX program, and then
we walk through it in detail. The first program that we’ve chosen for you is called “Hello Earthrise,” which
demonstrates more features than the typical beginning “Hello World” program.
Developing Your First JavaFX Program: Hello Earthrise
On Christmas Eve in 1968, the crew of Apollo 8 entered lunar orbit for the first time in history. They were
the first humans to witness an “Earthrise,” taking the magnificent picture shown in Figure 1-3. This image is
dynamically loaded from this book’s web site when the program starts, so you’ll need to be connected to the
Internet to view it.
7
Chapter 1 ■ Getting a Jump-Start in JavaFX
Figure 1-3. The Hello Earthrise program
In addition to demonstrating how to dynamically load images over the Internet, this example shows you
how to use animation in JavaFX. Now it’s time for you to compile and run the program. We show you two
ways to do this: from the command line and using NetBeans.
Compiling and Running from the Command Line
We usually use an IDE to build and run JavaFX programs, but to take all of the mystery out of the process we
use the command-line tools first.
■■Note For this exercise, as with most others in the book, you need the source code. If you prefer not to type
the source code into a text editor, you can obtain the source code for all of the examples in this book from the
code download site. See the “Resources” section at the end of this chapter for the location of this site.
Assuming that you’ve downloaded and extracted the source code for this book into a directory, follow
the directions in this exercise, performing all of the steps as instructed. We dissect the source code after the
exercise.
8
Chapter 1 ■ Getting a Jump-Start in JavaFX
COMPILING AND RUNNING THE HELLO EARTHRISE PROGRAM FROM
THE COMMAND LINE
You’ll use the javac and java command-line tools to compile and run the program in this exercise. From
the command-line prompt on your machine:
1.
Navigate to the Chapter01/Hello directory.
2.
Execute the following command to compile the HelloEarthRiseMain.java file.
javac -d . HelloEarthRiseMain.java
3.
Because the –d option was used in this command, the class files generated are
placed in directories matching the package statements in the source files. The roots
of those directories are specified by the argument given for the –d option, in this
case the current directory.
4.
To run the program, execute the following command. Note that we use the fully
qualified name of the class that will be executed, which entails specifying the
nodes of the path name and the name of the class, all separated by periods.
java projavafx.helloearthrise.ui.HelloEarthRiseMain
The program should appear as shown in Figure 1-4, with the text scrolling slowly upward, reminiscent
of the Star Wars opening crawls.
Congratulations on completing your first exercise as you explore JavaFX!
Understanding the Hello Earthrise Program
Now that you’ve run the application, let’s walk through the program listing together. The code for the Hello
Earthrise application is shown in Listing 1-1.
Listing 1-1. The HelloEarthRiseMain.java Program
package projavafx.helloearthrise.ui;
import
import
import
import
import
import
import
import
import
import
import
import
import
import
javafx.animation.Interpolator;
javafx.animation.Timeline;
javafx.animation.TranslateTransition;
javafx.application.Application;
javafx.geometry.VPos;
javafx.scene.Group;
javafx.scene.Scene;
javafx.scene.image.Image;
javafx.scene.image.ImageView;
javafx.scene.paint.Color;
javafx.scene.shape.Rectangle;
javafx.scene.text.Font;
javafx.scene.text.FontWeight;
javafx.scene.text.Text;
9
Chapter 1 ■ Getting a Jump-Start in JavaFX
import javafx.scene.text.TextAlignment;
import javafx.stage.Stage;
import javafx.util.Duration;
/**
* Main class for the "Hello World" style example
*/
public class HelloEarthRiseMain extends Application {
/**
* @param args the command line arguments
*/
public static void main(String[] args) {
Application.launch(args);
}
@Override
public void start(Stage stage) {
String message
= "Earthrise at Christmas: "
+ "[Forty] years ago this Christmas, a turbulent world "
+ "looked to the heavens for a unique view of our home "
+ "planet. This photo of Earthrise over the lunar horizon "
+ "was taken by the Apollo 8 crew in December 1968, showing "
+ "Earth for the first time as it appears from deep space. "
+ "Astronauts Frank Borman, Jim Lovell and William Anders "
+ "had become the first humans to leave Earth orbit, "
+ "entering lunar orbit on Christmas Eve. In a historic live "
+ "broadcast that night, the crew took turns reading from "
+ "the Book of Genesis, closing with a holiday wish from "
+ "Commander Borman: \"We close with good night, good luck, "
+ "a Merry Christmas, and God bless all of you -- all of "
+ "you on the good Earth.\"";
// Reference to the Text
Text textRef = new Text(message);
textRef.setLayoutY(100);
textRef.setTextOrigin(VPos.TOP);
textRef.setTextAlignment(TextAlignment.JUSTIFY);
textRef.setWrappingWidth(400);
textRef.setFill(Color.rgb(187, 195, 107));
textRef.setFont(Font.font("SansSerif", FontWeight.BOLD, 24));
// Provides the animated scrolling behavior for the text
TranslateTransition transTransition = new TranslateTransition(new Duration(75000),
textRef);
transTransition.setToY(-820);
transTransition.setInterpolator(Interpolator.LINEAR);
transTransition.setCycleCount(Timeline.INDEFINITE);
10
Chapter 1 ■ Getting a Jump-Start in JavaFX
// Create an ImageView containing the Image
Image image = new Image ("http://projavafx.com/images/earthrise.jpg");
ImageView imageView = new ImageView(image);
// Create a Group containing the text
Group textGroup = new Group(textRef);
textGroup.setLayoutX(50);
textGroup.setLayoutY(180);
textGroup.setClip(new Rectangle(430, 85));
// Combine ImageView and Group
Group root = new Group(imageView, textGroup);
Scene scene = new Scene(root, 516, 387);
stage.setScene(scene);
stage.setTitle("Hello Earthrise");
stage.show();
// Start the text animation
transTransition.play();
}
}
Now that you’ve seen the code, let’s take a look at its constructs and concepts in some more detail.
What Happened to the Builders?
If you were using JavaFX 2 before, you are probably familiar with the so-called builder pattern. Builders
provide a declarative style of programming. Rather than calling set() methods on a class instance to specify
its fields, the builder pattern uses an instance of a Builder class to define how the target class should be
composed.
Builders were very popular in JavaFX. However, it turned out that there were major technical hurdles
with keeping them in the platform. As a consequence, the decision was made to phase out builders. In Java 8,
Builder classes were still usable, but they are deprecated. In Java 9, Builder classes have been removed
entirely.
More information on the reason why Builder classes are not preferred anymore can be found in a
mailing list entry by JavaFX Client Architect Richard Bair at http://mail.openjdk.java.net/pipermail/
openjfx-dev/2013-March/006725.html. The bottom of this entry contains a very important statement:
“I believe that FXML or lambda’s or alternative languages all provide other avenues for achieving the same
goals as builders but without the additional cost in byte codes or classes.”
This is what we will show throughout this book. Near the end of this chapter, we show a first example
of a lambda expression in our code. In Chapter 3, we show how Scene Builder and FXML allow you to use a
declarative way of defining a UI.
In the current example, we programmatically define the different components of the UI, and we glue
them together. In Chapter 3, we show the same example using a declarative FXML-based approach.
11
Chapter 1 ■ Getting a Jump-Start in JavaFX
The JavaFX Application
Let’s have a look at the class declaration in our first example:
public class HelloEarthRiseMain extends Application
This declaration states that our application extends the javafx.application.Application class. This
class has one abstract method that we should implement:
public void start(Stage stage) {}
This method will be called by the environment that executes our JavaFX application.
Depending on the environment, JavaFX applications will be launched in a different way. As a developer,
you don’t have to worry about how your application is launched, and where the connection to a physical
screen is made. You have to implement the “start” method and use the provided Stage parameter to create
your UI, as discussed in the next paragraph.
In our command-line example, we launched the applications by executing the main method of the
application class. The implementation of the main method is very simple:
public static void main(String[] args) {
Application.launch(args);
}
The only instruction in this main method is a call to the static launch method of the application, which
will launch the application.
■■Tip
A JavaFX application always has to extend the javafx.application.Application class.
A Stage and a Scene
A Stage contains the UI of a JavaFX app, whether it is deployed on the desktop, on an embedded system,
or on other devices. On the desktop, for example, a Stage has its own top-level window, which typically
includes a border and title bar.
The initial stage is created by the JavaFX runtime, and passed to you via the start() method, as
described in the previous paragraph. The Stage class has a set of properties and methods. Some of these
properties and methods, as shown in the following code snippet from the listing, are as follows.
•
A scene that contains the graphical nodes in the UI
•
A title that appears in the title bar of the window (when deployed on the desktop)
•
The visibility of the Stage
stage.setScene(scene);
stage.setTitle("Hello Earthrise");
stage.show();
A Scene is the top container in the JavaFX scene graph. A Scene holds the graphical elements that are
displayed on the Stage. Every element in a Scene is a graphical node, which is any class that extends
javafx.scene.Node. The scene graph is a hierarchical representation of the Scene. Elements in the scene
graph may contain child elements, and all of them are instances of the Node class.
12
Chapter 1 ■ Getting a Jump-Start in JavaFX
The Scene class contains a number of properties, such as its width and height. A Scene also has a property
named root that holds the graphical elements that are displayed in the Scene, in this case a Group instance that
contains an ImageView instance (which displays an image) and a Group instance. Nested within the latter Group
is a Text instance (which is a graphical element, usually called a graphical node, or simply node).
Notice that the root property of the Scene contains an instance of the Group class. The root property may
contain an instance of any subclass of javafx.scene.Node, and typically contains one capable of holding its
own set of Node instances. Take a look at the JavaFX API documentation that we showed you how to access in
the “Use the Official Specifications” section and check out the Node class to see the properties and methods
available to any graphical node. Also, take a look at the ImageView class in the javafx.scene.image package
and the Group class in the javafx.scene package. In both cases, they inherit from the Node class.
■■Tip We can’t emphasize enough the importance of having the JavaFX API documentation handy
while reading this book. As classes, variables, and functions are mentioned, it’s a good idea to look at the
documentation to get more information. In addition, this habit helps you become more familiar with what is
available to you in the API.
Displaying Images
As shown in the following code, displaying an image entails using an ImageView instance in conjunction
with an Image instance.
Image image = new Image ("http://projavafx.com/images/earthrise.jpg");
ImageView imageView = new ImageView(image);
The Image instance identifies the image resource and loads it from the URL assigned to its URL variable.
Both of these classes are located in the javafx.scene.image package.
Displaying Text
In the example, we created a Text Node as follows:
Text textRef = new Text(message);
If you consult the JavaFX API documentation, you will notice that a Text instance, contained in package
javafx.scene.text, extends a Shape that extends a Node. As a consequence, a Text instance is a Node as
well, and all the properties on Node apply on Text as well. Moreover, Text instances can be used in the scene
graph the same way other nodes are used.
As you can detect from the example, a Text instance contains a number of properties that can be
modified. Most of the properties are self-explanatory, but again, it is always useful to consult the JavaFX API
documentation when manipulating objects.
Because all graphical elements in JavaFX directly or indirectly extend the Node class, and because the
Node class already contains many useful properties, the amount of properties on a specific graphical element
such as Text can be rather high.
In our example, we set a limited number of properties that are briefly explained next.
The textRef.setLayoutY(100) method applies a vertical translation of 100 pixels to the Text content.
The fill method is used to specify the color of the text.
13
Chapter 1 ■ Getting a Jump-Start in JavaFX
While you’re looking at the javafx.scene.text package in the API documentation, take a look at the
font function of the Font class, which is used to define the font family, weight, and size of the Text.
The textOrigin property specifies how the text is aligned with its area.
Referring again to the JavaFX API documentation, notice that the VPos enum (in the javafx.geometry
package) has fields that serve as constants, for example, BASELINE, BOTTOM, and TOP. These control the
origin of the text with respect to vertical locations on the displayed Text:
•
The TOP origin, as we’re using it in the previous code snippet, places the top of the
text (including ascenders) at the layoutY position, relative to the coordinate space in
which the Text is located.
•
The BOTTOM origin would place the bottom of the text, including descenders
(located in a lowercase g, for example) at the layoutY position.
•
The BASELINE origin would place the baseline of the text (excluding descenders) at
the layoutY position. This is the default value for the textOrigin property of a Text
instance.
The wrappingWidth property enables you to specify at what number of pixels the text will wrap.
The textAlignment property enables you to control how the text will be justified. In our example,
TextAlignment.JUSTIFY aligns the text on both the left and right sides, expanding the space between words
to achieve that.
The text that we’re displaying is sufficiently long enough to wrap and be drawn on the Earth, so we need
to define a rectangular region, outside of which the text cannot be seen.
■■Tip We recommend you modify some of the values, recompile the example, and run it again. This will help
you understanding how the different properties work. Alternatively, by using ScenicView you can inspect and
modify the different properties at runtime.
Working with Graphical Nodes as a Group
One powerful graphical feature of JavaFX is the ability to create scene graphs, which consist of a tree of
graphical nodes. You can then assign values to properties of a Group located in the hierarchy, and the nodes
contained in the Group will be affected. In our current example from Listing 1-1, we’re using a Group to
contain a Text node and to clip a specific rectangular region within the Group so that the text doesn’t appear
on the moon or the Earth as it animates upward. Here’s the relevant code snippet:
Group textGroup = new Group(textRef);
textGroup.setLayoutX(50);
textGroup.setLayoutY(180);
textGroup.setClip(new Rectangle(430, 85));
Notice that the Group is located 50 pixels to the right and 180 pixels down from where it would have
been located by default. This is due to the values assigned to the layoutX and layoutY variables of the Group
instance. Because this Group is contained directly by the Scene, its upper-left corner’s location is 50 pixels
to the right and 180 pixels down from the upper-left corner of the Scene. Take a look at Figure 1-4 to see this
example illustrated as you read the rest of the explanation.
14
Chapter 1 ■ Getting a Jump-Start in JavaFX
Figure 1-4. The Scene, Group, Text, and clip illustrated
A Group instance contains instances of Node subclasses by assigning a collection of them to itself via
the children() method. In the previous code snippet, the Group contains a Text instance that has a value
assigned to its layoutY property. Because this Text is contained by a Group, it assumes the two-dimensional
space (also called the coordinate space) of the Group, with the origin of the Text node (0,0) coincident
with the top-left corner of the Group. Assigning a value of 100 to the layoutY property causes the Text to
be located 100 pixels down from the top of the Group, which is just below the bottom of the clip region,
thus causing it to be out of view until the animation begins. Because a value isn’t assigned to the layoutX
variable, its value is 0 (the default).
The layoutX and layoutY properties of the Group just described are examples of our earlier statement
that nodes contained in a Group will be affected by values assigned to properties of the Group. Another
example is setting the opacity property of a Group instance to 0.5, which causes all of the nodes contained in
that Group to become translucent. If the JavaFX API documentation is handy, look at the properties available
in the javafx.scene.Group class. Then look at the properties available in the javafx.scene.Node class
properties, which is where you’ll find the layoutX, layoutY, and opacity variables that are inherited by the
Group class.
15
Chapter 1 ■ Getting a Jump-Start in JavaFX
Clipping Graphical Areas
To define a clipping area, we assign a Node subclass to the clip property that defines the clipping shape,
in this case a Rectangle that is 430 pixels wide and 85 pixels high. In addition to keeping the Text from
covering the moon, when the Text scrolls up as a result of animation, the clipping area keeps the Text from
covering the earth.
Animating the Text to Make It Scroll Up
When the HelloEarthriseMain program is invoked, the Text begins scrolling up slowly. To achieve this
animation, we’re using the TranslateTransition class located in the javafx.animation package, as shown
in the following snippet from Listing 1-1.
TranslateTransition transTransition = new TranslateTransition(new Duration(75000), textRef);
transTransition.setToY(-820);
transTransition.setInterpolator(Interpolator.LINEAR);
transTransition.setCycleCount(Timeline.INDEFINITE);
...code omitted...
// Start the text animation
transTransition.play();
The javafx.animation package contains convenience classes for animating nodes. This
TranslateTransition instance translates the Text node referenced by the textRef variable from its original
Y position of 100 pixels to a Y position of –820 pixels, over a duration of 75 seconds. The Interpolator.
LINEAR constant is assigned to the interpolator property, which causes the animation to proceed in a linear
fashion. A look at the API docs for the Interpolator class in the javafx.animation package reveals that
there are other forms of interpolation available, one of which is EASE_OUT, which slows down the animation
toward the end of the specified duration.
■■Note Interpolation in this context is the process of calculating the value at any point in time, given a
beginning value, an ending value, and a duration.
The last line in the previous snippet begins executing the play method of the TranslateTransition
instance created earlier in the program. This makes the Text begin scrolling upward. Because of the value
assigned to the cycleCount variable, this transition will repeat indefinitely.
Now that you’ve compiled and run this example using the command-line tools and we’ve walked
through the code together, it is time to begin using the NetBeans IDE to make the development and
deployment process faster and easier.
Building and Running the Program with NetBeans
Assuming that you’ve downloaded and extracted the source code for this book into a directory, follow the
directions in this exercise to build and run the Hello Earthrise program in NetBeans. If you haven’t yet
downloaded the Java SDK and NetBeans, please do so from the site listed in the “Resources” section at the
end of this chapter.
16
Chapter 1 ■ Getting a Jump-Start in JavaFX
BUILDING AND RUNNING HELLO EARTHRISE WITH NETBEANS
To build and run the Hello Earthrise program, perform the following steps.
1.
Start NetBeans.
2.
Choose File ➤ New Project from the menu bar. The first window of the New Project
Wizard will appear. Select the JavaFX category, and you will see wizard shown in
Figure 1-5.
Figure 1-5. New Project Wizard
3.
Choose JavaFX Application in the Projects pane, and then click Next. The next page
in the New Project Wizard, shown in Figure 1-6, should appear.
17
Chapter 1 ■ Getting a Jump-Start in JavaFX
Figure 1-6. The next page of the New Project Wizard
4.
On this screen, type the project name (we used HelloEarthRise) and click Browse.
5.
Select a Project Location either by typing it directly into the text box or by
clicking Browse to navigate to the desired directory (we used /home/johan/
NetBeansProjects).
6.
Select the Create Application Class check box, and change the supplied package/
class name to projavafx.helloearthrise.ui.HelloEarthRiseMain
7.
Click Finish. The HelloEarthRise project with a default main class created by
NetBeans should now be created. If you’d like to run this default program, rightclick the HelloEarthRise project in the Projects pane and select Run Project from the
shortcut menu.
8.
Enter the code from Listing 1-1 into the HelloEarthRiseMain.java code window.
You can type it in, or cut and paste it from the HelloEarthRiseMain.java file
located in the Chapter01/HelloEarthRise/src/projavafx/helloearthrise/ui
directory of this book’s source code download.
9.
Right-click the HelloEarthRise project in the Projects pane and select Run Project
from the shortcut menu.
The HelloEarthRise program should begin executing, as you saw in Figure 1-3 earlier in the chapter.
At this point, you’ve built and run the “Hello Earthrise” program application, both from the command
line and using NetBeans. Before leaving this example, we show you another way to achieve the scrolling
Text node. There is a class in the javafx.scene.control package named ScrollPane whose purpose is
18
Chapter 1 ■ Getting a Jump-Start in JavaFX
to provide a scrollable view of a node that is typically larger than the view. In addition, the user can drag
the node being viewed within the scrollable area. Figure 1-7 shows the Hello Earthrise program after being
modified to use the ScrollPane control.
Figure 1-7. Using the ScrollPane control to provide a scrollable view of the Text node
Notice that the move cursor is visible, signifying that the user can drag the node around the clipped
area. Note that the screenshot in Figure 1-7 is of the program running on macOS X, and the move cursor has
a different appearance on other platforms. Listing 1-2 contains the relevant portion of code for this example,
named HelloScrollPaneMain.java.
Listing 1-2. The HelloScrollPaneMain.java Program
...code omitted...
// Create a ScrollPane containing the text
ScrollPane scrollPane = new ScrollPane();
scrollPane.setLayoutX(50);
scrollPane.setLayoutY(180);
scrollPane.setPrefWidth(400);
scrollPane.setPrefHeight(85);
scrollPane.setHbarPolicy(ScrollPane.ScrollBarPolicy.NEVER);
scrollPane.setVbarPolicy(ScrollPane.ScrollBarPolicy.NEVER);
scrollPane.setPannable(true);
scrollPane.setContent(textRef);
scrollPane.setStyle("-fx-background-color: transparent;");
19
Chapter 1 ■ Getting a Jump-Start in JavaFX
// Combine ImageView and ScrollPane
Group root = new Group(imageView, scrollPane);
Scene scene = new Scene(root, 516, 387);
Now that you’ve learned some of the basics of JavaFX application development, let’s examine another
sample application to help you learn more JavaFX concepts and constructs.
Developing Your Second JavaFX Program: “More Cowbell!”
If you’re familiar with the Saturday Night Live television show, you may have seen the “More Cowbell”
sketch, in which Christopher Walken’s character keeps asking for “more cowbell” during a Blue Oyster Cult
recording session. The following JavaFX example program covers some of the simple but powerful concepts
of JavaFX in the context of an imaginary application that lets you select a music genre and control the
volume. Of course, “Cowbell Metal,” shortened to “Cowbell,” is one of the available genres. Figure 1-8 shows
a screenshot of this application, which has a sort of retro iPhone application look.
Figure 1-8. The Audio Configuration “More Cowbell” program
Building and Running the Audio Configuration Program
Earlier in the chapter, we showed you how to create a new JavaFX project in NetBeans. For this example
(and the rest of the examples in the book), we take advantage of the fact that the code download bundle for
the book contains both NetBeans and Eclipse project files for each example. Follow the instructions in this
exercise to build and run the Audio Configuration application.
20
Chapter 1 ■ Getting a Jump-Start in JavaFX
BUILDING AND RUNNING THE AUDIO CONFIGURATION
PROGRAM USING NETBEANS
To build and execute this program using NetBeans, perform the following steps.
1.
From the File menu, select the Open Project menu item. In the Open Project dialog
box, navigate to the Chapter01 directory where you extracted the book’s code
download bundle, as shown in Figure 1-9.
Figure 1-9. The Chapter 01 directory in the Open Project dialog box
2.
Select the AudioConfig project in the pane on the left, and click Open Project.
3.
Run the project as discussed previously.
The application should appear as shown in Figure 1-8.
The Behavior of the Audio Configuration Program
When you run the application, notice that adjusting the volume slider changes the associated decibel
(dB) level displayed. Also, selecting the Muting check box disables the slider, and selecting various genres
changes the volume slider. This behavior is enabled by concepts that are shown in the code that follows,
such as the following:
•
Binding to a class that contains a model
•
Using change listeners
•
Creating observable lists
21
Chapter 1 ■ Getting a Jump-Start in JavaFX
Understanding the Audio Configuration Program
The Audio Configuration program contains two source code files, shown in Listing 1-3 and Listing 1-4:
•
The AudioConfigMain.java file in Listing 1-3 contains the main class, and expresses
the UI in a manner that you are familiar with from the Hello Earthrise example in
Listing 1-1.
•
The AudioConfigModel.java file in Listing 1-4 contains a model for this program,
which holds the state of the application, to which the UI is bound.
Take a look at the AudioConfigMain.java source code in Listing 1-3, after which we examine it together,
focusing on concepts not covered in the previous example.
Listing 1-3. The AudioConfigMain.java Program
package projavafx.audioconfig.ui;
import
import
import
import
import
import
import
import
import
import
import
import
import
import
import
import
import
import
javafx.application.Application;
javafx.geometry.VPos;
javafx.scene.Group;
javafx.scene.Scene;
javafx.scene.control.CheckBox;
javafx.scene.control.ChoiceBox;
javafx.scene.control.Slider;
javafx.scene.paint.Color;
javafx.scene.paint.CycleMethod;
javafx.scene.paint.LinearGradient;
javafx.scene.paint.Stop;
javafx.scene.shape.Line;
javafx.scene.shape.Rectangle;
javafx.scene.text.Font;
javafx.scene.text.FontWeight;
javafx.scene.text.Text;
javafx.stage.Stage;
projavafx.audioconfig.model.AudioConfigModel;
public class AudioConfigMain extends Application {
// A reference to the model
AudioConfigModel acModel = new AudioConfigModel();
Text textDb;
Slider slider;
CheckBox mutingCheckBox;
ChoiceBox genreChoiceBox;
Color color = Color.color(0.66, 0.67, 0.69);
public static void main(String[] args) {
Application.launch(args);
}
22
Chapter 1 ■ Getting a Jump-Start in JavaFX
@Override
public void start(Stage stage) {
Text title = new Text(65,12, "Audio Configuration");
title.setTextOrigin(VPos.TOP);
title.setFill(Color.WHITE);
title.setFont(Font.font("SansSerif", FontWeight.BOLD, 20));
Text textDb = new Text();
textDb.setLayoutX(18);
textDb.setLayoutY(69);
textDb.setTextOrigin(VPos.TOP);
textDb.setFill(Color.web("#131021"));
textDb.setFont(Font.font("SansSerif", FontWeight.BOLD, 18));
Text mutingText = new Text(18, 113, "Muting");
mutingText.setTextOrigin(VPos.TOP);
mutingText.setFont(Font.font("SanSerif", FontWeight.BOLD, 18));
mutingText.setFill(Color.web("#131021"));
Text genreText = new Text(18,154,"Genre");
genreText.setTextOrigin(VPos.TOP);
genreText.setFill(Color.web("#131021"));
genreText.setFont(Font.font("SanSerif", FontWeight.BOLD, 18));
slider = new Slider();
slider.setLayoutX(135);
slider.setLayoutY(69);
slider.setPrefWidth(162);
slider.setMin(acModel.minDecibels);
slider.setMax(acModel.maxDecibels);
mutingCheckBox = new CheckBox();
mutingCheckBox.setLayoutX(280);
mutingCheckBox.setLayoutY(113);
genreChoiceBox = new ChoiceBox();
genreChoiceBox.setLayoutX(204);
genreChoiceBox.setLayoutY(154);
genreChoiceBox.setPrefWidth(93);
genreChoiceBox.setItems(acModel.genres);
Stop[] stops = new Stop[]{new Stop(0, Color.web("0xAEBBCC")), new Stop(1, Color.
web("0x6D84A3"))};
LinearGradient linearGradient = new LinearGradient(0, 0, 0, 1, true, CycleMethod.
NO_CYCLE, stops);
Rectangle rectangle = new Rectangle(0, 0, 320, 45);
rectangle.setFill(linearGradient);
Rectangle rectangle2 = new Rectangle(0, 43, 320, 300);
rectangle2.setFill(Color.rgb(199, 206, 213));
23
Chapter 1 ■ Getting a Jump-Start in JavaFX
Rectangle rectangle3 = new Rectangle(8, 54, 300, 130);
rectangle3.setArcHeight(20);
rectangle3.setArcWidth(20);
rectangle3.setFill(Color.WHITE);
rectangle3.setStroke(color);
Line line1 = new Line(9, 97, 309, 97);
line1.setStroke(color);
Line line2 = new Line(9, 141, 309, 141);
line2.setFill(color);
Group group = new Group(rectangle, title, rectangle2, rectangle3,
textDb,
slider,
line1,
mutingText,
mutingCheckBox, line2, genreText,
genreChoiceBox);
Scene scene = new Scene(group, 320, 343);
textDb.textProperty().bind(acModel.selectedDBs.asString().concat(" dB"));
slider.valueProperty().bindBidirectional(acModel.selectedDBs);
slider.disableProperty().bind(acModel.muting);
mutingCheckBox.selectedProperty().bindBidirectional(acModel.muting);
acModel.genreSelectionModel = genreChoiceBox.getSelectionModel();
acModel.addListenerToGenreSelectionModel();
acModel.genreSelectionModel.selectFirst();
stage.setScene(scene);
stage.setTitle("Audio Configuration");
stage.show();
}
}
Now that you’ve seen the main class in this application, let’s walk through the new concepts.
The Magic of Binding
One of the most powerful aspects of JavaFX is binding, which enables the application’s UI to easily stay in
sync with the state, or model, of the application. The model for a JavaFX application is typically held in one
or more classes, in this case the AudioConfigModel class. Look at the following snippet, taken from
Listing 1-3, in which we create an instance of this model class.
AudioConfigModel acModel = new AudioConfigModel();
There are several graphical node instances in the scene of this UI (recall that a scene consists of a
sequence of nodes). Skipping past several of them, we come to the graphical nodes shown in the following
snippet that have a property bound to the selectedDBs property in the model.
24
Chapter 1 ■ Getting a Jump-Start in JavaFX
textDb = new Text();
... code omitted
slider = new Slider();
...code omitted...
textDb.textProperty().bind(acModel.selectedDBs.asString().concat(" dB"));
slider.valueProperty().bindBidirectional(acModel.selectedDBs);
As shown in this code, the text property of the Text object is bound to an expression. The bind function
contains an expression (that includes the selectedDBs property), which is evaluated and becomes the value
of the text property. Look at Figure 1-9 (or check the running application) to see the content value of the Text
node displayed to the left of the slider.
Notice also in the code that the value property of the Slider node is bound to the selectedDBs
property in the model as well, but that it uses the bindBidirectional() method. This causes the bind to
be bidirectional, so in this case when the slider is moved, the selectedDBs property in the model changes.
Conversely, when the selectedDBs property changes (as a result of changing the genre), the slider moves.
Go ahead and move the slider to demonstrate the effects of the bind expressions in the snippet. The
number of decibels displayed at the left of the slider should change as the slider is adjusted.
There are other bound properties in Listing 1-3 that we point out when we walk through the model
class. Before leaving the UI, we point out some color-related concepts in this example.
Colors and Gradients
The following snippet from Listing 1-3 contains an example of defining a color gradient pattern, as well as
defining colors.
Stop[] stops = new Stop[]{new Stop(0, Color.web("0xAEBBCC")), new Stop(1, Color.
web("0x6D84A3"))};
LinearGradient linearGradient = new LinearGradient(0, 0, 0, 1, true, CycleMethod.NO_CYCLE,
stops);
Rectangle rectangle = new Rectangle(0, 0, 320, 45);
rectangle.setFill(linearGradient);
If the JavaFX API docs are handy, first take a look at the javafx.scene.shape.Rectangle class and
notice that it inherits a property named fill that is of type javafx.scene.paint.Paint. Looking at
the JavaFX API docs for the Paint class, you’ll see that the Color, ImagePattern, LinearGradient, and
RadialGradient classes are subclasses of Paint. This means that the fill of any shape can be assigned a
color, pattern, or gradient.
To create a LinearGradient, as shown in the code, you need to define at least two stops, which define
the location and color at that location. In this example, the offset value of the first stop is 0.0, and the offset
value of the second stop is 1.0. These are the values at both extremes of the unit square, the result being that
the gradient will span the entire node (in this case a Rectangle). The direction of the LinearGradient is
controlled by its startX, startY, endX, and endY values, which we pass via the constructor. In this case, the
direction is only vertical because the startY value is 0.0 and the endY value is 1.0, whereas the startX and
endX values are both 0.0.
Note that in the Hello Earthrise example in Listing 1-1, the constant named Color.WHITE was used to
represent the color white. In the previous snippet, the web function of the Color class is used to define a
color from a hexadecimal value.
25
Chapter 1 ■ Getting a Jump-Start in JavaFX
The Model Class for the Audio Configuration Example
Take a look at the source code for the AudioConfigModel class in Listing 1-4.
Listing 1-4. The Source Code for AudioConfigModel.java
package projavafx.audioconfig.model;
import
import
import
import
import
import
import
import
javafx.beans.Observable;
javafx.beans.property.BooleanProperty;
javafx.beans.property.IntegerProperty;
javafx.beans.property.SimpleBooleanProperty;
javafx.beans.property.SimpleIntegerProperty;
javafx.collections.FXCollections;
javafx.collections.ObservableList;
javafx.scene.control.SingleSelectionModel;
/**
* The model class that the AudioConfigMain class uses
*/
public class AudioConfigModel {
/**
* The minimum audio volume in decibels
*/
public double minDecibels = 0.0;
/**
* The maximum audio volume in decibels
*/
public double maxDecibels = 160.0;
/**
* The selected audio volume in decibels
*/
public IntegerProperty selectedDBs = new SimpleIntegerProperty(0);
/**
* Indicates whether audio is muted
*/
public BooleanProperty muting = new SimpleBooleanProperty(false);
/**
* List of some musical genres
*/
public ObservableList genres = FXCollections.observableArrayList(
"Chamber",
"Country",
"Cowbell",
"Metal",
"Polka",
"Rock"
);
26
Chapter 1 ■ Getting a Jump-Start in JavaFX
/**
* A reference to the selection model used by the Slider
*/
public SingleSelectionModel genreSelectionModel;
/**
* Adds a change listener to the selection model of the ChoiceBox, and contains
* code that executes when the selection in the ChoiceBox changes.
*/
public void addListenerToGenreSelectionModel() {
genreSelectionModel.selectedIndexProperty().addListener((Observable o) -> {
int selectedIndex = genreSelectionModel.selectedIndexProperty().getValue();
switch(selectedIndex) {
case 0: selectedDBs.setValue(80);
break;
case 1: selectedDBs.setValue(100);
break;
case 2: selectedDBs.setValue(150);
break;
case 3: selectedDBs.setValue(140);
break;
case 4: selectedDBs.setValue(120);
break;
case 5: selectedDBs.setValue(130);
}
});
}
}
Using InvalidationListeners and Lambda Expressions
In the “The Magic of Binding” section, we showed how you can use property binding for dynamically
changing parameters. There is another, more low-level but also more flexible way of achieving this, using
ChangeListeners and InvalidationListeners. These concepts are discussed in more detail in Chapter 4.
In our example, we add an InvalidationListener to the selectedIndexProperty of the
genreSelectionModel. When the value of the selectedIndexProperty changes, and when we didn’t retrieve
it yet, the invalidated(Observable) method on the added InvalidationListener will be called. In the
implementation of this method, we retrieve the value of the selectedIndexProperty, and based on its value,
the value of the selectedDBs property is changed. This is achieved with the following code:
public void addListenerToGenreSelectionModel() {
genreSelectionModel.selectedIndexProperty().addListener((Observable o) -> {
int selectedIndex = genreSelectionModel.selectedIndexProperty().getValue();
switch(selectedIndex) {
case 0: selectedDBs.setValue(80);
break;
case 1: selectedDBs.setValue(100);
break;
case 2: selectedDBs.setValue(150);
break;
27
Chapter 1 ■ Getting a Jump-Start in JavaFX
case 3: selectedDBs.setValue(140);
break;
case 4: selectedDBs.setValue(120);
break;
case 5: selectedDBs.setValue(130);
}
});
}
Note that we are using a lambda expression here rather than creating a new instance of the
InvalidationListener and implementing its single abstract method invalidated.
■■Tip One of the major enhancements in JavaFX 8 is the fact that it is using Java 8. As a consequence,
abstract classes with a single abstract method can easily be replaced by lambda expressions, which clearly
enhance the readability of the code.
What causes selectedIndexProperty of the genreSelectionModel to change? To see the answer to this,
we have to revisit some code in Listing 1-3. In the following code snippet, the setItems method of ChoiceBox
is used to populate the ChoiceBox with items that each contain a genre.
genreChoiceBox = new ChoiceBox();
genreChoiceBox.setLayoutX(204);
genreChoiceBox.setLayoutY(154);
genreChoiceBox.setPrefWidth(93);
genreChoiceBox.setItems(acModel.genres);
This snippet from the model code in Listing 1-4 contains the collection to which the ComboBox items are
bound:
/**
* List of some musical genres
*/
public ObservableList genres = FXCollections.observableArrayList(
"Chamber",
"Country",
"Cowbell",
"Metal",
"Polka",
"Rock"
);
When the user chooses a different item in the ChoiceBox, the invalidationListener is invoked.
Looking again at the code in the invalidationListener, you’ll see that the value of the selectedDBs
property changes, which as you may recall, is bidirectionally bound to the slider. This is why the slider moves
when you select a genre in the combo box. Go ahead and test this by running the Audio Config program.
28
Chapter 1 ■ Getting a Jump-Start in JavaFX
■■Note
Associating the items property of the ChoiceBox with an ObservableList causes the items in the
ChoiceBox to be automatically updated when the elements in the underlying collection are modified.
Surveying JavaFX Features
We close this chapter by surveying many of the features of JavaFX, some of which are a review for you. We do
this by describing several of the more commonly used packages and classes in the Java SDK API.
The javafx.stage package contains the following:
•
The Stage class, which is the top level of the UI containment hierarchy for any
JavaFX application, regardless of where it is deployed (e.g., the desktop, a browser, or
a cell phone).
•
The Screen class, which represents the displays on the machine in which a JavaFX
program is running. This enables you to get information about the screens, such as
size and resolution.
The javafx.scene package contains some classes that you’ll use often:
•
The Scene class is the second level of the UI containment hierarchy for JavaFX
applications. It includes all of the UI elements contained in the application. These
elements are called graphical nodes, or simply nodes.
•
The Node class is the base class of all of the graphical nodes in JavaFX. UI elements
such as text, images, media, shapes, and controls (e.g., text boxes and buttons) are all
subclasses of Node. Take a moment to look at the variables and functions in the Node
class to appreciate the capabilities provided to all of its subclasses, including bounds
calculation and mouse and keyboard event handling.
•
The Group class is a subclass of the Node class. Its purpose includes grouping nodes
together into a single coordinate space and allowing transforms (e.g., rotate) to be
applied to the whole group. Also, attributes of the group that are changed
(e.g., opacity) apply to all of the nodes contained within the group.
Several packages begin with javafx.scene that contain subclasses of Node of various types. Examples
include the following:
•
The javafx.scene.image package contains the Image and ImageView classes,
which enable images to be displayed in the Scene. The ImageView class is a
subclass of Node.
•
The javafx.scene.shape package contains several classes for drawing shapes such
as Circle, Rectangle, Line, Polygon, and Arc. The base class of the shapes, named
Shape, contains an attribute named fill that enables you to specify a color, pattern,
or gradient with which to fill the shape.
•
The javafx.scene.text package contains the Text class for drawing text in the
scene. The Font class enables you to specify the font name and size of the text.
•
The javafx.scene.media package has classes that enable you to play media. The
MediaView class is a subclass of Node that displays the media.
•
The javafx.scene.chart package has classes that help you easily create area, bar,
bubble, line, pie, and scatter charts. The corresponding UI classes in this package are
AreaChart, BarChart, BubbleChart, LineChart, PieChart, and ScatterChart.
29
Chapter 1 ■ Getting a Jump-Start in JavaFX
Here are some other packages in the JavaFX 8 API.
•
The javafx.scene.control package contains several UI controls, each one having
the ability to be skinned and styled via CSS.
•
The javafx.scene.transform package enables you to transform nodes (scale, rotate,
translate, shear, and affine).
•
The javafx.scene.input package contains classes such as MouseEvent and
KeyEvent that provide information about these events from within an event handler
function such as the Node class’s onMouseClicked event.
•
The javafx.scene.layout package contains several layout containers, including
HBox, VBox, BorderPane, FlowPane, StackPane, and TilePane.
•
The javafx.scene.effect package contains easy-to-use effects such as Reflection,
Glow, Shadow, BoxBlur, and Lighting.
•
The javafx.scene.web package contains classes for easily embedding a web
browser in your JavaFX applications.
•
The javafx.animation package contains time-based interpolations typically used
for animation and convenience classes for common transitions.
•
The javafx.beans, javafx.beans.binding, javafx.beans.property, and javafx.
beans.value packages contain classes that implement properties and binding.
•
The javafx.fxml package contains classes that implement a very powerful facility
known as FXML, a markup language for expressing JavaFX UIs in XML.
•
The javafx.util package contains utility classes such as the Duration class used in
the HelloEarthRise example.
•
The javafx.print package contains utilities for printing (parts of ) the layout of a
JavaFX application.
•
The javafx.embed.swing package contains the required functionality for embedded
JavaFX applications in a Swing application.
•
The javafx.embed.swt package contains the required functionality for embedding
JavaFX applications in an SWT application.
Take a look at the JavaFX API docs again in light of this information to get a deeper sense of how you can
use its capabilities.
Summary
Congratulations! You learned a lot about JavaFX in this chapter, including
30
•
JavaFX is rich-client Java, and is needed by the software development industry.
•
Since the Java 9 release, the JavaFX APIs are split in a number of modules that follow
the Java 9 conventions and rules.
•
Some of the high points of the history of JavaFX.
•
Where to find JavaFX resources, including the Java SDK, NetBeans, Scene Builder,
ScenicView, and the API documentation.
Chapter 1 ■ Getting a Jump-Start in JavaFX
•
How to compile and run a JavaFX program from the command line.
•
How to build and run a JavaFX program using NetBeans.
•
How to use several of the classes in the JavaFX API.
•
How to create a class in JavaFX and use it as a model that contains the state of a
JavaFX application.
•
How to use property binding to keep the UI easily in sync with the model.
We also looked at many of the available API packages and classes, and you learned how you can
leverage their capabilities. Now that you have a jump-start in JavaFX, you can begin examining the details of
JavaFX in Chapter 2.
Resources
For some background information on JavaFX, you can consult the following resources.
•
This book’s code examples: The Source Code/Download section on the Apress
web site (www.apress.com).
•
Java Posse #163: Newscast for February 8, 2008: This is a podcast of a Java Posse
interview with Josh Marinacci and Richard Bair on the subject of JavaFX.
(http://javaposse.com/java_posse_163_newscast_for_feb_8th_2008).
•
“Congratulations to the JavaFX Script Compiler Team—The Elephant Is Through the
Door”: A blog post by one of this book’s authors, Jim Weaver, that congratulated the
JavaFX compiler team for reaching a tipping point in the project.
(http://learnjavafx.typepad.com/weblog/2007/12/congratulations.html).
•
Oracle’s JavaFX.com site: The home page for JavaFX where you can download the
JavaFX SDK and other resource for JavaFX. (www.javafx.com)
•
FX Experience: A blog maintained by Oracle JavaFX Engineers Richard Bair, Jasper
Potts, and Jonathan Giles. (http://fxexperience.com)
•
Jim Weaver’s JavaFX Blog: A blog, started in October 2007, the stated purpose of
which is to help the reader become a “JavaFXpert.” (http://javafxpert.com)
•
Weiqi Gao’s Observation: A blog in which Weiqi Gao shares his experience in
software development. (http://weiqigao.blogspot.com)
•
Dean Iverson’s Pleasing Software Blog: A blog in which Dean Iverson shares his
innovations in JavaFX and GroovyFX. (http://pleasingsoftware.blogspot.com)
•
Steve on Java: A blog in which Stephen Chin keeps the world updated on his tireless
exploits in the areas of JavaFX, Java, and Agile development. (http://steveonjava.com)
•
Johan’s blog: A blog in which Johan Vos discusses JavaFX and Java Enterprise.
(http://blogs.lodgon.com/johan)
•
JavaFX Eclipse Plugin: Eclipse tooling for JavaFX 2.0, developed by Tom Shindl.
(http://tomsondev.bestsolution.at/2011/06/24/introducing-efxclipse/)
31
Chapter 1 ■ Getting a Jump-Start in JavaFX
32
•
Scenic View: An application for inspecting the scenegraph of your JavaFX
applications. (http://scenic-view.org)
•
Gluon web site: (http://gluonhq.com)
•
ControlsFX, high-quality custom JavaFX controls. (http://controlsfx.org)
•
JFXtras.org, high-quality custom JavaFX controls. (http://jfxtras.org)
CHAPTER 2
Creating a User Interface in JavaFX
Life is the art of drawing without an eraser.
—John W. Gardner
Chapter 1 gave you a jump start using JavaFX by covering the basics in developing and executing JavaFX
programs. Now we cover many of the details about creating a UI in JavaFX that were glossed over in Chapter 1.
First on the agenda is to get you acquainted with the theater metaphor used by JavaFX to express UIs and to
cover the significance of what we call a node-centric UI.
Programmatic vs. Declarative Creation of the User Interface
The JavaFX platform provides two complementary ways for creating a UI. In this chapter, we discuss how
you can use the Java API to create and populate a UI. This is a convenient way for Java developers who are
used to writing code to leverage APIs.
Designers often use graphical tools that allow them to declare rather than program a UI. The JavaFX
platform defines FXML, which is an XML-based markup language that can be used to declaratively describe
a UI. Furthermore, a graphical tool called Scene Builder is made available by Gluon, and this tool is capable
of working with FXML files. The use of Scene Builder is demonstrated in Chapter 4.
Note that parts of a UI can be created using the API, where other parts can be created using Scene
Builder. The FXML APIs provide the bridge and the integration glue between the two approaches.
Introduction to Node-Centric UIs
Creating a UI in JavaFX is like creating a theater play, in that it typically consists of these very simple steps:
1.
Create a stage on which your program will perform. The realization of your stage
will depend on the platform on which it is deployed (e.g., a desktop, a tablet, or
an embedded system).
2.
Create a scene in which the actors and props (nodes) will visually interact with
each other and the audience (the users of your program). Like any good set
designer in the theater business, good JavaFX developers endeavor to make their
scenes visually appealing. To this end, it is often a good idea to collaborate with a
graphic designer on your “theater play.”
© Johan Vos, Stephen Chin, Weiqi Gao, James Weaver, and Dean Iverson 2018
J. Vos et al., Pro JavaFX 9, https://doi.org/10.1007/978-1-4842-3042-8_2
33
Chapter 2 ■ Creating a User Interface in JavaFX
3.
Create nodes in the scene. These nodes are subclasses of the javafx.scene.Node
class, which include UI controls, shapes, Text (a type of shape), images, media
players, embedded browsers, and custom UI components that you create. Nodes
can also be containers for other nodes, often providing cross-platform layout
capabilities. A scene has a scene graph that contains a directed graph of nodes.
Individual nodes and groups of nodes can be manipulated in many ways
(e.g., moving, scaling, and setting opacity) by changing the values of a very rich
set of Node properties.
4.
Create variables and classes that represent the model for the nodes in the scene.
As discussed in Chapter 1, one of the very powerful aspects of JavaFX is binding,
which enables the application’s UI to stay in sync easily with the state, or model,
of the application.
■■Note Most of the examples in this chapter are small programs intended to demonstrate UI concepts. For
this reason, the model in many of these examples consists of variables appearing in the main program, rather
than being contained by separate Java classes (e.g., the AudioConfigModel class in Chapter 1).
5.
Create event handlers, such as onMousePressed, that allow the user to interact
with your program. Often these event handlers manipulate instance variables
in the model. Many of these handlers require a single abstract method to be
implemented, and as a consequence provide a perfect opportunity to use
lambda expressions.
6.
Create timelines and transitions that animate your scene. For example, you might
want the thumbnail images of a list of books to move smoothly across the scene
or a page in the UI to fade into view. You might simply want a ping-pong ball to
move across the scene, bouncing off walls and paddles; this is demonstrated later
in this chapter in the “The Zen of Node Collision Detection” section.
Let’s get started with a closer look at step 1, in which we examine the capabilities of the stage.
Setting the Stage
The appearance and functionality of your stage will depend on the platform on which it is deployed. For
example, if deployed in a mobile device, or an embedded device with a touch screen, your stage might be the
whole touch screen. The stage for a JavaFX program deployed in an X11 system will be a window.
Understanding the Stage Class
The Stage class is the top-level container for any JavaFX program that has a graphical UI. It has several
properties and methods that allow it, for example, to be positioned, sized, given a title, made invisible, or
given some degree of opacity. The two best ways that we know of to learn the capabilities of a class are to
study the JavaFX API documentation and to examine (and write) programs that use it. In this section, we ask
you to do both, beginning with looking at the API docs.
34
Chapter 2 ■ Creating a User Interface in JavaFX
The JavaFX API docs, just like the other Java API docs, are available online at the http://download.java.
net/java/jdk9/docs/api/overview-summary. Open the index.html file in your browser, navigate to the
javafx.stage package in the javafx.graphics module, and select the Stage class. That page should contain
tables of Properties, Constructors, and Methods, including select ones shown in the excerpt in Figure 2-1.
Figure 2-1. A portion of the Stage class documentation in the JavaFX API
Go ahead and explore the documentation for each of the properties and methods in the Stage class,
remembering to click the links to reveal more detailed information. When you’re finished, come back
and we’ll show you a program that demonstrates many of the properties and methods available in the
Stage class.
Using the Stage Class: The StageCoach Example
A screenshot of the unassuming, purposely ill-fitting StageCoach example program is shown in Figure 2-2.
35
Chapter 2 ■ Creating a User Interface in JavaFX
Figure 2-2. A screenshot of the StageCoach example
The StageCoach program was created to coach you through the finer points of using the Stage class
and related classes such as StageStyle and Screen. Also, we use this program to show you how to get
arguments passed into the program. Before walking through the behavior of the program, go ahead and
open the project. Follow the instructions for building and executing the Audio-Config project in Chapter 1.
The project file is located in the Chapter02 directory subordinate to where you extracted the book’s code
download bundle.
EXAMINING THE BEHAVIOR OF THE STAGECOACH PROGRAM
When the program starts, its appearance should be similar to the screenshot in Figure 2-2. To fully
examine its behavior, perform the following steps. Note that for instructional purposes, the property and
method names on the UI correspond to the properties and methods in the Stage instance.
Notice that the StageCoach program’s window is initially displayed near the top of the screen, with its
horizontal position in the center of the screen. Drag the program’s window and observe that the x and y
values near the top of the UI are dynamically updated to reflect its position on the screen.
Resize the program’s window and observe that the width and height values change to reflect the
width and height of the Stage. Note that this size includes the decorations (title bar and borders) of the
window.
Click the program (or cause it to be in focus some other way) and notice that the focused value is true.
Cause the window to lose focus, perhaps by clicking somewhere else on the screen, and notice that the
focused value becomes false.
36
Chapter 2 ■ Creating a User Interface in JavaFX
Clear the resizable check box and then notice that the resizable value becomes false. Then try to resize
the window and note that it is not permitted. Select the resizable check box again to make the window
resizable.
Select the fullScreen check box. Notice that the program occupies the full screen and that the window
decorations are not visible. Clear the fullScreen check box to restore the program to its former size.
Edit the text in the text field beside the title label, noticing that the text in the window’s title bar is
changed to reflect the new value.
Drag the window to partially cover another window, and click toBack(). Notice that this places the
program behind the other window, therefore causing the z-order to change.
With a portion of the program’s window behind another window, but with the toFront() button visible,
click that button. Notice that the program’s window is placed in front of the other window.
Click close(), noticing that the program exits.
Invoke the program again, passing in the string "undecorated". If invoking from NetBeans, use the
Project Properties dialog box to pass this argument as shown in Figure 2-3. The "undecorated" string
is passed as a parameter without a value.
Figure 2-3. Using NetBeans’ Project Properties dialog box to pass an argument into the program
37
Chapter 2 ■ Creating a User Interface in JavaFX
Notice that this time the program appears without any window decorations, but the white background
of the program includes the background of the window. The black outline in the screenshot shown in
Figure 2-4 is part of the desktop background.
Exit the program again by clicking close( ), and then run the program again, passing in the string
"transparent" as the argument. Notice that the program appears in the shape of a rounded rectangle,
as shown in Figure 2-5.
Figure 2-4. The StageCoach program after being invoked with the undecorated argument
■■Note You might have noticed that the screenshots in Figures 2-4 and 2-5 have y values that are negative.
This is because the application was positioned on the secondary monitor, logically above the primary monitor,
when the screenshots were taken.
38
Chapter 2 ■ Creating a User Interface in JavaFX
Figure 2-5. The StageCoach program after being invoked with the transparent argument
Click the application’s UI, drag it around the screen, and click close( )when finished. Congratulations
on sticking with this 13-step exercise! Performing this exercise has prepared you to relate to the code
behind it, which we now walk through together.
Understanding the StageCoach Program
Take a look at the code for the StageCoach program in Listing 2-1 before we point out new and relevant
concepts.
Listing 2-1. StageCoachMain.java
package projavafx.stagecoach.ui;
import java.util.List;
import javafx.application.Application;
import javafx.beans.property.SimpleStringProperty;
import javafx.beans.property.StringProperty;
import javafx.geometry.Rectangle2D;
import javafx.geometry.VPos;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.CheckBox;
import javafx.scene.control.Label;
import javafx.scene.control.TextField;
import javafx.scene.input.MouseEvent;
import javafx.scene.layout.HBox;
import javafx.scene.layout.VBox;
39
Chapter 2 ■ Creating a User Interface in JavaFX
import
import
import
import
import
import
import
javafx.scene.paint.Color;
javafx.scene.shape.Rectangle;
javafx.scene.text.Text;
javafx.stage.Screen;
javafx.stage.Stage;
javafx.stage.StageStyle;
javafx.stage.WindowEvent;
public class StageCoachMain extends Application {
StringProperty title = new SimpleStringProperty();
Text textStageX;
Text textStageY;
Text textStageW;
Text textStageH;
Text textStageF;
CheckBox checkBoxResizable;
CheckBox checkBoxFullScreen;
double dragAnchorX;
double dragAnchorY;
public static void main(String[] args) {
Application.launch(args);
}
@Override
public void start(Stage stage) {
StageStyle stageStyle = StageStyle.DECORATED;
List unnamedParams = getParameters().getUnnamed();
if (unnamedParams.size() > 0) {
String stageStyleParam = unnamedParams.get(0);
if (stageStyleParam.equalsIgnoreCase("transparent")) {
stageStyle = StageStyle.TRANSPARENT;
} else if (stageStyleParam.equalsIgnoreCase("undecorated")) {
stageStyle = StageStyle.UNDECORATED;
} else if (stageStyleParam.equalsIgnoreCase("utility")) {
stageStyle = StageStyle.UTILITY;
}
}
final Stage stageRef = stage;
Group rootGroup;
TextField titleTextField;
Button toBackButton = new Button("toBack()");
toBackButton.setOnAction(e -> stageRef.toBack());
Button toFrontButton = new Button("toFront()");
toFrontButton.setOnAction(e -> stageRef.toFront());
Button closeButton = new Button("close()");
closeButton.setOnAction(e -> stageRef.close());
Rectangle blue = new Rectangle(250, 350, Color.SKYBLUE);
40
Chapter 2 ■ Creating a User Interface in JavaFX
blue.setArcHeight(50);
blue.setArcWidth(50);
textStageX = new Text();
textStageX.setTextOrigin(VPos.TOP);
textStageY = new Text();
textStageY.setTextOrigin(VPos.TOP);
textStageH = new Text();
textStageH.setTextOrigin(VPos.TOP);
textStageW = new Text();
textStageW.setTextOrigin(VPos.TOP);
textStageF = new Text();
textStageF.setTextOrigin(VPos.TOP);
checkBoxResizable = new CheckBox("resizable");
checkBoxResizable.setDisable(stageStyle == StageStyle.TRANSPARENT
|| stageStyle == StageStyle.UNDECORATED);
checkBoxFullScreen = new CheckBox("fullScreen");
titleTextField = new TextField("Stage Coach");
Label titleLabel = new Label("title");
HBox titleBox = new HBox(titleLabel, titleTextField);
VBox contentBox = new VBox(
textStageX, textStageY, textStageW, textStageH, textStageF,
checkBoxResizable, checkBoxFullScreen,
titleBox, toBackButton, toFrontButton, closeButton);
contentBox.setLayoutX(30);
contentBox.setLayoutY(20);
contentBox.setSpacing(10);
rootGroup = new Group(blue, contentBox);
Scene scene = new Scene(rootGroup, 270, 370);
scene.setFill(Color.TRANSPARENT);
//when mouse button is pressed, save the initial position of screen
rootGroup.setOnMousePressed((MouseEvent me) -> {
dragAnchorX = me.getScreenX() - stageRef.getX();
dragAnchorY = me.getScreenY() - stageRef.getY();
});
//when screen is dragged, translate it accordingly
rootGroup.setOnMouseDragged((MouseEvent me) -> {
stageRef.setX(me.getScreenX() - dragAnchorX);
stageRef.setY(me.getScreenY() - dragAnchorY);
});
textStageX.textProperty().bind(new SimpleStringProperty("x: ")
.concat(stageRef.xProperty().asString()));
textStageY.textProperty().bind(new SimpleStringProperty("y: ")
.concat(stageRef.yProperty().asString()));
textStageW.textProperty().bind(new SimpleStringProperty("width: ")
.concat(stageRef.widthProperty().asString()));
textStageH.textProperty().bind(new SimpleStringProperty("height: ")
.concat(stageRef.heightProperty().asString()));
41
Chapter 2 ■ Creating a User Interface in JavaFX
textStageF.textProperty().bind(new SimpleStringProperty("focused: ")
.concat(stageRef.focusedProperty().asString()));
stage.setResizable(true);
checkBoxResizable.selectedProperty()
.bindBidirectional(stage.resizableProperty());
checkBoxFullScreen.selectedProperty().addListener((ov, oldValue, newValue) -> {
stageRef.setFullScreen(checkBoxFullScreen.selectedProperty().getValue());
});
title.bind(titleTextField.textProperty());
stage.setScene(scene);
stage.titleProperty().bind(title);
stage.initStyle(stageStyle);
stage.setOnCloseRequest((WindowEvent we) -> {
System.out.println("Stage is closing");
});
stage.show();
Rectangle2D primScreenBounds = Screen.getPrimary().getVisualBounds();
stage.setX((primScreenBounds.getWidth() - stage.getWidth()) / 2);
stage.setY((primScreenBounds.getHeight() - stage.getHeight()) / 4);
}
}
Obtaining Program Arguments
The first new concept introduced by this program is the ability to read the arguments passed into a JavaFX
program. The javafx.application package includes a class named Application that has application life
cycle-related methods such as launch(), init(), start(), and stop(). Another method in the Application
class is getParameters(), which gives the application access to the arguments passed on the command line,
as well as unnamed parameters and pairs specified in a JNLP file. Here’s the relevant code
snippet from Listing 2-1 for your convenience:
StageStyle stageStyle = StageStyle.DECORATED;
List unnamedParams = getParameters().getUnnamed();
if (unnamedParams.size() > 0) {
String stageStyleParam = unnamedParams.get(0);
if (stageStyleParam.equalsIgnoreCase("transparent")) {
stageStyle = StageStyle.TRANSPARENT;
}
else if (stageStyleParam.equalsIgnoreCase("undecorated")) {
stageStyle = StageStyle.UNDECORATED;
}
else if (stageStyleParam.equalsIgnoreCase("utility")) {
stageStyle = StageStyle.UTILITY;
}
}
...code omitted...
stage.initStyle(stageStyle);
42
Chapter 2 ■ Creating a User Interface in JavaFX
Setting the Style of the Stage
We’re using the getParameters() method described previously to get an argument that tells us whether the
stage style of the Stage instance should be its default (StageStyle.DECORATED), StageStyle.UNDECORATED,
or StageStyle.TRANSPARENT. You saw the effects of each in the preceding exercise, specifically in Figures 2-2,
2-4, and 2-5.
Controlling Whether a Stage Is Resizable
As shown in the following excerpt from Listing 2-1, to make this application’s window initially resizable
we’re calling the setResizable() method of the Stage instance. To keep the resizable property of the Stage
and the state of the resizable check box synchronized, the check box is bidirectionally bound to the resizable
property of the Stage instance.
stage.setResizable(true);
checkBoxResizable.selectedProperty()
.bindBidirectional(stage.resizableProperty());
■■Tip A property that is bound cannot be explicitly set. In the code preceding the snippet, the resizable
property is set with the setResizable() method before the property is bound in the next line.
Making a Stage Full Screen
Making the Stage show in full-screen mode is done by setting the fullScreen property of the Stage instance
to true. As shown in the following snippet from Listing 2-1, to keep the fullScreen property of the Stage and
the state of the fullScreen check box synchronized, the fullScreen property of the Stage instance is updated
whenever the selected property of the checkBox changes.
checkBoxFullScreen.selectedProperty().addListener((ov, oldValue, newValue) -> {
stageRef.setFullScreen(checkBoxFullScreen.selectedProperty().getValue());
});
Note that the full-screen mode doesn’t have an impact on some platforms. On mobile, for example, the
JavaFX applications will by default be in full-screen mode, and the distribution for JavaFX on Mobile does
not allow a non-full-screen option because that does not make sense in the world of mobile apps on devices.
Working with the Bounds of the Stage
The bounds of the Stage are represented by its x, y, width, and height properties, the values of which can
be changed at will. This is demonstrated in the following snippet from Listing 2-1 where the Stage is placed
near the top and centered horizontally on the primary screen after the Stage has been initialized.
Rectangle2D primScreenBounds = Screen.getPrimary().getVisualBounds();
stage.setX((primScreenBounds.getWidth() - stage.getWidth()) / 2);
stage.setY((primScreenBounds.getHeight() - stage.getHeight()) / 4);
43
Chapter 2 ■ Creating a User Interface in JavaFX
We’re using the Screen class of the javafx.stage package to get the dimensions of the primary screen
so that the desired position may be calculated.
■■Note We intentionally made the Stage in Figure 2-2 larger than the Scene contained within to make the
following point. The width and height of a Stage include its decorations (title bar and border), which vary on
different platforms. It is therefore usually better to control the width and height of the Scene (we show you how
in a bit) and let the Stage conform to that size.
Drawing Rounded Rectangles
As pointed out in Chapter 1, you can put rounded corners on a Rectangle by specifying the arcWidth and
arcHeight for the corners. The following snippet from Listing 2-1 draws the sky-blue rounded rectangle that
becomes the background for the transparent window example in Figure 2-5.
Rectangle blue = new Rectangle(250, 350, Color.SKYBLUE);
blue.setArcHeight(50);
blue.setArcWidth(50);
In this snippet, we use the three-argument constructor of Rectangle, in which the first two parameters
specify the width and the height of the Rectangle. The third parameter defines the fill color of the
Rectangle.
As you can detect from this code snippet, rounded rectangles are easily created using the
arcWidth(double v) and arcHeight(double v) methods, where the parameter v defines the diameter of
the arc.
Dragging the Stage on the Desktop When a Title Bar Isn’t Available
The Stage may be dragged on the desktop using its title bar, but in the case where its StageStyle is
UNDECORATED or TRANSPARENT, the title bar isn’t available. To allow dragging in this circumstance, we added
the code shown in the following code snippet from Listing 2-1.
//when mouse button is pressed, save the initial position of screen
rootGroup.setOnMousePressed((MouseEvent me) -> {
dragAnchorX = me.getScreenX() - stageRef.getX();
dragAnchorY = me.getScreenY() - stageRef.getY();
});
//when screen is dragged, translate it accordingly
rootGroup.setOnMouseDragged((MouseEvent me) -> {
stageRef.setX(me.getScreenX() - dragAnchorX);
stageRef.setY(me.getScreenY() - dragAnchorY);
});
Event handlers are covered a little later in the chapter, but as a preview, the lambda expression that is
supplied to the onMouseDragged() method is called when the mouse is dragged. As a result, the values of the
x and y properties are altered by the number of pixels that the mouse was dragged, which moves the Stage
as the mouse is dragged.
44
Chapter 2 ■ Creating a User Interface in JavaFX
Using UI Layout Containers
When developing applications that will be deployed in a cross-platform environment or are
internationalized, it is good to use layout containers. One advantage of using layout containers is that when
the node sizes change, their visual relationships with each other are predictable. Another advantage is that
you don’t have to calculate the location of each node that you place in the UI.
The following snippet from Listing 2-1 shows how the VBox layout class, located in the javafx.
scene.layout package, is used to arrange the Text, CheckBox, HBox, and Button nodes in a column. This
snippet also shows that layout containers may be nested, as demonstrated by the HBox with the name
titleBox that arranges the Label and TextField nodes horizontally. Note that several lines of code are
omitted from this snippet to show the layout nesting clearly:
HBox titleBox = new HBox(titleLabel, titleTextField);
VBox contentBox = new VBox(
textStageX, textStageY, textStageW, textStageH, textStageF,
checkBoxResizable, checkBoxFullScreen,
titleBox, toBackButton, toFrontButton, closeButton);
The VBox layout class is similar to the Group class discussed in the Hello Earthrise example in Chapter 1,
in that it contains a collection of nodes within it. Unlike the Group class, the VBox class arranges its contained
nodes vertically, spacing them apart from each other by the number of pixels specified in the spacing
property.
Ascertaining Whether the Stage Is in Focus
To know whether your JavaFX application is the one that currently is in focus (e.g., keys pressed are delivered
to the application), simply consult the focused property of the Stage instance. The following snippet from
Listing 2-1 demonstrates this.
textStageF.textProperty().bind(new SimpleStringProperty("focused: ")
.concat(stageRef.focusedProperty().asString()));
Controlling the Z-Order of the Stage
In the event that you want your JavaFX application to appear on top of other windows or behind other
windows onscreen, you can use the toFront() and toBack() methods, respectively. The following snippet
from Listing 2-1 shows how this is accomplished.
Button toBackButton = new Button("toBack()");
toBackButton.setOnAction(e -> stageRef.toBack());
Button toFrontButton = new Button("toFront()");
toFrontButton.setOnAction(e -> stageRef.toFront());
Once again, note how using lambda expressions enhances the readability of the code. It is clear from
the first line of the snippet that a Button named toBackButton is created with a text "toBack()" being
displayed on the button. The second line defines that when an action is performed on the button (i.e., the
button is clicked), the stage is sent to the back.
45
Chapter 2 ■ Creating a User Interface in JavaFX
Without using a lambda expression, the second line would be replaced by a call to an anonymous inner
class as follows:
toBackButton.setOnAction(new EventHandler() {
@Override public void handle(javafx.event.ActionEvent e) {
stageRef.toBack();
}
})
This approach not only requires more code, it doesn’t allow the Java runtime to optimize calls and it is
much less readable.
Closing the Stage and Detecting When It Is Closed
As shown in the following code snippet from Listing 2-1, you can programmatically close the Stage with its
close() method. This is important when the stageStyle is undecorated or transparent, because the close
button supplied by the windowing system is not present.
Button closeButton = new Button("close()");
closeButton.setOnAction(e -> stageRef.close());
By the way, you can detect when there is an external request to close the Stage by using the
onCloseRequest event handler as shown in the following code snippet from Listing 2-1.
stage.setOnCloseRequest((WindowEvent we) -> {
System.out.println("Stage is closing");
});
To see this in action, run the application without any arguments so that it has the appearance of
Figure 2-2 shown previously, and then click the close button on the decoration of the window.
■■Tip The onCloseRequest event handler is only called when there is an external request to close the
window. This is why the “Stage is closing” message doesn’t appear in this example when you click the button
labeled “close()”.
Making a Scene
Continuing on with our theater metaphor for creating JavaFX applications, we now discuss putting a Scene
on the Stage. The Scene, as you recall, is the place in which the actors and props (nodes) visually interact
with each other and the audience (the users of your program).
Using the Scene Class: The OnTheScene Example
As with the Stage class, we’re going to use a contrived example application to demonstrate and teach the
details of the available capabilities in the Scene class. See Figure 2-6 for a screenshot of the OnTheScene
program.
46
Chapter 2 ■ Creating a User Interface in JavaFX
Figure 2-6. The OnTheScene program when first invoked
Go ahead and run the OnTheScene program, putting it through its paces as instructed in the following
exercise. We follow up with a walkthrough of the code so that you can associate the behavior with the code
behind it.
EXAMINING THE BEHAVIOR OF THE ONTHESCENE PROGRAM
When the OnTheScene program starts, its appearance should be similar to the screenshot in Figure 2-6.
To fully examine its behavior, perform the following steps. Note that the property and method names
on the UI correspond to the property and methods in the Scene, Stage, and Cursor classes, as well as
Cascading Style Sheets (CSS) file names.
1.
Drag the application around, noticing that although the Stage x and y values are
relative to the screen, the Scene’s x and y values are relative to the upper-left
corner of the exterior of the Stage (including decorations). Similarly, the width and
height of the Scene are the dimensions of the interior of the Stage (which doesn’t
include decorations). As noted earlier, it is best to set the Scene width and height
explicitly (or let them be set implicitly by assuming the size of the contained nodes),
rather than setting the width and height of a decorated Stage.
2.
Resize the program’s window and observe that the width and height values change
to reflect the width and height of the Scene. Also notice that the position of much of
the content in the scene changes as you change the height of the window.
3.
Click the lookup( ) hyperlink and notice that the string “Scene height: XXX.X” prints
in the console, where XXX.X is the Scene’s height.
4.
Hover the mouse over the choice box drop-down list and notice that it becomes
slightly larger. Click the choice box and choose a cursor style in the list, noticing
that the cursor changes to that style. Be careful about choosing NONE, as the
cursor might disappear, and you’ll need to use the keyboard (or psychic powers
while moving the mouse) to make it visible.
47
Chapter 2 ■ Creating a User Interface in JavaFX
5.
Drag the slider on the left, noticing that the fill color of the Scene changes and that
the string at the top of the Scene reflects the red-green-blue (RGB) and opacity
values of the current fill color.
6.
Notice the appearance and content of the text on the Scene. Then click
changeOfScene.css, noticing that the color and font and content characteristics for
some of the text on the Scene changes as shown in the screenshot in Figure 2-7.
Figure 2-7. The OnTheScene program with the changeOfScene CSS style sheet applied
7.
Click OnTheScene.css, noticing that the color and font characteristics return to their
previous state.
Now that you've explored this example program that demonstrates features of the Scene, let’s walk
through the code!
Understanding the OnTheScene Program
Take a look at the code for the OnTheScene program in Listing 2-2, before we point out new and relevant
concepts.
Listing 2-2. OnTheSceneMain.java
import
import
import
import
import
import
import
import
import
import
import
import
import
48
javafx.application.Application;
javafx.beans.property.DoubleProperty;
javafx.beans.property.SimpleDoubleProperty;
javafx.beans.property.SimpleStringProperty;
javafx.collections.FXCollections;
javafx.collections.ObservableList;
javafx.geometry.HPos;
javafx.geometry.Insets;
javafx.geometry.Orientation;
javafx.geometry.VPos;
javafx.scene.Cursor;
javafx.scene.Scene;
javafx.scene.control.ChoiceBox;
Chapter 2 ■ Creating a User Interface in JavaFX
import
import
import
import
import
import
import
import
import
import
import
import
javafx.scene.control.Hyperlink;
javafx.scene.control.Label;
javafx.scene.control.RadioButton;
javafx.scene.control.Slider;
javafx.scene.control.ToggleGroup;
javafx.scene.layout.FlowPane;
javafx.scene.layout.HBox;
javafx.scene.paint.Color;
javafx.scene.text.Font;
javafx.scene.text.FontWeight;
javafx.scene.text.Text;
javafx.stage.Stage;
public class OnTheSceneMain extends Application {
DoubleProperty fillVals = new SimpleDoubleProperty(255.0);
Scene sceneRef;
ObservableList cursors = FXCollections.observableArrayList(
Cursor.DEFAULT,
Cursor.CROSSHAIR,
Cursor.WAIT,
Cursor.TEXT,
Cursor.HAND,
Cursor.MOVE,
Cursor.N_RESIZE,
Cursor.NE_RESIZE,
Cursor.E_RESIZE,
Cursor.SE_RESIZE,
Cursor.S_RESIZE,
Cursor.SW_RESIZE,
Cursor.W_RESIZE,
Cursor.NW_RESIZE,
Cursor.NONE
);
public static void main(String[] args) {
Application.launch(args);
}
@Override
public void start(Stage stage) {
Slider sliderRef;
ChoiceBox choiceBoxRef;
Text textSceneX;
Text textSceneY;
Text textSceneW;
Text textSceneH;
Label labelStageX;
Label labelStageY;
49
Chapter 2 ■ Creating a User Interface in JavaFX
Label labelStageW;
Label labelStageH;
final ToggleGroup toggleGrp = new ToggleGroup();
sliderRef = new Slider(0, 255, 255);
sliderRef.setOrientation(Orientation.VERTICAL);
choiceBoxRef = new ChoiceBox(cursors);
HBox hbox = new HBox(sliderRef, choiceBoxRef);
hbox.setSpacing(10);
textSceneX = new Text();
textSceneX.getStyleClass().add("emphasized-text");
textSceneY = new Text();
textSceneY.getStyleClass().add("emphasized-text");
textSceneW = new Text();
textSceneW.getStyleClass().add("emphasized-text");
textSceneH = new Text();
textSceneH.getStyleClass().add("emphasized-text");
textSceneH.setId("sceneHeightText");
Hyperlink hyperlink = new Hyperlink("lookup");
hyperlink.setOnAction((javafx.event.ActionEvent e) -> {
System.out.println("sceneRef:" + sceneRef);
Text textRef = (Text) sceneRef.lookup("#sceneHeightText");
System.out.println(textRef.getText());
});
RadioButton radio1 = new RadioButton("onTheScene.css");
radio1.setSelected(true);
radio1.setToggleGroup(toggleGrp);
RadioButton radio2 = new RadioButton("changeOfScene.css");
radio2.setToggleGroup(toggleGrp);
labelStageX = new Label();
labelStageX.setId("stageX");
labelStageY = new Label();
labelStageY.setId("stageY");
labelStageW = new Label();
labelStageH = new Label();
FlowPane sceneRoot = new FlowPane(Orientation.VERTICAL, 20, 10, hbox,
textSceneX, textSceneY, textSceneW, textSceneH, hyperlink,
radio1, radio2,
labelStageX, labelStageY,
labelStageW,
labelStageH);
sceneRoot.setPadding(new Insets(0, 20, 40, 0));
sceneRoot.setColumnHalignment(HPos.LEFT);
sceneRoot.setLayoutX(20);
sceneRoot.setLayoutY(40);
sceneRef = new Scene(sceneRoot, 600, 250);
sceneRef.getStylesheets().add("onTheScene.css");
stage.setScene(sceneRef);
50
Chapter 2 ■ Creating a User Interface in JavaFX
choiceBoxRef.getSelectionModel().selectFirst();
// Setup various property binding
textSceneX.textProperty().bind(new SimpleStringProperty("Scene x: ")
.concat(sceneRef.xProperty().asString()));
textSceneY.textProperty().bind(new SimpleStringProperty("Scene y: ")
.concat(sceneRef.yProperty().asString()));
textSceneW.textProperty().bind(new SimpleStringProperty("Scene width: ")
.concat(sceneRef.widthProperty().asString()));
textSceneH.textProperty().bind(new SimpleStringProperty("Scene height: ")
.concat(sceneRef.heightProperty().asString()));
labelStageX.textProperty().bind(new SimpleStringProperty("Stage x: ")
.concat(sceneRef.getWindow().xProperty().asString()));
labelStageY.textProperty().bind(new SimpleStringProperty("Stage y: ")
.concat(sceneRef.getWindow().yProperty().asString()));
labelStageW.textProperty().bind(new SimpleStringProperty("Stage width: ")
.concat(sceneRef.getWindow().widthProperty().asString()));
labelStageH.textProperty().bind(new SimpleStringProperty("Stage height: ")
.concat(sceneRef.getWindow().heightProperty().asString()));
sceneRef.cursorProperty().bind(choiceBoxRef.getSelectionModel()
.selectedItemProperty());
fillVals.bind(sliderRef.valueProperty());
// When fillVals changes, use that value as the RGB to fill the scene
fillVals.addListener((ov, oldValue, newValue) -> {
Double fillValue = fillVals.getValue() / 256.0;
sceneRef.setFill(new Color(fillValue, fillValue, fillValue, 1.0));
});
// When the selected radio button changes, set the appropriate style sheet
toggleGrp.selectedToggleProperty().addListener((ov, oldValue, newValue) -> {
String radioButtonText = ((RadioButton) toggleGrp.getSelectedToggle())
.getText();
sceneRef.getStylesheets().clear();
sceneRef.getStylesheets().addAll(radioButtonText);
});
stage.setTitle("On the Scene");
stage.show();
// Define an unmanaged node that will display Text
Text addedTextRef = new Text(0, -30, "");
addedTextRef.setTextOrigin(VPos.TOP);
addedTextRef.setFill(Color.BLUE);
addedTextRef.setFont(Font.font("Sans Serif", FontWeight.BOLD, 16));
addedTextRef.setManaged(false);
// Bind the text of the added Text node to the fill property of the Scene
addedTextRef.textProperty().bind(new SimpleStringProperty("Scene fill: ").
concat(sceneRef.fillProperty()));
51
Chapter 2 ■ Creating a User Interface in JavaFX
// Add to the Text node to the FlowPane
((FlowPane) sceneRef.getRoot()).getChildren().add(addedTextRef);
}
}
Setting the Cursor for the Scene
The cursor can be set for a given node, for the entire scene, or for both. To do the latter, set the cursor
property of the Scene instance to one of the constant values in the Cursor class, as shown in the following
snippet from Listing 2-2.
sceneRef.cursorProperty().bind(choiceBoxRef.getSelectionModel()
.selectedItemProperty());
These cursor values can be seen by looking at the javafx.scene.Cursor class in the JavaFX API docs;
we've created a collection of these constants in Listing 2-2.
Painting the Scene’s Background
The Scene class has a fill property of type javafx.scene.paint.Paint. Looking at the JavaFX API will
reveal that the known subclasses of Paint are Color, ImagePattern, LinearGradient, and RadialGradient.
Therefore, a Scene’s background can be filled with solid colors, patterns, and gradients. If you don’t set the
fill property of the Scene, the default color (white) will be used.
■■Tip One of the Color constants is Color.TRANSPARENT, so you may make the Scene’s background
completely transparent if desired. In fact, the reason that the Scene behind the rounded-cornered rectangle in
the StageCoach screenshot in Figure 2-5 isn’t white is that its fill property is set to Color.TRANSPARENT
(see Listing 2-1).
To set the fill property in the OnTheScene example, instead of using one of the constants in the Color
class (e.g., Color.BLUE), we’re using an RGB formula to create the color. Take a look at the javafx.scene.
paint.Color class in the JavaFX API docs and scroll down past the constants such as ALICEBLUE and
WHITESMOKE to see the constructors and methods. We’re using a constructor of the Color class, setting the fill
property to it, as shown in the following snippet from Listing 2-2.
sceneRef.setFill(new Color(fillValue, fillValue, fillValue, 1.0));
As you move the Slider, to which the fillVals property is bound, each of the arguments to the Color()
constructor is set to a value from 0 to 255, as indicated in the following code snippet from Listing 2-2.
fillVals.bind(sliderRef.valueProperty());
Populating the Scene with Nodes
As covered in Chapter 1, you can populate a Scene with nodes by instantiating them and adding them
to container nodes (e.g., Group and VBox) that can contain other nodes. These capabilities enable you to
construct complex scene graphs containing nodes. In the example here, the root property of the Scene
52
Chapter 2 ■ Creating a User Interface in JavaFX
contains a Flow layout container, which causes its contents to flow either vertically or horizontally,
wrapping as necessary. The Flow container in our example contains an HBox (which contains a Slider and a
ChoiceBox) and several other nodes (instances of Text, Hyperlink, and RadioButton classes).
Finding a Scene Node by ID
Each node in a Scene can be assigned an ID in the id property of the node. For example, in the following
snippet from Listing 2-2, the id property of a Text node is assigned the String "sceneHeightText". When
the action event handler in the Hyperlink control is called, the lookup() method of the Scene instance is
used to obtain a reference to the node with the id of "sceneHeightText". The event handler then prints the
content of the Text node to the console.
■■Note The Hyperlink control is essentially a button that has the appearance of hyperlink text. It has
an action event handler in which you could place code that opens a browser page or any other desired
functionality.
textSceneH = new Text();
textSceneH.getStyleClass().add("emphasized-text");
textSceneH.setId("sceneHeightText");
Hyperlink hyperlink = new Hyperlink("lookup");
hyperlink.setOnAction((javafx.event.ActionEvent e) -> {
System.out.println("sceneRef:" + sceneRef);
Text textRef = (Text) sceneRef.lookup("#sceneHeightText");
System.out.println(textRef.getText());
});
A close examination of the action event handler reveals that the lookup() method returns a Node, but
the actual type of object returned in this snippet is a Text object. Because we need to access a property of the
Text class (text) that isn’t in the Node class, it is necessary to coerce the compiler into trusting that at runtime
the object will be an instance of the Text class.
Accessing the Stage from the Scene
To obtain a reference to the Stage instance from the Scene, we use a property in the Scene class named
window. The accessor method for this property appears in the following snippet from Listing 2-2 to get the x
and y co-ordinates of the Stage on the screen.
labelStageX.textProperty().bind(new SimpleStringProperty("Stage x: ")
.concat(sceneRef.getWindow().xProperty().asString()));
labelStageY.textProperty().bind(new SimpleStringProperty("Stage y: ")
.concat(sceneRef.getWindow().yProperty().asString()));
53
Chapter 2 ■ Creating a User Interface in JavaFX
Inserting a Node into the Scene’s Content Sequence
Sometimes it is useful to add a node dynamically to the children of a UI container class. The code snippet
from Listing 2-2 that follows demonstrates how this may be accomplished by dynamically adding a Text
node to the children of the FlowPane instance:
// Define an unmanaged node that will display Text
Text addedTextRef = new Text(0, -30, "");
addedTextRef.setTextOrigin(VPos.TOP);
addedTextRef.setFill(Color.BLUE);
addedTextRef.setFont(Font.font("Sans Serif", FontWeight.BOLD, 16));
addedTextRef.setManaged(false);
// Bind the text of the added Text node to the fill property of the Scene
addedTextRef.textProperty().bind(new SimpleStringProperty("Scene fill: ").
concat(sceneRef.fillProperty()));
// Add the Text node to the FlowPane
((FlowPane) sceneRef.getRoot()).getChildren().add(addedTextRef);
This particular Text node is the one at the top of the Scene shown in Figures 2-6 and 2-7, in which
the value of the Scene’s fill property is displayed. Note that in this example the managed property of the
addedTextRef instance is set to false, so its position isn’t governed by the FlowPane. By default, nodes are
“managed,” which means that their parent (the container to which this node is added) is responsible for the
layout of the node. By setting the managed property to false, the developer is assumed to be responsible for
laying out the node.
CSS Styling the Nodes in a Scene
A very powerful aspect of JavaFX is the ability to use CSS to style the nodes in a Scene dynamically. You
used this capability in step 6 of the previous exercise when you clicked changeOfScene.css to change the
appearance of the UI from what you saw in Figure 2-6 to what was shown in Figure 2-7. Also, in step 7 of the
exercise, the appearance of the UI changed back to what was shown in Figure 2-6 when you selected the
onTheScene.css radio button. The relevant code snippet from Listing 2-2 is shown here:
sceneRef.getStylesheets().add("onTheScene.css");
...code omitted...
// When the selected radio button changes, set the appropriate stylesheet
toggleGrp.selectedToggleProperty().addListener((ov, oldValue, newValue) -> {
String radioButtonText = ((RadioButton) toggleGrp.getSelectedToggle())
.getText();
sceneRef.getStylesheets().clear();
sceneRef.getStylesheets().addAll("/"+radioButtonText);
});
In this snippet, the stylesheets property of the Scene is initialized to the location of the onTheScene.
css file, which in this case is the root directory. Also shown in the snippet is the assignment of the CSS files to
the Scene as the appropriate buttons are clicked. The text of the RadioButton instances is equal to the names
of the style sheets, hence we can easily set the corresponding style sheet to the scene. Take a look at Listing
2-3 to see the style sheet that corresponds to the screenshot in Figure 2-6. Some of the CSS selectors in this
style sheet represent the nodes whose id property is either "stageX" or "stageY". There is also a selector in
54
Chapter 2 ■ Creating a User Interface in JavaFX
this style sheet that represents nodes whose styleClass property is "emphasized-text". In addition, there
is a selector in this style sheet that maps to the ChoiceBox UI control by substituting the camel-case name of
the control to a lowercase hyphenated name (choice-box). The properties in this style sheet begin with "-fx",
and correspond to the type of node with which they are associated. The values in this style sheet (e.g., black,
italic, and 14pt) are expressed as standard CSS values.
Listing 2-3. onTheScene.css
#stageX, #stageY {
-fx-padding: 1;
-fx-border-color: black;
-fx-border-style: dashed;
-fx-border-width: 2;
-fx-border-radius: 5;
}
.emphasized-text {
-fx-font-size: 14pt;
-fx-font-weight: normal;
-fx-font-style: italic;
}
.choice-box:hover {
-fx-scale-x: 1.1;
-fx-scale-y: 1.1;
}
.radio-button .radio {
-fx-background-color: -fx-shadow-highlight-color, -fx-outer-border,
-fx-inner-border, -fx-body-color;
-fx-background-insets: 0 0 -1 0, 0, 1, 2;
-fx-background-radius: 1.0em;
-fx-padding: 0.333333em;
}
.radio-button:focused .radio {
-fx-background-color: -fx-focus-color, -fx-outer-border,
-fx-inner-border, -fx-body-color;
-fx-background-radius: 1.0em;
-fx-background-insets: -1.4, 0, 1, 2;
}
Listing 2-4 is the style sheet that corresponds to the screenshot in Figure 2-7. For more information on
CSS style sheets, see the “Resources” section at the end of this chapter.
Listing 2-4. changeOfScene.css
#stageX, #stageY {
-fx-padding: 3;
-fx-border-color: blue;
-fx-stroke-dash-array: 12 2 4 2;
-fx-border-width: 4;
55
Chapter 2 ■ Creating a User Interface in JavaFX
-fx-border-radius: 5;
}
.emphasized-text {
-fx-font-size: 14pt;
-fx-font-weight: bold;
-fx-font-style: normal;
}
.radio-button *.radio {
-fx-padding: 10;
-fx-background-color: red, yellow;
-fx-background-insets: 0, 5;
-fx-background-radius: 30, 20;
}
.radio-button:focused *.radio {
-fx-background-color: blue, red, yellow;
-fx-background-insets: -5, 0, 5;
-fx-background-radius: 40, 30, 20;
}
Now that you've had some experience with using the Stage and Scene classes, several of the Node
subclasses, and CSS styling, we show you how to handle events that can occur when your JavaFX program is
running.
Handling Input Events
So far we've shown you a couple of examples of event handling. For example, we used the onAction event
handler to execute code when a button is clicked. We also used the onCloseRequest event handler of the
Stage class to execute code when the Stage has been requested externally to close. In this section, we
explore more of the event handlers available in JavaFX.
Surveying Mouse, Keyboard, Touch, and Gesture Events and
Handlers
Most of the events that occur in JavaFX programs are related to the user manipulating input devices such as
a mouse, a keyboard, or a multitouch screen. To see the available event handlers and their associated event
objects, we take yet another look at the JavaFX API documentation. First, navigate to the javafx.scene.
Node class and look for the properties that begin with the letters “on”. These properties represent the event
handlers common to all nodes in JavaFX. Here is a list of these event handlers in the JavaFX 8 API:
56
•
Key event handlers: onKeyPressed, onKeyReleased, onKeyTyped
•
Mouse event handlers: onMouseClicked, onMouseDragEntered, onMouseDragExited,
onMouseDragged, onMouseDragOver, onMouseDragReleased, onMouseEntered,
onMouseExited, onMouseMoved, onMousePressed, onMouseReleased
•
Drag-and-drop handlers: onDragDetected, onDragDone, onDragDropped,
onDragEntered, onDragExited, onDragOver
Chapter 2 ■ Creating a User Interface in JavaFX
•
Touch handlers: onTouchMoved, onTouchPressed, onTouchReleased,
onTouchStationary
•
Gesture handlers: onRotate, onRotationFinished, onRotationStarted, onScroll,
onScrollStarted, onScrollFinished, onSwipeLeft, onSwipeRight, onSwipeUp,
onSwipeDown, onZoom, onZoomStarted, onZoomFinished
Each of these is a property that defines a method to be called when particular input events occur. In
the case of the key event handlers, as shown in the JavaFX API docs, the method’s parameter is a javafx.
scene.input.KeyEvent instance. The method’s parameter for the mouse event handlers is a javafx.scene.
input.MouseEvent. Touch handlers consume a javafx.scene.input.TouchEvent instance, and when a
gesture event occurs, the method’s parameter for the handle event is an instance of javax.scene.input.
GestureInput.
Understanding the KeyEvent Class
Take a look at the JavaFX API docs for the KeyEvent class, and you’ll see that it contains several methods, a
commonly used one being getCode(). The getCode() method returns a KeyCode instance representing the
key that caused the event when pressed. Looking at the javafx.scene.input.KeyCode class in the JavaFX
API docs reveals that a multitude of constants exist that represent keys on an international set of keyboards.
Another way to find out what key was pressed is to call the getCharacter() method, which returns a string
that represents the Unicode character associated with the key pressed.
The KeyEvent class also enables you to see whether the Alt, Ctrl, Meta, and/or Shift keys were down
at the time of the event by calling the isAltDown(), isControlDown(), isMetaDown(), or isShiftDown()
methods, respectively.
Understanding the MouseEvent Class
Take a look at the MouseEvent class in the JavaFX API docs, and you see that significantly more methods
are available than in KeyEvent. Like KeyEvent, MouseEvent has the isAltDown(), isControlDown(),
isMetaDown(), and isShiftDown() methods, as well as the source field, which is a reference to the object
in which the event originated. In addition, it has several methods that pinpoint various coordinate spaces
where the mouse event occurred, all expressed in pixels:
•
getX() and getY() return the horizontal and vertical position of the mouse event,
relative to the origin of the node in which the mouse event occurred.
•
getSceneX() and getSceneY() return the horizontal and vertical position of the
mouse event, relative to the Scene.
•
getScreenX() and getScreenY() return the horizontal and vertical position of the
mouse event, relative to the screen.
Here are a few other commonly useful methods:
•
isDragDetect() returns true if a drag event is detected.
•
getButton(), isPrimaryButtonDown(), isSecondaryButtonDown(),
isMiddleButtonDown(), and getClickCount() contain information about what
button was clicked, and how many times it was clicked.
A little later in this chapter you get some experience with creating key and mouse event handlers in the
ZenPong example program. To continue preparing you for the ZenPong example, we now give you a look at
how you can animate the nodes that you put in your scene.
57
Chapter 2 ■ Creating a User Interface in JavaFX
Understanding the TouchEvent Class
With more and more devices being equipped with a touch screen, built-in support for touch events makes
JavaFX a state-of-the art platform for creating applications that leverage multitouch capabilities, by which we
mean that the platform is able to track more than one touchpoint in a single set of events.
The TouchEvent class provides the getTouchPoint() method, which returns a specific touch point.
The methods on this TouchPoint are similar to the methods on a MouseEvent, for example, you can retrieve
the relative and absolute positions by calling getX() and getY(), or getSceneX() and getSceneY(), or
getScreenX() and getScreenY().
The TouchEvent class also allows the developer to get information about the other touch points that
belong to the same set. By calling getEventSetId(), you get the unique identifier of the set of TouchEvent
instances, and the list of all touch points in the set can be obtained by calling getTouchPoints(), which
returns a list of TouchPoint instances.
Understanding the GestureEvent Class
Besides handling multitouch events, JavaFX also supports the creation and dispatching of gesture events.
Gestures are increasingly used on smartphones, tablets, touch screens, and other input devices. They
provide an intuitive way of performing an action, for example, by having the user swipe his or her finger.
The GestureEvent class currently has four subclasses, each representing a specific gesture: RotateEvent,
ScrollEvent, SwipeEvent, and ZoomEvent. All of these events have methods comparable to the MouseEvent
for retrieving the position of the action—the getX() and getY(), getSceneX() and getSceneY(), and the
getScreenX() and getScreenY() methods.
The specific subclasses all allow for retrieving a more detailed type of the event. A SwipeEvent, for
example can be a swipe to the right or the left, to the top or the bottom. This information is obtained by
calling the getEventType() method on the GestureEvent.
Animating Nodes in the Scene
One of the strengths of JavaFX is the ease with which you can create graphically rich UIs. Part of that richness
is the ability to animate nodes that live in the Scene. At its core, animating a node involves changing the
value of its properties over a period of time. Examples of animating a node include the following.
•
Gradually increasing the size of a node when the mouse enters its bounds, and
gradually decreasing the size when the mouse exits its bounds. Note that this
requires scaling the node, which is referred to as a transform.
•
Gradually increasing or decreasing the opacity of a node to provide a fade-in or fadeout effect, respectively.
•
Gradually altering values of properties in a node that change its location, causing it to
move from one location to another. This is useful, for example, when creating a game such
as Pong. A related capability is detecting when a node has collided with another node.
Animating a node involves the use of the Timeline class, located in the javafx.animation package.
Depending on the requirements of an animation and personal preference, use one of two general techniques:
58
•
Create an instance of the Timeline class directly and supply key frames that specify
values and actions at specific points in time.
•
Use the javafx.animation.Transition subclasses to define and associate specific
transitions with a node. Examples of transitions include causing a node to move
along a defined path over a period of time, and rotating a node over a period of time.
Each of these transition classes extends the Timeline class.
Chapter 2 ■ Creating a User Interface in JavaFX
We now cover these techniques, showing examples of each, beginning with the first one listed.
Using a Timeline for Animation
Take a look at the javafx.animation package in the JavaFX API docs, and you see three of the classes that
are used when directly creating a timeline: Timeline, KeyFrame, and Interpolator. Peruse the docs for these
classes, and then come back so we can show you some examples of using them.
■■Tip Remember to consult the JavaFX API docs for any new packages, classes, properties, and methods
that you encounter.
The Metronome1 Example
We use a simple metronome example to demonstrate how to create a timeline.
As the screenshot in Figure 2-8 shows, the Metronome1 program has a pendulum as well as four buttons
that start, pause, resume, and stop the animation. The pendulum in this example is a Line node, and we’re
going to animate that node by interpolating its startX property over the period of one second. Go ahead and
take this example for a spin by doing the following exercise.
Figure 2-8. The Metronome1 program
59
Chapter 2 ■ Creating a User Interface in JavaFX
EXAMINING THE BEHAVIOR OF THE METRONOME1 PROGRAM
When the Metronome1 program starts, its appearance should be similar to the screenshot in Figure 2-8.
To fully examine its behavior, perform the following steps.
1.
Observe that of the four buttons on the scene, only the Start button is enabled.
2.
Click Start. Notice that the top of the line moves back and forth, taking one second
to travel each direction. Also, observe that the Start and Resume buttons are
disabled and that the Pause and Stop buttons are enabled.
3.
Click Pause, noticing that the animation pauses. Also, observe that the Start and
Pause buttons are disabled and that the Resume and Stop buttons are enabled.
4.
Click Resume, noticing that the animation resumes from where it was paused.
5.
Click Stop, noticing that the animation stops and that the button states are the
same as they were when the program was first started (see step 1).
6.
Click Start again, noticing that the line jumps back to its starting point before
beginning the animation (rather than simply resuming as it did in step 4).
7.
Click Stop.
Now that you've experienced the behavior of the Metronome1 program, let’s walk through the code
behind it.
Understanding the Metronome1 Program
Take a look at the code for the Metronome1 program in Listing 2-5, before we discuss relevant concepts.
Listing 2-5. Metronome1Main.java
package projavafx.metronome1.ui;
import
import
import
import
import
import
import
import
import
import
import
import
import
import
import
import
60
javafx.animation.Animation;
javafx.animation.Interpolator;
javafx.animation.KeyFrame;
javafx.animation.KeyValue;
javafx.animation.Timeline;
javafx.application.Application;
javafx.beans.property.DoubleProperty;
javafx.beans.property.SimpleDoubleProperty;
javafx.scene.Group;
javafx.scene.Scene;
javafx.scene.control.Button;
javafx.scene.layout.HBox;
javafx.scene.paint.Color;
javafx.scene.shape.Line;
javafx.stage.Stage;
javafx.util.Duration;
Chapter 2 ■ Creating a User Interface in JavaFX
public class Metronome1Main extends Application {
DoubleProperty startXVal = new SimpleDoubleProperty(100.0);
Button startButton;
Button pauseButton;
Button resumeButton;
Button stopButton;
Line line;
Timeline anim;
public static void main(String[] args) {
Application.launch(args);
}
@Override
public void start(Stage stage) {
anim = new Timeline(
new KeyFrame(new Duration(0.0), new KeyValue(startXVal, 100.)),
new KeyFrame(new Duration(1000.0), new KeyValue(startXVal, 300.,
Interpolator.LINEAR))
);
anim.setAutoReverse(true);
anim.setCycleCount(Animation.INDEFINITE);
line = new Line(0, 50, 200, 400);
line.setStrokeWidth(4);
line.setStroke(Color.BLUE);
startButton = new Button("start");
startButton.setOnAction(e -> anim.playFromStart());
pauseButton = new Button("pause");
pauseButton.setOnAction(e -> anim.pause());
resumeButton = new Button("resume");
resumeButton.setOnAction(e -> anim.play());
stopButton = new Button("stop");
stopButton.setOnAction(e -> anim.stop());
HBox commands = new HBox(10,
startButton,
pauseButton,
resumeButton,
stopButton);
commands.setLayoutX(60);
commands.setLayoutY(420);
Group group = new Group(line, commands);
Scene scene = new Scene(group, 400, 500);
line.startXProperty().bind(startXVal);
startButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.STOPPED));
pauseButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.RUNNING));
resumeButton.disableProperty().bind(anim.statusProperty()
61
Chapter 2 ■ Creating a User Interface in JavaFX
.isNotEqualTo(Animation.Status.PAUSED));
stopButton.disableProperty().bind(anim.statusProperty()
.isEqualTo(Animation.Status.STOPPED));
stage.setScene(scene);
stage.setTitle("Metronome 1");
stage.show();
}
}
Understanding the Timeline Class
The main purpose of the Timeline class is to provide the ability to change the values of properties in a
gradual fashion over given periods of time. Take a look at the following snippet from Listing 2-5 to see the
timeline being created, along with some of its commonly used properties.
DoubleProperty startXVal = new SimpleDoubleProperty(100.0);
...code omitted...
Timeline anim = new Timeline(
new KeyFrame(new Duration(0.0), new KeyValue(startXVal, 100.)),
new KeyFrame(new Duration(1000.0), new KeyValue(startXVal, 300.,
Interpolator.LINEAR))
);
anim.setAutoReverse(true);
anim.setCycleCount(Animation.INDEFINITE);
...code omitted...
line = new Line(0, 50, 200, 400);
line.setStrokeWidth(4);
line.setStroke(Color.BLUE);
...code omitted...
line.startXProperty().bind(startXVal);
■■Note In JavaFX 2, it was recommended to use the builder pattern for creating Nodes. As a consequence,
creating a Line would be done as follows:
line = LineBuilder.create()
.startY(50)
.endX(200)
62
Chapter 2 ■ Creating a User Interface in JavaFX
.endY(400)
.strokeWidth(4)
.stroke(Color.BLUE)
.build();
The advantage of this approach is that it is clear what the parameter “50” in the second line means: The line
has a start-coordinate of 50 in the vertical position. The same readability can be achieved by calling setter
methods, for example
line.setStartY(50);
In practice, however, many parameters are passed via the constructor of the Node. In the case of a Line
instance, the second parameter is the startY parameter. This approach leads to fewer lines of code, but the
developer should be careful about the order and the meaning of the parameters in the constructor. Once again,
we strongly recommend having the Javadoc available while writing JavaFX applications.
Inserting Key Frames into the Timeline
Our timeline contains a collection of two KeyFrame instances. Using the KeyValue constructor, one of these
instances assigns 100 to the startXVal property at the beginning of the timeline, and the other assigns 300 to
the startXVal property when the timeline has been running for one second. Because the startX property of
the Line is bound to the value of the startXVal property, the net result is that the top of the line moves 200
pixels horizontally over the course of one second.
In the second KeyFrame of the timeline, the KeyValue constructor is passed a third argument that
specifies that the interpolation from 100 to 300 will occur in a linear fashion over the one-second duration.
Other Interpolation constants include EASE_IN, EASE_OUT, and EASE_BOTH. These cause the interpolation in
a KeyFrame to be slower in the beginning, ending, or both, respectively.
The following are the other Timeline properties, inherited from the Animation class, used in this
example:
•
autoReverse, which we’re initializing to true. This causes the timeline to
automatically reverse when it reaches the last KeyFrame. When reversed, the
interpolation goes from 300 to 100 over the course of one second.
•
cycleCount, which we’re initializing to Animation.INDEFINITE. This causes the
timeline to repeat indefinitely until stopped by the stop() method of the Timeline
class.
Speaking of the methods of the Timeline class, now is a good time to show you how to control the
timeline and monitor its state.
Controlling and Monitoring the Timeline
As you observed when using the Metronome1 program, clicking the buttons causes the animation to start,
pause, resume, and stop. This in turn has an effect on the states of the animation (running, paused, or
stopped). Those states are reflected in the buttons in the form of being enabled or disabled. The following
63
Chapter 2 ■ Creating a User Interface in JavaFX
snippet from Listing 2-5 shows how to start, pause, resume, and stop the timeline, as well as how to tell
whether the timeline is running or paused.
startButton = new Button("start");
startButton.setOnAction(e -> anim.playFromStart());
pauseButton = new Button("pause");
pauseButton.setOnAction(e -> anim.pause());
resumeButton = new Button("resume");
resumeButton.setOnAction(e -> anim.play());
stopButton = new Button("stop");
stopButton.setOnAction(e -> anim.stop());
...code omitted...
startButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.STOPPED));
pauseButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.RUNNING));
resumeButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.PAUSED));
stopButton.disableProperty().bind(anim.statusProperty()
.isEqualTo(Animation.Status.STOPPED));
As shown here in the action event handler of the Start button, the playFromStart() method of the
Timeline instance is called, which begins playing the timeline from the beginning. In addition, the disable
property of that Button is bound to an expression that evaluates whether the status property of the timeline
is not equal to Animation.Status.STOPPED. This causes the button to be disabled when the timeline is not
stopped (in which case it must be either running or paused).
When the user clicks the Pause button, the action event handler calls the timeline’s pause() method,
which pauses the animation. The disable property of that Button is bound to an expression that evaluates
whether the timeline is not running.
The Resume button is only disabled when the timeline is not paused. To resume the timeline from
where it was paused, the action event handler calls the play() method of the timeline.
Finally, the Stop button is disabled when the timeline is stopped. To stop the timeline, the action event
handler calls the stop() method of the timeline.
Now that you know how to animate nodes by creating a Timeline class and creating KeyFrame
instances, it’s time to learn how to use the transition classes to animate nodes.
Using the Transition Classes for Animation
Using a TimeLine allows very flexible animations. There are a number of common animations facilitating the
translation from one state to another that are out-of-the box supported by JavaFX. The javafx.animation
package contains several classes whose purpose is to provide convenient ways to do these commonly used
animation tasks. Both TimeLine and Transition (the abstract root class for all concrete transitions) extend
the Animation class.
Table 2-1 contains a list of transition classes in that package.
64
Chapter 2 ■ Creating a User Interface in JavaFX
Table 2-1. Transition Classes in the javafx.animation Package for Animating Nodes
Transition Class Name
Description
TranslateTransition
Translates (moves) a node from one location to another over a given period of
time. This was employed in the Hello Earthrise example program in Chapter 1.
PathTransition
Moves a node along a specified path.
RotateTransition
Rotates a node over a given period of time.
ScaleTransition
Scales (increases or decreases the size of ) a node over a given period of time.
FadeTransition
Fades (increases or decreases the opacity of ) a node over a given period of time.
FillTransition
Changes the fill of a shape over a given period of time.
StrokeTransition
Changes the stroke color of a shape over a given period of time.
PauseTransition
Executes an action at the end of its duration; designed mainly to be used in a
SequentialTransition as a means to wait for a period of time.
SequentialTransition
Allows you to define a series of transitions that execute sequentially.
ParallelTransition
Allows you to define a series of transitions that execute in parallel.
Let’s take a look at a variation on the metronome theme in which we create a metronome using
TranslateTransition for the animation.
The MetronomeTransition Example
When using the transition classes, we take a different approach toward animation than when using the
Timeline class directly:
•
In the timeline-based Metronome1 program, we bound a property of a node
(specifically, startX) to a property in the model (startXVal), and then used the
timeline to interpolate the value of the property in the model.
•
When using a transition class, however, we assign values to the properties of the
Transition subclass, one of which is a node. The net result is that the node itself is
affected, rather than just a bound attribute of the node being affected.
The distinction between these two approaches becomes clear as we walk through the
MetronomeTransition example. Figure 2-9 shows a screenshot of this program when it is first invoked.
65
Chapter 2 ■ Creating a User Interface in JavaFX
Figure 2-9. The MetronomeTransition program
The first noticeable difference between this example and the previous (Metronome1) example is that
instead of one end of a line moving back and forth, we’re going to make a Circle node move back and forth.
The Behavior of the MetronomeTransition Program
Go ahead and run the program, and perform the same steps that you did in the previous exercise with
Metronome1. Everything should function the same, except for the visual difference pointed out previously.
Understanding the MetronomeTransition Program
Take a look at the code for the MetronomeTransition program in Listing 2-6, before we point out relevant
concepts.
Listing 2-6. MetronomeTransitionMain.fx
package projavafx.metronometransition.ui;
import javafx.animation.Animation;
import javafx.animation.Interpolator;
import javafx.animation.TranslateTransition;
66
Chapter 2 ■ Creating a User Interface in JavaFX
import
import
import
import
import
import
import
import
import
javafx.application.Application;
javafx.scene.Group;
javafx.scene.Scene;
javafx.scene.control.Button;
javafx.scene.layout.HBox;
javafx.scene.paint.Color;
javafx.scene.shape.Circle;
javafx.stage.Stage;
javafx.util.Duration;
public class MetronomeTransitionMain extends Application {
Button
Button
Button
Button
Circle
startButton;
pauseButton;
resumeButton;
stopButton;
circle;
public static void main(String[] args) {
Application.launch(args);
}
@Override
public void start(Stage stage) {
circle = new Circle(100, 50, 4, Color.BLUE);
TranslateTransition anim = new TranslateTransition(new Duration(1000.0), circle);
anim.setFromX(0);
anim.setToX(200);
anim.setAutoReverse(true);
anim.setCycleCount(Animation.INDEFINITE);
anim.setInterpolator(Interpolator.LINEAR);
startButton = new Button("start");
startButton.setOnAction(e -> anim.playFromStart());
pauseButton = new Button("pause");
pauseButton.setOnAction(e -> anim.pause());
resumeButton = new Button("resume");
resumeButton.setOnAction(e -> anim.play());
stopButton = new Button("stop");
stopButton.setOnAction(e -> anim.stop());
HBox commands = new HBox(10, startButton,
pauseButton,
resumeButton,
stopButton);
commands.setLayoutX(60);
commands.setLayoutY(420);
Group group = new Group(circle, commands);
Scene scene = new Scene(group, 400, 500);
startButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.STOPPED));
pauseButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.RUNNING));
67
Chapter 2 ■ Creating a User Interface in JavaFX
resumeButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.PAUSED));
stopButton.disableProperty().bind(anim.statusProperty()
.isEqualTo(Animation.Status.STOPPED));
stage.setScene(scene);
stage.setTitle("Metronome using TranslateTransition");
stage.show();
}
}
Using the TranslateTransition Class
As shown in the following snippet from Listing 2-6, to create a TranslateTransition we’re supplying
values that are reminiscent of the values that we used when creating a timeline in the previous example. For
example, we’re setting autoReverse to true and cycleCount to Animation.INDEFINITE. Also, just as when
creating a KeyFrame for a timeline, we’re supplying a duration and an interpolation type here as well.
In addition, we’re supplying some values to properties that are specific to a TranslateTransition,
namely fromX and toX. These values are interpolated over the requested duration and assigned to the
layoutX property of the node controlled by the transition (in this case, the circle). If we also wanted to cause
vertical movement, assigning values to fromY and toY would cause interpolated values between them to be
assigned to the layoutY property.
An alternative to supplying toX and toY values is to provide values to the byX and byY properties, which
enables you to specify the distance to travel in each direction rather than start and end points. Also, if you
don’t supply a value for fromX, the interpolation will begin with the current value of the node’s layoutX
property. The same holds true for fromY (if not supplied, the interpolation will begin with the value of
layoutY).
circle = new Circle(100, 50, 4, Color.BLUE);
TranslateTransition anim = new TranslateTransition(new Duration(1000.0), circle);
anim.setFromX(0);
anim.setToX(200);
anim.setAutoReverse(true);
anim.setCycleCount(Animation.INDEFINITE);
anim.setInterpolator(Interpolator.LINEAR);
Controlling and Monitoring the Transition
The TranslateTransition class, as do all of the classes in Table 2-1, extends the javafx.animation.
Transition class, which in turn extends the Animation class. Because the Timeline class extends the
Animation class, as you can see by comparing Listings 2-5 and 2-6, all of the code for the buttons in
this example is identical to that in the previous example. Indeed, the functionality required to start,
pause, resume, and stop an animation is defined on the Animation class itself, and inherited by both the
Translation classes as well as the Timeline class.
68
Chapter 2 ■ Creating a User Interface in JavaFX
The MetronomePathTransition Example
As shown in Table 2-1, PathTransition is a transition class that enables you to move a node along a
defined geometric path. Figure 2-10 shows a screenshot of a version of the metronome example, named
MetronomePathTransition, that demonstrates how to use the PathTransition class.
Figure 2-10. The MetronomePathTransition program
The Behavior of the MetronomePathTransition Program
Go ahead and run the program, performing once again the same steps that you did for the Metronome1
exercise. Everything should function the same as it did in the MetronomeTransition example, except that the
node is an ellipse instead of a circle, and the node moves along the path of an arc.
Understanding the MetronomePathTransition Program
Listing 2-7 contains code snippets from the MetronomePathTransition program that highlight the
differences from the preceding (MetronomeTransition) program. Take a look at the code, and then we
review relevant concepts.
69
Chapter 2 ■ Creating a User Interface in JavaFX
Listing 2-7. Portions of MetronomePathTransitionMain.java
package projavafx.metronomepathtransition.ui;
...imports omitted...
public class MetronomePathTransitionMain extends Application {
Button startButton;
Button pauseButton;
Button resumeButton;
Button stopButton;
Ellipse ellipse;
Path path;
public static void main(String[] args) {
Application.launch(args);
}
@Override
public void start(Stage stage) {
ellipse = new Ellipse(100, 50, 4, 8);
ellipse.setFill(Color.BLUE);
path = new Path(
new MoveTo(100, 50),
new ArcTo(350, 350, 0, 300, 50, false, true)
);
PathTransition anim = new PathTransition(new Duration(1000.0), path, ellipse);
anim.setOrientation(OrientationType.ORTHOGONAL_TO_TANGENT);
anim.setInterpolator(Interpolator.LINEAR);
anim.setAutoReverse(true);
anim.setCycleCount(Timeline.INDEFINITE);
startButton = new Button("start");
startButton.setOnAction(e -> anim.playFromStart());
pauseButton = new Button("pause");
pauseButton.setOnAction(e -> anim.pause());
resumeButton = new Button("resume");
resumeButton.setOnAction(e -> anim.play());
stopButton = new Button("stop");
stopButton.setOnAction(e -> anim.stop());
HBox commands = new HBox(10, startButton,
pauseButton,
resumeButton,
stopButton);
commands.setLayoutX(60);
commands.setLayoutY(420);
Group group = new Group(ellipse, commands);
Scene scene = new Scene(group, 400, 500);
startButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.STOPPED));
70
Chapter 2 ■ Creating a User Interface in JavaFX
pauseButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.RUNNING));
resumeButton.disableProperty().bind(anim.statusProperty()
.isNotEqualTo(Animation.Status.PAUSED));
stopButton.disableProperty().bind(anim.statusProperty()
.isEqualTo(Animation.Status.STOPPED));
stage.setScene(scene);
stage.setTitle("Metronome using PathTransition");
stage.show();
}
}
Using the PathTransition Class
As shown in Listing 2-7, defining a PathTransition includes supplying an instance of type Path to the path
property that represents the geometric path that the node is to travel. Here we’re creating a Path instance
that defines an arc beginning at 100 pixels on the x axis and 50 pixels on the y axis, ending at 300 pixels on
the x axis and 50 pixels on the y axis, with 350 pixel horizontal and vertical radii. This is accomplished by
creating a Path that contains the MoveTo and ArcTo path elements. Take a look at the javafx.scene.shape
package in the JavaFX API docs for more information on the PathElement class and its subclasses, which are
used for creating a path.
■■Tip The properties in the ArcTo class are fairly intuitive except for sweepFlag. If sweepFlag is true, the line
joining the center of the arc to the arc itself sweeps through increasing angles; otherwise, it sweeps through
decreasing angles.
Another property of the PathTransition class is orientation, which controls whether the node’s
orientation remains unchanged or stays perpendicular to the path’s tangent as it moves along the path.
Listing 2-7 uses the OrientationType.ORTHOGONAL_TO_TANGENT constant to accomplish the latter, as the
former is the default.
Drawing an Ellipse
As shown in Listing 2-7, drawing an Ellipse is similar to drawing a Circle, the difference being that an
additional radius is required (radiusX and radiusY instead of just radius).
Now that you've learned how to animate nodes by creating a timeline and by creating transitions, we
create a very simple Pong-style game that requires animating a ping-pong ball. In the process, you learn how
to detect when the ball has hit a paddle or wall in the game.
The Zen of Node Collision Detection
When animating a node, you sometimes need to know when the node has collided with another node. To
demonstrate this capability, our colleague Chris Wright developed a simple version of the Pong-style game
that we call ZenPong. Originally, we asked him to build the game with only one paddle, which brought the
famous Zen koan (philosophical riddle) “What is the sound of one hand clapping?” to mind. Chris had
71
Chapter 2 ■ Creating a User Interface in JavaFX
so much fun developing the game that he snuck a second paddle in, but we’re still calling this example
ZenPong. Figure 2-11 shows this very simple form of the game when first invoked.
Figure 2-11. The initial state of the ZenPong game
Try out the game by following the instructions in the upcoming exercise, remembering that you control
both paddles (unless you can get a colleague to share your keyboard and play).
EXAMINING THE BEHAVIOR OF THE ZENPONG GAME
When the program starts, its appearance should be similar to the screenshot in Figure 2-11. To fully
examine its behavior, perform the following steps.
72
1.
Before clicking Start, drag each of the paddles vertically to other positions. One
game cheat is to drag the left paddle up and the right paddle down, which will put
them in good positions to respond to the ball after being served.
2.
Practice using the A key to move the left paddle up, the Z key to move the left
paddle down, the L key to move the right paddle up, and the comma (,) key to move
the right paddle down.
3.
Click Start to begin playing the game. Notice that the Start button disappears and
the ball begins moving at a 45° angle, bouncing off paddles and the top and bottom
walls. The screen should look similar to Figure 2-12.
Chapter 2 ■ Creating a User Interface in JavaFX
Figure 2-12. The ZenPong game in action
4.
If the ball hits the left or right wall, one of your hands has lost the game. Notice that
the game resets, looking again like the screenshot in Figure 2-11.
Now that you’ve experienced the behavior of the ZenPong program, let’s review the code behind it.
Understanding the ZenPong Program
Examine the code for the ZenPong program in Listing 2-8, before we highlight some concepts demonstrated
within.
Listing 2-8. ZenPongMain.java
package projavafx.zenpong.ui;
...imports omitted...
public class ZenPongMain extends Application {
/**
* The center points of the moving ball
*/
73
Chapter 2 ■ Creating a User Interface in JavaFX
DoubleProperty centerX = new SimpleDoubleProperty();
DoubleProperty centerY = new SimpleDoubleProperty();
/**
* The Y coordinate of the left paddle
*/
DoubleProperty leftPaddleY = new SimpleDoubleProperty();
/**
* The Y coordinate of the right paddle
*/
DoubleProperty rightPaddleY = new SimpleDoubleProperty();
/**
* The drag anchor for left and right paddles
*/
double leftPaddleDragAnchorY;
double rightPaddleDragAnchorY;
/**
* The initial translateY property for the left and right paddles
*/
double initLeftPaddleTranslateY;
double initRightPaddleTranslateY;
/**
* The moving ball
*/
Circle ball;
/**
* The Group containing all of the walls, paddles, and ball. This also
* allows us to requestFocus for KeyEvents on the Group
*/
Group pongComponents;
/**
* The left and right paddles
*/
Rectangle leftPaddle;
Rectangle rightPaddle;
/**
* The walls
*/
Rectangle topWall;
Rectangle rightWall;
Rectangle leftWall;
Rectangle bottomWall;
Button startButton;
74
Chapter 2 ■ Creating a User Interface in JavaFX
/**
* Controls whether the startButton is visible
*/
BooleanProperty startVisible = new SimpleBooleanProperty(true);
/**
* The animation of the ball
*/
Timeline pongAnimation;
/**
* Controls whether the ball is moving right
*/
boolean movingRight = true;
/**
* Controls whether the ball is moving down
*/
boolean movingDown = true;
/**
* Sets the initial starting positions of the ball and paddles
*/
void initialize() {
centerX.setValue(250);
centerY.setValue(250);
leftPaddleY.setValue(235);
rightPaddleY.setValue(235);
startVisible.set(true);
pongComponents.requestFocus();
}
/**
* Checks whether or not the ball has collided with either the paddles,
* topWall, or bottomWall. If the ball hits the wall behind the paddles, the
* game is over.
*/
void checkForCollision() {
if (ball.intersects(rightWall.getBoundsInLocal())
|| ball.intersects(leftWall.getBoundsInLocal())) {
pongAnimation.stop();
initialize();
} else if (ball.intersects(bottomWall.getBoundsInLocal())
|| ball.intersects(topWall.getBoundsInLocal())) {
movingDown = !movingDown;
} else if (ball.intersects(leftPaddle.getBoundsInParent()) && !movingRight) {
movingRight = !movingRight;
} else if (ball.intersects(rightPaddle.getBoundsInParent()) && movingRight) {
movingRight = !movingRight;
}
}
75
Chapter 2 ■ Creating a User Interface in JavaFX
/**
* @param args the command line arguments
*/
public static void main(String[] args) {
Application.launch(args);
}
@Override
public void start(Stage stage) {
pongAnimation = new Timeline(
new KeyFrame(new Duration(10.0), t -> {
checkForCollision();
int horzPixels = movingRight ? 1 : -1;
int vertPixels = movingDown ? 1 : -1;
centerX.setValue(centerX.getValue() + horzPixels);
centerY.setValue(centerY.getValue() + vertPixels);
})
);
pongAnimation.setCycleCount(Timeline.INDEFINITE);
ball = new Circle(0, 0, 5, Color.WHITE);
topWall = new Rectangle(0, 0, 500, 1);
leftWall = new Rectangle(0, 0, 1, 500);
rightWall = new Rectangle(500, 0, 1, 500);
bottomWall = new Rectangle(0, 500, 500, 1);
leftPaddle = new Rectangle(20, 0, 10, 30);
leftPaddle.setFill(Color.LIGHTBLUE);
leftPaddle.setCursor(Cursor.HAND);
leftPaddle.setOnMousePressed(me -> {
initLeftPaddleTranslateY = leftPaddle.getTranslateY();
leftPaddleDragAnchorY = me.getSceneY();
});
leftPaddle.setOnMouseDragged(me -> {
double dragY = me.getSceneY() - leftPaddleDragAnchorY;
leftPaddleY.setValue(initLeftPaddleTranslateY + dragY);
});
rightPaddle = new Rectangle(470, 0, 10, 30);
rightPaddle.setFill(Color.LIGHTBLUE);
rightPaddle.setCursor(Cursor.CLOSED_HAND);
rightPaddle.setOnMousePressed(me -> {
initRightPaddleTranslateY = rightPaddle.getTranslateY();
rightPaddleDragAnchorY = me.getSceneY();
});
rightPaddle.setOnMouseDragged(me -> {
double dragY = me.getSceneY() - rightPaddleDragAnchorY;
rightPaddleY.setValue(initRightPaddleTranslateY + dragY);
});
startButton = new Button("Start!");
startButton.setLayoutX(225);
startButton.setLayoutY(470);
startButton.setOnAction(e -> {
startVisible.set(false);
76
Chapter 2 ■ Creating a User Interface in JavaFX
pongAnimation.playFromStart();
pongComponents.requestFocus();
});
pongComponents = new Group(ball,
topWall,
leftWall,
rightWall,
bottomWall,
leftPaddle,
rightPaddle,
startButton);
pongComponents.setFocusTraversable(true);
pongComponents.setOnKeyPressed(k -> {
if (k.getCode() == KeyCode.SPACE
&& pongAnimation.statusProperty()
.equals(Animation.Status.STOPPED)) {
rightPaddleY.setValue(rightPaddleY.getValue() - 6);
} else if (k.getCode() == KeyCode.L
&& !rightPaddle.getBoundsInParent().intersects(topWall.
getBoundsInLocal())) {
rightPaddleY.setValue(rightPaddleY.getValue() - 6);
} else if (k.getCode() == KeyCode.COMMA
&& !rightPaddle.getBoundsInParent().intersects(bottomWall.
getBoundsInLocal())) {
rightPaddleY.setValue(rightPaddleY.getValue() + 6);
} else if (k.getCode() == KeyCode.A
&& !leftPaddle.getBoundsInParent().intersects(topWall.
getBoundsInLocal())) {
leftPaddleY.setValue(leftPaddleY.getValue() - 6);
} else if (k.getCode() == KeyCode.Z
&& !leftPaddle.getBoundsInParent().intersects(bottomWall.
getBoundsInLocal())) {
leftPaddleY.setValue(leftPaddleY.getValue() + 6);
}
});
Scene scene = new Scene(pongComponents, 500, 500);
scene.setFill(Color.GRAY);
ball.centerXProperty().bind(centerX);
ball.centerYProperty().bind(centerY);
leftPaddle.translateYProperty().bind(leftPaddleY);
rightPaddle.translateYProperty().bind(rightPaddleY);
startButton.visibleProperty().bind(startVisible);
stage.setScene(scene);
initialize();
stage.setTitle("ZenPong Example");
stage.show();
}
}
77
Chapter 2 ■ Creating a User Interface in JavaFX
Using the KeyFrame Action Event Handler
We’re using a different technique in the timeline than demonstrated in the Metronome1 program earlier in
the chapter (see Figure 2-8 and Listing 2-5). Instead of interpolating two values over a period of time, we’re
using the action event handler of the KeyFrame instance in our timeline. Take a look at the following snippet
from Listing 2-8 to see this technique in use.
pongAnimation = new Timeline(
new KeyFrame(new Duration(10.0), t -> {
checkForCollision();
int horzPixels = movingRight ? 1 : -1;
int vertPixels = movingDown ? 1 : -1;
centerX.setValue(centerX.getValue() + horzPixels);
centerY.setValue(centerY.getValue() + vertPixels);
})
);
pongAnimation.setCycleCount(Timeline.INDEFINITE);
As shown in the snippet, we use only one KeyFrame, and it has a very short time (10 milliseconds).
When a KeyFrame has an action event handler, the code in that handler—which in this case is once again a
lambda expression—is executed when the time for that KeyFrame is reached. Because the cycleCount of this
timeline is indefinite, the action event handler will be executed every 10 milliseconds. The code in this event
handler does two things:
•
Calls a method named checkForCollision(), which is defined in this program, the
purpose of which is to see whether the ball has collided with either paddle or any of
the walls
•
Updates the properties in the model to which the position of the ball is bound, taking
into account the direction in which the ball is already moving
Using the Node intersects( ) Method to Detect Collisions
Take a look inside the checkForCollision() method in the following snippet from Listing 2-8 to see how we
check for collisions by detecting when two nodes intersect (share any of the same pixels).
void checkForCollision() {
if (ball.intersects(rightWall.getBoundsInLocal()) ||
ball.intersects(leftWall.getBoundsInLocal())) {
pongAnimation.stop();
initialize();
}
else if (ball.intersects(bottomWall.getBoundsInLocal()) ||
ball.intersects(topWall.getBoundsInLocal())) {
movingDown = !movingDown;
}
else if (ball.intersects(leftPaddle.getBoundsInParent()) && !movingRight) {
movingRight = !movingRight;
}
else if (ball.intersects(rightPaddle.getBoundsInParent()) && movingRight) {
movingRight = !movingRight;
}
}
78
Chapter 2 ■ Creating a User Interface in JavaFX
The intersects() method of the Node class shown here takes an argument of type Bounds, located in
the javafx.geometry package. It represents the rectangular bounds of a node, for example, the leftPaddle
node shown in the preceding code snippet. Notice that to get the position of the left paddle in the Group that
contains it, we’re using the boundsInParent property that the leftPaddle (a Rectangle) inherited from the
Node class.
The net results of the intersect method invocations in the preceding snippet are as follows.
•
If the ball intersects with the bounds of the rightWall or leftWall, the
pongAnimation Timeline is stopped and the game is initialized for the next play.
Note that the rightWall and left Wall nodes are one-pixel-wide rectangles on the
left and right sides of the Scene. Take a peek at Listing 2-8 to see where these are
defined.
•
If the ball intersects with the bounds of the bottomWall or topWall, the vertical
direction of the ball will be changed by negating the program’s Boolean movingDown
variable.
•
If the ball intersects with the bounds of the leftPaddle or rightPaddle, the
horizontal direction of the ball will be changed by negating the program’s Boolean
movingRight variable.
■■Tip
For more information on boundsInParent and its related properties, layoutBounds and
boundsInLocal, see the “Bounding Rectangles” discussion at the beginning of the javafx.scene.Node class in
the JavaFX API docs. For example, it is a common practice to find out the width or height of a node by using the
expression myNode.getLayoutBounds().getWidth() or myNode.getLayoutBounds().getHeight().
Dragging a Node
As you experienced previously, the paddles of the ZenPong application may be dragged with the mouse.
The following snippet from Listing 2-8 shows how this capability is implemented in ZenPong for dragging
the right paddle.
DoubleProperty rightPaddleY = new SimpleDoubleProperty();
...code omitted...
double rightPaddleDragStartY;
double rightPaddleDragAnchorY;
...code omitted...
void initialize() {
...code omitted...
rightPaddleY.setValue(235);
}
...code omitted...
rightPaddle = new Rectangle(470, 0, 10, 30);
rightPaddle.setFill(Color.LIGHTBLUE);
rightPaddle.setCursor(Cursor.CLOSED_HAND);
rightPaddle.setOnMousePressed(me -> {
initRightPaddleTranslateY = rightPaddle.getTranslateY();
rightPaddleDragAnchorY = me.getSceneY();
});
79
Chapter 2 ■ Creating a User Interface in JavaFX
rightPaddle.setOnMouseDragged(me -> {
double dragY = me.getSceneY() - rightPaddleDragAnchorY;
rightPaddleY.setValue(initRightPaddleTranslateY + dragY);
});
...code omitted...
rightPaddle.translateYProperty().bind(rightPaddleY);
Note that in this ZenPong example, we’re dragging the paddles only vertically, not horizontally
Therefore, the code snippet only deals with dragging on the y axis. After creating the paddle at the initial
location, we register event handlers for MousePressed and MouseDragged events. The latter manipulates the
rightPaddleY property, which is used for translating the paddle along the y axis. Properties and bindings
will be explained in detail in Chapter 3.
Giving Keyboard Input Focus to a Node
For a node to receive key events, it has to have keyboard focus. This is accomplished in the ZenPong example
by doing these two things, as shown in the snippet that follows from Listing 2-8:
•
Assigning true to the focusTraversable property of the Group node. This allows the
node to accept keyboard focus.
•
Calling the requestFocus() method of the Group node (referred to by the
pongComponents variable). This requests that the node obtain focus.
■■Tip You cannot directly set the value of the focused property of a Stage. Consulting the API docs also
reveals that you cannot set the value of the focused property of a Node (e.g., the Group that we’re discussing
now). However, as discussed in the second point just mentioned, you can call requestFocus() on the node,
which if granted (and focusTraversable is true) sets the focused property to true. By the way, Stage doesn’t
have a requestFocus() method, but it does have a toFront() method, which should give it keyboard focus.
...code omitted...
pongComponents.setFocusTraversable(true);
pongComponents.setOnKeyPressed(k -> {
if (k.getCode() == KeyCode.SPACE
&& pongAnimation.statusProperty()
.equals(Animation.Status.STOPPED)) {
rightPaddleY.setValue(rightPaddleY.getValue() - 6);
} else if (k.getCode() == KeyCode.L
&& !rightPaddle.getBoundsInParent().intersects(topWall.getBoundsInLocal())) {
rightPaddleY.setValue(rightPaddleY.getValue() - 6);
} else if (k.getCode() == KeyCode.COMMA
&& !rightPaddle.getBoundsInParent().intersects(bottomWall.getBoundsInLocal())) {
rightPaddleY.setValue(rightPaddleY.getValue() + 6);
} else if (k.getCode() == KeyCode.A
&& !leftPaddle.getBoundsInParent().intersects(topWall.getBoundsInLocal())) {
leftPaddleY.setValue(leftPaddleY.getValue() - 6);
} else if (k.getCode() == KeyCode.Z
80
Chapter 2 ■ Creating a User Interface in JavaFX
&& !leftPaddle.getBoundsInParent().intersects(bottomWall.getBoundsInLocal())) {
leftPaddleY.setValue(leftPaddleY.getValue() + 6);
}
});
Now that the node has focus, when the user interacts with the keyboard, the appropriate event handlers
will be invoked. In this example, we’re interested in whenever certain keys are pressed, as discussed next.
Using the onKeyPressed Event Handler
When the user presses a key, the lambda expression supplied to the onKeyPressed method is invoked,
passing a KeyEvent instance that contains information about the event. The method body of this expression,
shown in the preceding snippet from Listing 2-8, compares the getCode() method of the KeyEvent instance
to the KeyCode constants that represent the arrow keys to ascertain which key was pressed.
Summary
Congratulations! You have learned a lot in this chapter about creating UIs in JavaFX, including the following.
•
Creating a UI in JavaFX, which we loosely based on the metaphor of creating a
theater play, and typically consists of creating a stage, a scene, nodes, a model, and
event handlers, and animating some of the nodes
•
The details about using most of the properties and methods of the Stage class,
including how to create a Stage that is transparent with no window decorations
•
How to use the HBox and VBox layout containers to organize nodes horizontally and
vertically, respectively
•
The details about using many of the properties and methods of the Scene class
•
How to create and apply CSS styles to nodes in your program by associating one or
more style sheets with the Scene
•
How to handle keyboard and mouse input events
•
How to animate nodes in the scene, both with the Timeline class and the transition
classes
•
How to detect when nodes in the scene have collided
In Chapter 3, we will discuss the alternative approach for creating UIs, this time with Scene Builder.
Then, in Chapter 4, we take a deeper dive into the areas of properties and binding.
Resources
For some additional information on creating JavaFX UIs, you can consult the following resources.
•
JavaFX 9 SDK documentation online: http://download.java.net/jdk9/jfxdocs/
•
JavaFX 9 CSS Reference Guide: http://docs.oracle.com/javase/9/docs/api/
javafx/scene/doc-files/cssref.html
•
The w3schools.com CSS Tutorial: www.w3schools.com/css
81
CHAPTER 3
Properties and Bindings
Heaven acts with vitality and persistence.
In correspondence with this
The superior person keeps himself vital without ceasing.
—I Ching
In Chapters 1 and 2, we introduced you to the JavaFX 9 platform that is part of Oracle JDK 9. You set up
your development environment with your favorite IDE: Eclipse, NetBeans, or IntelliJ IDEA. You wrote and
ran your first JavaFX GUI programs. You learned the fundamental building blocks of JavaFX: the Stage and
Scene classes, and the Nodes that go into the Scene. You have no doubt noticed the use of user-defined model
classes to represent the application state and have that state communicated to the UI through properties and
bindings.
In this chapter, we give you a guided tour of the JavaFX properties and bindings framework. After
recalling a little bit of history and presenting a motivating example that shows various ways that a
JavaFX Property can be used, we cover key concepts of the framework: Observable, ObservableValue,
WritableValue, ReadOnlyProperty, Property, and Binding. We show you the capabilities offered by these
fundamental interfaces of the framework. We then show you how Property objects are bound together, how
Binding objects are built out of properties and other bindings—using the factory methods in the Bindings
utility class, the fluent interface API, or going low level by directly extending abstract classes that implement
the Binding interface—and how they are used to easily propagate changes in one part of a program to other
parts of the program without too much coding. We then introduce the JavaFX Beans naming convention, an
extension of the original JavaBeans naming convention that makes organizing your data into encapsulated
components an orderly affair. We finish this chapter by showing how to adapt old-style JavaBeans properties
into JavaFX properties.
Because the JavaFX properties and bindings framework is a nonvisual part of the JavaFX platform, the
example programs in this chapter are also nonvisual in nature. We deal with Boolean, Integer, Long, Float,
Double, String, and Object type properties and bindings as these are the types in which the JavaFX binding
framework specializes. Your GUI building fun resumes in the next and further chapters.
Forerunners of JavaFX Binding
The need for exposing attributes of Java components directly to client code, allowing them to observe and to
manipulate such attributes, and to take action when their values change, was recognized early in Java’s life.
The JavaBeans framework in Java 1.1 provided support for properties through the now familiar getter and
setter convention. It also supported the propagations of property changes through its PropertyChangeEvent
and PropertyChangeListener mechanism. Although the JavaBeans framework is used in many Swing
© Johan Vos, Stephen Chin, Weiqi Gao, James Weaver, and Dean Iverson 2018
J. Vos et al., Pro JavaFX 9, https://doi.org/10.1007/978-1-4842-3042-8_3
83
Chapter 3 ■ Properties and Bindings
applications, its use is quite cumbersome and requires quite a bit of boilerplate code. Several higher-level
data binding frameworks were created over the years with various levels of success. The heritage of the
JavaBeans in the JavaFX properties and bindings framework lies mainly in the JavaFX Beans getter, setter,
and property getter naming convention when defining JavaFX components. We talk about the JavaFX Beans
getter, setter, and property getter naming convention later in this chapter, after we have covered the key
concepts and interfaces of the JavaFX properties and bindings framework.
Another strand of heritage of the JavaFX properties and bindings framework comes from the
JavaFX Script language that was part of the JavaFX 1.x platform. Although the JavaFX Script language
was deprecated in the JavaFX platform in favor of a Java-based API, one of the goals of the transition
was to preserve most of the powers of the JavaFX Script’s bind keyword, the expressive power of which
has delighted many JavaFX enthusiasts. As an example, JavaFX Script supports the binding to complex
expressions:
var
var
var
def
a
b
m
c
=
=
=
=
1;
10;
4;
bind for (x in [a..b] where x < m) { x * x };
This code will automatically recalculate the value of c whenever the values of a, b, or m are changed.
Although the JavaFX properties and bindings framework does not support all of the binding constructs
of JavaFX Script, it supports the binding of many useful expressions. We talk more about constructing
compound binding expressions after we cover the key concepts and interfaces of the framework.
A Motivating Example
Let’s start with an example in Listing 3-1 that shows off the capabilities of the Property interface through the
use of a couple of instances of the SimpleIntegerProperty class.
Listing 3-1. MotivatingExample.java
import
import
import
import
import
javafx.beans.InvalidationListener;
javafx.beans.property.IntegerProperty;
javafx.beans.property.SimpleIntegerProperty;
javafx.beans.value.ChangeListener;
javafx.beans.value.ObservableValue;
public class MotivatingExample {
private static IntegerProperty intProperty;
public static void main(String[] args) {
createProperty();
addAndRemoveInvalidationListener();
addAndRemoveChangeListener();
bindAndUnbindOnePropertyToAnother();
}
private static void createProperty() {
System.out.println();
intProperty = new SimpleIntegerProperty(1024);
System.out.println("intProperty = " + intProperty);
System.out.println("intProperty.get() = " + intProperty.get());
84
Chapter 3 ■ Properties and Bindings
System.out.println("intProperty.getValue() = " + intProperty.getValue().intValue());
}
private static void addAndRemoveInvalidationListener() {
System.out.println();
final InvalidationListener invalidationListener = observable ->
System.out.println("The observable has been invalidated: " + observable + ".");
intProperty.addListener(invalidationListener);
System.out.println("Added invalidation listener.");
System.out.println("Calling intProperty.set(2048).");
intProperty.set(2048);
System.out.println("Calling intProperty.setValue(3072).");
intProperty.setValue(Integer.valueOf(3072));
intProperty.removeListener(invalidationListener);
System.out.println("Removed invalidation listener.");
System.out.println("Calling intProperty.set(4096).");
intProperty.set(4096);
}
private static void addAndRemoveChangeListener() {
System.out.println();
final ChangeListener changeListener = (ObservableValue observableValue, Object
oldValue, Object newValue) ->
System.out.println("The observableValue has changed: oldValue = " + oldValue + ",
newValue = " + newValue);
intProperty.addListener(changeListener);
System.out.println("Added change listener.");
System.out.println("Calling intProperty.set(5120).");
intProperty.set(5120);
intProperty.removeListener(changeListener);
System.out.println("Removed change listener.");
System.out.println("Calling intProperty.set(6144).");
intProperty.set(6144);
}
private static void bindAndUnbindOnePropertyToAnother() {
System.out.println();
IntegerProperty otherProperty = new SimpleIntegerProperty(0);
System.out.println("otherProperty.get() = " + otherProperty.get());
System.out.println("Binding otherProperty to intProperty.");
otherProperty.bind(intProperty);
System.out.println("otherProperty.get() = " + otherProperty.get());
85
Chapter 3 ■ Properties and Bindings
System.out.println("Calling intProperty.set(7168).");
intProperty.set(7168);
System.out.println("otherProperty.get() = " + otherProperty.get());
System.out.println("Unbinding otherProperty from intProperty.");
otherProperty.unbind();
System.out.println("otherProperty.get() = " + otherProperty.get());
System.out.println("Calling intProperty.set(8192).");
intProperty.set(8192);
System.out.println("otherProperty.get() = " + otherProperty.get());
}
}
In this example we created a SimpleIntegerProperty object called intProperty with an initial value
of 1024. We then updated its value through a series of different integers while we added and then removed
an InvalidationListener, added and then removed a ChangeListener, and finally, created another
SimpleIntegerProperty named otherProperty, bound it to, and then unbound it from the intProperty.
We have taken advantage of the Java 8 lambda syntax in defining our listeners. The sample program used a
generous amount of println calls to show what is happening inside the program.
When we run the program in Listing 3-1, the following output is printed to the console:
intProperty = IntegerProperty [value: 1024]
intProperty.get() = 1024
intProperty.getValue() = 1024
Added invalidation listener.
Calling intProperty.set(2048).
The observable has been invalidated: IntegerProperty [value: 2048].
Calling intProperty.setValue(3072).
The observable has been invalidated: IntegerProperty [value: 3072].
Removed invalidation listener.
Calling intProperty.set(4096).
Added change listener.
Calling intProperty.set(5120).
The observableValue has changed: oldValue = 4096, newValue = 5120
Removed change listener.
Calling intProperty.set(6144).
otherProperty.get() = 0
Binding otherProperty to intProperty.
otherProperty.get() = 6144
Calling intProperty.set(7168).
otherProperty.get() = 7168
Unbinding otherProperty from intProperty.
otherProperty.get() = 7168
Calling intProperty.set(8192).
otherProperty.get() = 7168
86
Chapter 3 ■ Properties and Bindings
By correlating the output lines with the program source code (or by stepping through the code in the
debugger of your favorite IDE), we can draw the following conclusions.
•
A SimpleIntegerProperty object such as intProperty and otherProperty holds
an int value. The value can be manipulated with the get(), set(), getValue(), and
setValue() methods. The get() and set() methods perform their operation with
the primitive int type. The getValue() and setValue() methods use the Integer
wrapper type.
•
You can add and remove InvalidationListener objects to and from intProperty.
•
You can add and remove ChangeListener objects to and from intProperty.
•
Another Property object such as otherProperty can bind itself to intProperty.
When that happens, otherProperty receives the value of intProperty.
•
When a new value is set on intProperty, whatever object that is attached to it is
notified. The notification is not sent if the object is removed.
•
When notified, InvalidationListener objects are only informed of which object is
sending out the notification and that object is only known as an Observable.
•
When notified, ChangeListener objects are informed on two more pieces of
information—the oldValue and the newValue—in addition to the object sending the
notification. The sending object is known as an ObservableValue.
•
In the case of a binding property such as otherProperty, we cannot tell from the
output when or how it is notified of the change of value in intProperty. However,
we can infer that it must have known of the change because when we asked
otherProperty for its value we got back the latest value of intProperty.
■■Note Even though this motivating example uses an Integer property, similar examples can be made to
use properties based on the Boolean, Long, Float, Double, String, and Object types. In the JavaFX properties
and bindings framework, when interfaces are extended or implemented for concrete types, they are always
done for the Boolean, Integer, Long, Float, Double, String, and Object types.
This example brings to our attention some of the key interfaces and concepts of the JavaFX properties
and bindings framework: including the Observable and the associated InvalidationListener interfaces,
the ObservableValue and the associated ChangeListener interfaces, the get(), set(), getValue(), and
setValue() methods that allow us to manipulate the values of a SimpleIntegerProperty object directly, and
the bind() method that allows us to relinquish direct manipulation of the value of a SimpleIntegerProperty
object by subordinating it to another SimpleIntegerProperty object.
In the next section, we show you these and some other key interfaces and concepts of the JavaFX
properties and bindings framework in more detail.
Understanding Key Interfaces and Concepts
Figure 3-1 is a UML diagram showing the key interfaces of the JavaFX properties and bindings framework. It
includes some interfaces that you saw in the last section, and some that you haven’t yet seen.
87
Chapter 3 ■ Properties and Bindings
Figure 3-1. Key interfaces of the JavaFX properties and bindings framework
■■Note We did not show you the fully qualified names of the interfaces in the UML diagram. These interfaces
are spread out in four packages: javafx.beans, javafx.beans.binding, javafx.beans.property, and
javafx.beans.value. You can easily figure out which interface belongs to which package by examining the
JavaFX API documentation or by the “find class” feature of your favorite IDE.
Understanding the Observable Interface
At the root of the hierarchy is the Observable interface. You can register InvalidationListener objects to
an Observable object to receive invalidation events. You have already seen invalidation events fired from
one kind of Observable object, the SimpleIntegerProperty object intProperty in the motivating example
in the last section. It is fired when the set() or setValue() methods are called to change the underlying
value from one int to a different int.
■■Note An invalidation event is fired only once by any of the implementations of the Property interface in
the JavaFX properties and bindings framework if you call the setter with the same value several times in a row.
88
Chapter 3 ■ Properties and Bindings
Another place where invalidation events are fired is from Binding objects. You haven’t seen an example
of a Binding object yet, but there are plenty of Binding objects in the second half of this chapter. For now we
just note that a Binding object may become invalid, for example, when its invalidate() method is called, or
as we show later in this chapter, when one of its dependencies fires an invalidation event.
■■Note An invalidation event is fired only once by any of the implementations of the Binding interface in the
JavaFX properties and bindings framework if it becomes invalid several times in a row.
Understanding the ObservableValue Interface
Next up in the hierarchy is the ObservableValue interface. It’s simply an Observable that has a
value. Its getValue() method returns its value. The getValue() method that we called on the
SimpleIntegerProperty objects in the motivating example can be considered to have come from this
interface. You can register ChangeListener objects to an ObservableValue object to receive change events.
You saw change events being fired in the motivating example in the last section. When the change event
fires, the ChangeListener receives two more pieces of information: the old value and the new value of the
ObservableValue object.
■■Note A change event is fired only once by any of the implementations of the ObservableValue interface in
the JavaFX properties and bindings framework if you call the setter with the same value several times in a row.
The distinction between an invalidation event and a change event is made so that the JavaFX properties
and bindings framework may support lazy evaluations. We show an example of this by looking at three lines
of code from the motivating example:
otherProperty.bind(intProperty);
intProperty.set(7168);
System.out.println("otherProperty.get() = " + otherProperty.get());
When intProperty.set(7168) is called, it fires an invalidation event to otherProperty. On receiving
this invalidation event, otherProperty simply makes a note of the fact that its value is no longer valid. It does
not immediately perform a recalculation of its value by querying intProperty for its value. The recalculation
is performed later when otherProperty.get() is called. Imagine if instead of calling intProperty.set()
only once as in the preceding code we call intProperty.set() multiple times; otherProperty still
recalculates its value only once.
■■Note The ObservableValue interface is not the only direct subinterface of Observable. There are four
other direct subinterfaces of Observable that live in the javafx.collections package: ObservableList,
ObservableMap, ObservableSet, and ObservableArray with corresponding ListChangeListener,
MapChangeListener, SetChangeListener, and ArrayChangeListener as callback mechanisms. These JavaFX
observable collections are covered in Chapter 7.
89
Chapter 3 ■ Properties and Bindings
Understanding the WritableValue Interface
This might be the simplest subsection in the entire chapter, for the WritableValue interface is truly as simple
as it looks. Its purpose is to inject the getValue() and setValue() methods into implementations of this
interface. All implementation classes of WritableValue in the JavaFX properties and bindings framework
also implement ObservableValue; therefore, you can make an argument that the value of WritableValue is
only to provide the setValue() method.
You have seen the setValue() method at work in the motivating example.
Understanding the ReadOnlyProperty Interface
The ReadOnlyProperty interface injects two methods into its implementations. The getBean() method
should return the Object that contains the ReadOnlyRroperty or null if it is not contained in an Object.
The getName() method should return the name of the ReadOnlyProperty or the empty string if the
ReadOnlyProperty does not have a name.
The containing object and the name provide contextual information about a ReadOnlyProperty.
The contextual information of a property does not play any direct role in the propagation of invalidation
events or the recalculation of values. However, if provided, it will be taken into account in some peripheral
calculations.
In our motivating example, the intProperty is constructed without any contextual information. Had we
used the full constructor to supply it a name,
intProperty = new SimpleIntegerProperty(null, "intProperty", 1024);
the output would have contained the property name:
intProperty = IntegerProperty [name: intProperty, value: 1024]
Understanding the Property Interface
Now we come to the bottom of our key interfaces hierarchy. The Property interface has as its superinterfaces
all four interfaces we have examined thus far: Observable, ObservableValue, ReadOnlyProperty, and
WritableValue. Therefore, it inherits all the methods from these interfaces. It also provides five methods of
its own:
void bind(ObservableValue observableValue);
void unbind();
boolean isBound();
void bindBidirectional(Property tProperty);
void unbindBidirectional(Property tProperty);
You have seen two of the methods at work in the motivating example in the last section: bind() and
unbind().
Calling bind() creates a unidirectional binding or a dependency between the Property object and the
ObservableValue argument. Once they enter this relationship, calling the set() or setValue() methods on
the Property object will cause a RuntimeException to be thrown. Calling the get() or getValue() methods
on the Property object will return the value of the ObservableValue object. And, of course, changing the
value of the ObservableValue object will invalidate the Property object. Calling unbind() releases any
existing unidirectional binding the Property object may have. If a unidirectional binding is in effect, the
isBound() method returns true; otherwise, it returns false.
90
Chapter 3 ■ Properties and Bindings
Calling bindBidirectional() creates a bidirectional binding between the Property caller and the
Property argument. Notice that unlike the bind() method, which takes an ObservableValue argument,
the bindBidirectional() method takes a Property argument. Only two Property objects can be bound
together bidirectionally. Once they enter this relationship, calling the set() or setValue() methods on
either Property object will cause both objects’ values to be updated. Calling unbindBidirectional()
releases any existing bidirectional binding the caller and the argument may have. The program in Listing 3-2
shows a simple bidirectional binding at work.
Listing 3-2. BidirectionalBindingExample.java
import javafx.beans.property.SimpleStringProperty;
import javafx.beans.property.StringProperty;
public class BidirectionalBindingExample {
public static void main(String[] args) {
System.out.println("Constructing two StringProperty objects.");
StringProperty prop1 = new SimpleStringProperty("");
StringProperty prop2 = new SimpleStringProperty("");
System.out.println("Calling bindBidirectional.");
prop2.bindBidirectional(prop1);
System.out.println("prop1.isBound() = " + prop1.isBound());
System.out.println("prop2.isBound() = " + prop2.isBound());
System.out.println("Calling prop1.set(\"prop1 says: Hi!\")");
prop1.set("prop1 says: Hi!");
System.out.println("prop2.get() returned:");
System.out.println(prop2.get());
System.out.println("Calling prop2.set(prop2.get() + \"\\nprop2 says: Bye!\")");
prop2.set(prop2.get() + "\nprop2 says: Bye!");
System.out.println("prop1.get() returned:");
System.out.println(prop1.get());
}
}
In this example we created two SimpleStringProperty objects called prop1 and prop2, created a
bidirectional binding between them, and then called set() and get() on both properties.
When we run the program in Listing 3-2, the following output is printed to the console:
Constructing two StringProperty objects.
Calling bindBidirectional.
prop1.isBound() = false
prop2.isBound() = false
Calling prop1.set("prop1 says: Hi!")
prop2.get() returned:
prop1 says: Hi!
Calling prop2.set(prop2.get() + "\nprop2 says: Bye!")
prop1.get() returned:
prop1 says: Hi!
prop2 says: Bye!
91
Chapter 3 ■ Properties and Bindings
■■Caution Each Property object may have at most one active unidirectional binding at a time. It may have
as many bidirectional bindings as you want. The isBound() method pertains only to unidirectional bindings.
Calling bind() a second time with a different ObservableValue argument while a unidirectional binding is
already in effect will unbind the existing one and replace it with the new one.
Understanding the Binding Interface
The Binding interface defines four methods that reveal the intentions of the interface. A Binding object is an
ObservableValue whose validity can be queried with the isValid() method and set with the invalidate()
method. It has a list of dependencies that can be obtained with the getDependencies() method. And finally
a dispose() method signals that the binding will not be used anymore and resources used by it can be
cleaned up.
From this brief description of the Binding interface, we can infer that it represents a unidirectional
binding with multiple dependencies. Each dependency, we imagine, could be an ObservableValue to which
the Binding is registered to receive invalidation events. When the get() or getValue() method is called, if
the binding is invalidated, its value is recalculated.
The JavaFX properties and bindings framework does not provide any concrete classes that implement
the Binding interface. However, it provides multiple ways to create your own Binding objects easily: You
can extend the abstract base classes in the framework; you can use a set of static methods in the utility class
Bindings to create new bindings out of existing regular Java values (i.e., unobservable values), properties,
and bindings; you can also use a set of methods that are provided in the various properties and bindings
classes and form a fluent interface API to create new bindings. We go through the utility methods and the
fluent interface API in the “Creating Bindings” section later in this chapter. For now, we show you the first
example of a binding by extending the DoubleBinding abstract class. The program in Listing 3-3 uses a
binding to calculate the area of a rectangle.
Listing 3-3. RectangleAreaExample.java
import javafx.beans.binding.DoubleBinding;
import javafx.beans.property.DoubleProperty;
import javafx.beans.property.SimpleDoubleProperty;
public class RectangleAreaExample {
public static void main(String[] args) {
System.out.println("Constructing x with initial value of 2.0.");
final DoubleProperty x = new SimpleDoubleProperty(null, "x", 2.0);
System.out.println("Constructing y with initial value of 3.0.");
final DoubleProperty y = new SimpleDoubleProperty(null, "y", 3.0);
System.out.println("Creating binding area with dependencies x and y.");
DoubleBinding area = new DoubleBinding() {
private double value;
{
super.bind(x, y);
}
@Override
protected double computeValue() {
System.out.println("computeValue() is called.");
92
Chapter 3 ■ Properties and Bindings
return x.get() * y.get();
}
};
System.out.println("area.get() = " + area.get());
System.out.println("area.get() = " + area.get());
System.out.println("Setting x to 5");
x.set(5);
System.out.println("Setting y to 7");
y.set(7);
System.out.println("area.get() = " + area.get());
}
}
In the anonymous inner class, we called the protected bind() method in the superclass DoubleBinding,
informing the superclass that we would like to listen to invalidation events from the DoubleProperty
objects x and y. We finally implemented the protected abstract computeValue() method in the superclass
DoubleBinding to do the actual calculation when a recalculation is needed.
When we run the program in Listing 3-3, the following output is printed to the console:
Constructing x with initial value of 2.0.
Constructing y with initial value of 3.0.
Creating binding area with dependencies x and y.
computeValue() is called.
area.get() = 6.0
area.get() = 6.0
Setting x to 5
Setting y to 7
computeValue() is called.
area.get() = 35.0
Notice that computeValue() is called only once when we call area.get() twice in a row.
■■Caution The DoubleBinding abstract class contains a default implementation of dispose() that is empty
and a default implementation of getDependencies() that returns an empty list. To make this example a correct
Binding implementation, we should override these two methods to behave correctly.
Now that you have a firm grasp of the key interfaces and concepts of the JavaFX properties and bindings
framework, we show you how these generic interfaces are specialized to type-specific interfaces and
implemented in type-specific abstract and concrete classes.
Type-Specific Specializations of Key Interfaces
We did not emphasize this fact in the last section because we believe its omission does not hurt the
explanations there, but except for Observable and InvalidationListener, the rest of the interfaces are
generic interfaces with a type parameter . In this section, we examine how these generic interfaces are
specialized to the specific types of interest: Boolean, Integer, Long, Float, Double, String, and Object. We
93
Chapter 3 ■ Properties and Bindings
also examine some of the abstract and concrete classes of the framework and explore typical usage scenarios
of each class.
■■Note Specializations of these interfaces also exist for List, Map, and Set. They are designed for working
with observable collections. We cover observable collections in Chapter 7.
A Common Theme for Type-Specific Interfaces
Although the generic interfaces are not all specialized in exactly the same way, a common theme exists:
•
The Boolean type is specialized directly.
•
The Integer, Long, Float, and Double types are specialized through the Number
supertype.
•
The String type is specialized through the Object type.
This theme exists in the type-specific specializations of all the key interfaces. As an example, we
examine the subinterfaces of the ObservableValue interface:
•
ObservableBooleanValue extends ObservableValue, and it offers one
additional method.
•
•
•
boolean get();
ObservableNumberValue extends ObservableValue, and it offers four
additional methods.
•
int intValue();
•
long longValue();
•
float floatValue();
•
double doubleValue();
ObservableObjectValue extends ObservableValue, and it offers one
additional method.
•
T get();
•
ObservableIntegerValue, ObservableLongValue, ObservableFloatValue, and
ObservableDoubleValue extend ObservableNumberValue and each offers an
additional get() method that returns the appropriate primitive type value.
•
ObservableStringValue extends ObservableObjectValue and inherits its
get() method that returns String.
Notice that the get() method that we have been using in the examples is defined in the type-specific
ObservableValue subinterfaces. A similar examination reveals that the set() method that we have been
using in the examples is defined in the type-specific WritableValue subinterfaces.
94
Chapter 3 ■ Properties and Bindings
A practical consequence of this derivation hierarchy is that any numerical property can call bind()
on any other numerical property or binding. Indeed, the signature of the bind() method on any numerical
property is as follows:
void bind(ObservableValue observable);
And any numerical property and binding is assignable to the generic parameter type. The program in
Listing 3-4 shows that any numerical properties of different specific types can be bound to each other.
Listing 3-4. NumericPropertiesExample.java
import
import
import
import
import
import
import
import
javafx.beans.property.DoubleProperty;
javafx.beans.property.FloatProperty;
javafx.beans.property.IntegerProperty;
javafx.beans.property.LongProperty;
javafx.beans.property.SimpleDoubleProperty;
javafx.beans.property.SimpleFloatProperty;
javafx.beans.property.SimpleIntegerProperty;
javafx.beans.property.SimpleLongProperty;
public class NumericPropertiesExample {
public static void main(String[] args) {
IntegerProperty i = new SimpleIntegerProperty(null, "i", 1024);
LongProperty l = new SimpleLongProperty(null, "l", 0L);
FloatProperty f = new SimpleFloatProperty(null, "f", 0.0F);
DoubleProperty d = new SimpleDoubleProperty(null, "d", 0.0);
System.out.println("Constructed numerical properties i, l, f, d.");
System.out.println("i.get()
System.out.println("l.get()
System.out.println("f.get()
System.out.println("d.get()
=
=
=
=
"
"
"
"
+
+
+
+
i.get());
l.get());
f.get());
d.get());
l.bind(i);
f.bind(l);
d.bind(f);
System.out.println("Bound l to i, f to l, d to f.");
System.out.println("i.get()
System.out.println("l.get()
System.out.println("f.get()
System.out.println("d.get()
=
=
=
=
"
"
"
"
+
+
+
+
i.get());
l.get());
f.get());
d.get());
System.out.println("Calling i.set(2048).");
i.set(2048);
System.out.println("i.get()
System.out.println("l.get()
System.out.println("f.get()
System.out.println("d.get()
=
=
=
=
"
"
"
"
+
+
+
+
i.get());
l.get());
f.get());
d.get());
95
Chapter 3 ■ Properties and Bindings
d.unbind();
f.unbind();
l.unbind();
System.out.println("Unbound l to i, f to l, d to f.");
f.bind(d);
l.bind(f);
i.bind(l);
System.out.println("Bound f to d, l to f, i to l.");
System.out.println("Calling d.set(10000000000L).");
d.set(10000000000L);
System.out.println("d.get()
System.out.println("f.get()
System.out.println("l.get()
System.out.println("i.get()
}
}
=
=
=
=
"
"
"
"
+
+
+
+
d.get());
f.get());
l.get());
i.get());
In this example we created four numeric properties and bound them into a chain in decreasing size to
demonstrate that the bindings work as expected. We then reversed the order of the chain and set the double
property’s value to a number that would overflow the integer property to highlight the fact that even though
you can bind different sizes of numeric properties together, when the value of the dependent property is
outside the range of the binding property, normal Java numeric conversion applies.
When we run the program in Listing 3-4, the following is printed to the console:
Constructed numerical properties i, l, f, d.
i.get() = 1024
l.get() = 0
f.get() = 0.0
d.get() = 0.0
Bound l to i, f to l, d to f.
i.get() = 1024
l.get() = 1024
f.get() = 1024.0
d.get() = 1024.0
Calling i.set(2048).
i.get() = 2048
l.get() = 2048
f.get() = 2048.0
d.get() = 2048.0
Unbound l to i, f to l, d to f.
Bound f to d, l to f, i to l.
Calling d.set(10000000000L).
d.get() = 1.0E10
f.get() = 1.0E10
l.get() = 10000000000
i.get() = 1410065408
96
Chapter 3 ■ Properties and Bindings
Commonly Used Classes
We now give a survey of the content of the four packages javafx.beans, javafx.beans.binding, javafx.
beans.property, and javafx.beans.value. In this section, the SimpleIntegerProperty series of classes
refers to the classes extrapolated over the Boolean, Integer, Long, Float, Double, String, and Object types.
Therefore, what is said also applies to SimpleBooleanProperty, and so on.
•
The most often used classes in the JavaFX properties and bindings framework are the
SimpleIntegerProperty series of classes. They provide all the functionalities of the
Property interface including lazy evaluation. They are used in all the examples of
this chapter up to this point.
•
Another set of concrete classes in the JavaFX properties and bindings framework
is the ReadOnlyIntegerWrapper series of classes. These classes implement the
Property interface but also have a getReadOnlyProperty() method that returns
a ReadOnlyProperty that is synchronized with the main Property. They are very
handy to use when you need a full-blown Property for the implementation of a
component but you only want to hand out a ReadOnlyProperty to the client of the
component.
•
The IntegerPropertyBase series of abstract classes can be extended to
provide implementations of full Property classes, although in practice the
SimpleIntegerProperty series of classes is easier to use. The only abstract methods
in the IntegerPropertyBase series of classes are getBean() and getName().
•
The ReadOnlyIntegerPropertyBase series of abstract classes can be extended to
provide implementations of ReadOnlyProperty classes. This is rarely necessary. The
only abstract methods in the ReadOnlyIntegerPropertyBase series of classes are
get(), getBean(), and getName().
•
The WeakInvalidationListener and WeakChangeListener classes can be used to
wrap InvalidationListener and ChangeListener instances before addListener()
is called. They hold weak references of the wrapped listener instances. As long as
you hold a reference to the wrapped listener on your side, the weak references will
be kept alive and you will receive events. When you are done with the wrapped
listener and have unreferenced it from your side, the weak references will be eligible
for garbage collection, and then later garbage collected. All the JavaFX properties
and bindings framework Observable objects know how to clean up a weak listener
after its weak reference has been garbage collected. This prevents memory leaks
when the listeners are not removed after use. The WeakInvalidationListener
and WeakListener classes implement the WeakListener interface, whose
wasGarbageCollected() method will return true if the wrapped listener instance
was garbage collected.
That covers all the JavaFX properties and bindings APIs that reside in the javafx.beans, javafx.beans.
property, and javafx.beans.value packages and some but not all of the APIs in the javafx.beans.binding
package. The javafx.beans.property.adapters package provides adapters between old-style JavaBeans
properties and JavaFX properties. We will cover these adapters in the “Adapting JavaBeans Properties to
JavaFX Properties” section. The remaining classes of the javafx.beans.binding package are APIs that help
you to create new bindings out of existing properties and bindings. That is the focus of the next section.
97
Chapter 3 ■ Properties and Bindings
Creating Bindings
We now turn our focus to the creation of new bindings out of existing properties and bindings. You learned
in the “Understanding Key Interfaces and Concepts” section earlier in this chapter that a binding is an
observable value that has a list of dependencies that are also observable values.
The JavaFX properties and bindings framework offers three ways of creating new bindings:
•
Extending the IntegerBinding series of abstract classes.
•
Using the bindings-creating static methods in the utilities class Bindings.
•
Using the fluent interface API provided by the IntegerExpression series of abstract
classes.
You saw the direct extension approach in the “Understanding the Binding Interface” section. We
explore the Bindings utility class next.
Understanding the Bindings Utility Class
The Bindings class contains 236 factory methods that make new bindings out of existing observable values
and regular values. Most of the methods are overloaded to take into account that both observable values and
regular Java (unobservable) values can be used to build new bindings. At least one of the parameters must
be an observable value. Here are the signatures of the nine overloaded add() methods:
public
public
public
public
public
public
public
public
public
static
static
static
static
static
static
static
static
static
NumberBinding
DoubleBinding
DoubleBinding
NumberBinding
NumberBinding
NumberBinding
NumberBinding
NumberBinding
NumberBinding
add(ObservableNumberValue n1, ObservableNumberValue n2)
add(ObservableNumberValue n, double d)
add(double d, ObservableNumberValue n)
add(ObservableNumberValue n, float f)
add(float f, ObservableNumberValue n)
add(ObservableNumberValue n, long l)
add(long l, ObservableNumberValue n)
add(ObservableNumberValue n, int i)
add(int i, ObservableNumberValue n)
When the add() method is called, it returns a NumberBinding with dependencies that include all the
observable value parameters, and whose value is the sum of the value of its two parameters. Similarly
overloaded methods exist for subtract(), multiply(), and divide().
■■Note
Recall from the last section that ObservableIntegerValue, ObservableLongValue,
ObservableFloatValue, and ObservableDoubleValue are subclasses of ObservableNumberValue. Therefore,
the four arithmetic methods just mentioned can take any combinations of these observable numeric values as
well as any unobservable values.
The program in Listing 3-5 uses the arithmetic methods in Bindings to calculate the area of a triangle in
the Cartesian plane with vertices (x1, y1), (x2, y2), (x3, y3) using this formula:
Area = (x1*y2 + x2*y3 + x3*y1 – x1*y3 – x2*y1 – x3*y2) / 2
98
Chapter 3 ■ Properties and Bindings
Listing 3-5. TriangleAreaExample.java
import
import
import
import
javafx.beans.binding.Bindings;
javafx.beans.binding.NumberBinding;
javafx.beans.property.IntegerProperty;
javafx.beans.property.SimpleIntegerProperty;
public class TriangleAreaExample {
public static void main(String[] args) {
IntegerProperty x1 = new SimpleIntegerProperty(0);
IntegerProperty y1 = new SimpleIntegerProperty(0);
IntegerProperty x2 = new SimpleIntegerProperty(0);
IntegerProperty y2 = new SimpleIntegerProperty(0);
IntegerProperty x3 = new SimpleIntegerProperty(0);
IntegerProperty y3 = new SimpleIntegerProperty(0);
final
final
final
final
final
final
NumberBinding
NumberBinding
NumberBinding
NumberBinding
NumberBinding
NumberBinding
x1y2
x2y3
x3y1
x1y3
x2y1
x3y2
=
=
=
=
=
=
Bindings.multiply(x1,
Bindings.multiply(x2,
Bindings.multiply(x3,
Bindings.multiply(x1,
Bindings.multiply(x2,
Bindings.multiply(x3,
y2);
y3);
y1);
y3);
y1);
y2);
final
final
final
final
final
final
final
NumberBinding
NumberBinding
NumberBinding
NumberBinding
NumberBinding
NumberBinding
NumberBinding
sum1 = Bindings.add(x1y2, x2y3);
sum2 = Bindings.add(sum1, x3y1);
sum3 = Bindings.add(sum2, x3y1);
diff1 = Bindings.subtract(sum3, x1y3);
diff2 = Bindings.subtract(diff1, x2y1);
determinant = Bindings.subtract(diff2, x3y2);
area = Bindings.divide(determinant, 2.0D);
x1.set(0); y1.set(0);
x2.set(6); y2.set(0);
x3.set(4); y3.set(3);
printResult(x1, y1, x2, y2, x3, y3, area);
x1.set(1); y1.set(0);
x2.set(2); y2.set(2);
x3.set(0); y3.set(1);
printResult(x1, y1, x2, y2, x3, y3, area);
}
private static void printResult(IntegerProperty x1,
IntegerProperty x2,
IntegerProperty x3,
NumberBinding area)
System.out.println("For A(" +
IntegerProperty y1,
IntegerProperty y2,
IntegerProperty y3,
{
99
Chapter 3 ■ Properties and Bindings
x1.get() + "," + y1.get() + "), B(" +
x2.get() + "," + y2.get() + "), C(" +
x3.get() + "," + y3.get() + "), the area of triangle ABC is " + area.
getValue());
}
}
We used IntegerProperty to represent the coordinates. The building up of the NumberBinding area
uses all four arithmetic factory methods of Bindings. Because we started with IntegerProperty objects,
even though the return type from the arithmetic factory methods of Bindings is NumberBinding, the actual
objects that are returned, up to determinant, are IntegerBinding objects. We used 2.0D rather than a
mere 2 in the divide() call to force the division to be done as a double division, not as int division. All
the properties and bindings that we build up form a tree structure with area as the root, the intermediate
bindings as internal nodes, and the properties x1, y1, x2, y2, x3, y3 as leaves. This tree is similar to the parse
tree we will get if we parse the mathematical expression for the area formula using grammar for the regular
arithmetic expressions.
When we run the program in Listing 3-5, the following output is printed to the console:
For A(0,0), B(6,0), C(4,3), the area of triangle ABC is 9.0
For A(1,0), B(2,2), C(0,1), the area of triangle ABC is 1.5
Aside from the arithmetic methods, the Bindings class also has the following factory methods.
•
Logical operators: and, or, not
•
Numeric operators: min, max, negate
•
Object operators: isNull, isNotNull
•
String operators: length, isEmpty, isNotEmpty
•
Relational operators:
•
100
•
equal
•
equalIgnoreCase
•
greaterThan
•
greaterThanOrEqual
•
lessThan
•
lessThanOrEqual
•
notEqual
•
notEqualIgnoreCase
Creation operators:
•
createBooleanBinding
•
createIntegerBinding
•
createLongBinding
•
createFloatBinding
Chapter 3 ■ Properties and Bindings
•
•
createDoubleBinding
•
createStringBinding
•
createObjectBinding
Selection operators:
•
select
•
selectBoolean
•
selectInteger
•
selectLong
•
selectFloat
•
selectDouble
•
selectString
Except for the creation operators and the selection operators, the preceding operators all do what you
think they will do. The object operators are meaningful only for observable string values and observable
object values. The string operators are meaningful only for observable string values. All relational operators
except for the IgnoreCase ones apply to numeric values. There are versions of the equal and notEqual
operators for numeric values that have a third double parameter for the tolerance when comparing float or
double values. The equal and notEqual operators also apply to boolean, string, and object values. For string
and object values, the equal and notEqual operator compares their values using the equals() method.
The creation operators provide a convenient way of creating a binding without directly extending the
abstract base class. It takes a Callable and any number of dependencies as an argument. The area double
binding in Listing 3-3 can be rewritten using a lambda expression as the Callable, as follows,:
DoubleBinding area = Bindings.createDoubleBinding(() -> {
return x.get() * y.get();
}, x, y);
The selection operators operate on what are called JavaFX Beans, Java classes constructed according
to the JavaFX Beans specification. We talk about JavaFX Beans in the “Understanding JavaFX Beans
Convention” section later in this chapter.
There are a number of methods in Bindings that deal with observable collections. We cover them in
Chapter 7.
That covers all methods in Bindings that return a binding object. There are 18 methods in Bindings that
do not return a binding object. The various bindBidirectional() and unbindBidirectional() methods
create bidirectional bindings. As a matter of fact, the bindBidirectional() and unbindBidirectional()
methods in the various properties classes simply call the corresponding ones in the Bindings class. The
bindContent() and unbindContent() methods bind an ordinary collection to an observable collection. The
convert(), concat(), and a pair of overloaded format() methods return StringExpression objects. And
finally, the when() method returns a When object.
The When and the StringExpression classes are part of the fluent interface API for creating bindings,
which we cover in the next subsection.
101
Chapter 3 ■ Properties and Bindings
Understanding the Fluent Interface API
If you asked, “Why would anybody name a method when()?” and “What kind of information would the When
class encapsulate?”—welcome to the club. While you were not looking, the object-oriented programming
community invented a brand-new method of API design that totally disregards the decades-old principles of
object-oriented practices. Instead of encapsulating data and distributing business logic into relevant domain
objects, this new methodology produces a style of API that encourages method chaining and uses the return
type of one method to determine what methods are available for the next car of the choo-choo train. Method
names are chosen not to convey complete meaning, but to make the entire method chain read like a fluent
sentence. This style is called a fluent interface API.
■■Note You can find a more thorough exposition of fluent interfaces on Martin Fowler’s web site, referenced
at the end of this chapter.
The fluent interface APIs for creating bindings are defined in the IntegerExpression series of classes.
IntegerExpression is a superclass of both IntegerProperty and IntegerBinding, making the methods of
IntegerExpression also available in the IntegerProperty and IntegerBinding classes. The four numeric
expression classes share a common superinterface NumberExpression, where all the methods are defined.
The type-specific expression classes override some of the methods that yield a NumberBinding to return a
more appropriate type of binding.
The methods thus made available for the seven kinds of properties and bindings are listed here:
•
102
•
For BooleanProperty and BooleanBindingBooleanBinding
and(ObservableBooleanValue b)
•
BooleanBinding or(ObservableBooleanValue b)
•
BooleanBinding not()
•
BooleanBinding isEqualTo(ObservableBooleanValue b)
•
BooleanBinding isNotEqualTo(ObservableBooleanValue b)
•
StringBinding asString()
Common for all numeric properties and bindings
•
BooleanBinding isEqualTo(ObservableNumberValue m)
•
BooleanBinding isEqualTo(ObservableNumberValue m, double err)
•
BooleanBinding isEqualTo(double d, double err)
•
BooleanBinding isEqualTo(float f, double err)
•
BooleanBinding isEqualTo(long l)
•
BooleanBinding isEqualTo(long l, double err)
•
BooleanBinding isEqualTo(int i)
•
BooleanBinding isEqualTo(int i, double err)
•
BooleanBinding isNotEqualTo(ObservableNumberValue m)
•
BooleanBinding isNotEqualTo(ObservableNumberValue m, double err)
Chapter 3 ■ Properties and Bindings
•
•
BooleanBinding isNotEqualTo(double d, double err)
•
BooleanBinding isNotEqualTo(float f, double err)
•
BooleanBinding isNotEqualTo(long l)
•
BooleanBinding isNotEqualTo(long l, double err)
•
BooleanBinding isNotEqualTo(int i)
•
BooleanBinding isNotEqualTo(int i, double err)
•
BooleanBinding greaterThan(ObservableNumberValue m)
•
BooleanBinding greaterThan(double d)
•
BooleanBinding greaterThan(float f)
•
BooleanBinding greaterThan(long l)
•
BooleanBinding greaterThan(int i)
•
BooleanBinding lessThan(ObservableNumberValue m)
•
BooleanBinding lessThan(double d)
•
BooleanBinding lessThan(float f)
•
BooleanBinding lessThan(long l)
•
BooleanBinding lessThan(int i)
•
BooleanBinding greaterThanOrEqualTo(ObservableNumberValue m)
•
BooleanBinding greaterThanOrEqualTo(double d)
•
BooleanBinding greaterThanOrEqualTo(float f)
•
BooleanBinding greaterThanOrEqualTo(long l)
•
BooleanBinding greaterThanOrEqualTo(int i)
•
BooleanBinding lessThanOrEqualTo(ObservableNumberValue m)
•
BooleanBinding lessThanOrEqualTo(double d)
•
BooleanBinding lessThanOrEqualTo(float f)
•
BooleanBinding lessThanOrEqualTo(long l)
•
BooleanBinding lessThanOrEqualTo(int i)
•
StringBinding asString()
•
StringBinding asString(String str)
•
StringBinding asString(Locale locale, String str)
For IntegerProperty and IntegerBinding
•
IntegerBinding negate()
•
NumberBinding add(ObservableNumberValue n)
•
DoubleBinding add(double d)
103
Chapter 3 ■ Properties and Bindings
•
104
•
FloatBinding add(float f)
•
LongBinding add(long l)
•
IntegerBinding add(int i)
•
NumberBinding subtract(ObservableNumberValue n)
•
DoubleBinding subtract(double d)
•
FloatBinding subtract(float f)
•
LongBinding subtract(long l)
•
IntegerBinding subtract(int i)
•
NumberBinding multiply(ObservableNumberValue n)
•
DoubleBinding multiply(double d)
•
FloatBinding multiply(float f)
•
LongBinding multiply(long l)
•
IntegerBinding multiply(int i)
•
NumberBinding divide(ObservableNumberValue n)
•
DoubleBinding divide(double d)
•
FloatBinding divide(float f)
•
LongBinding divide(long l)
•
IntegerBinding divide(int i)
For LongProperty and LongBinding
•
LongBinding negate()
•
NumberBinding add(ObservableNumberValue n)
•
DoubleBinding add(double d)
•
FloatBinding add(float f)
•
LongBinding add(long l)
•
LongBinding add(int i)
•
NumberBinding subtract(ObservableNumberValue n)
•
DoubleBinding subtract(double d)
•
FloatBinding subtract(float f)
•
LongBinding subtract(long l)
•
LongBinding subtract(int i)
•
NumberBinding multiply(ObservableNumberValue n)
•
DoubleBinding multiply(double d)
•
FloatBinding multiply(float f)
Chapter 3 ■ Properties and Bindings
•
•
•
LongBinding multiply(long l)
•
LongBinding multiply(int i)
•
NumberBinding divide(ObservableNumberValue n)
•
DoubleBinding divide(double d)
•
FloatBinding divide(float f)
•
LongBinding divide(long l)
•
LongBinding divide(int i)
For FloatProperty and FloatBinding
•
FloatBinding negate()
•
NumberBinding add(ObservableNumberValue n)
•
DoubleBinding add(double d)
•
FloatBinding add(float g)
•
FloatBinding add(long l)
•
FloatBinding add(int i)
•
NumberBinding subtract(ObservableNumberValue n)
•
DoubleBinding subtract(double d)
•
FloatBinding subtract(float g)
•
FloatBinding subtract(long l)
•
FloatBinding subtract(int i)
•
NumberBinding multiply(ObservableNumberValue n)
•
DoubleBinding multiply(double d)
•
FloatBinding multiply(float g)
•
FloatBinding multiply(long l)
•
FloatBinding multiply(int i)
•
NumberBinding divide(ObservableNumberValue n)
•
DoubleBinding divide(double d)
•
FloatBinding divide(float g)
•
FloatBinding divide(long l)
•
FloatBinding divide(int i)
For DoubleProperty and DoubleBinding
•
DoubleBinding negate()
•
DoubleBinding add(ObservableNumberValue n)
•
DoubleBinding add(double d)
105
Chapter 3 ■ Properties and Bindings
•
106
•
DoubleBinding add(float f)
•
DoubleBinding add(long l)
•
DoubleBinding add(int i)
•
DoubleBinding subtract(ObservableNumberValue n)
•
DoubleBinding subtract(double d)
•
DoubleBinding subtract(float f)
•
DoubleBinding subtract(long l)
•
DoubleBinding subtract(int i)
•
DoubleBinding multiply(ObservableNumberValue n)
•
DoubleBinding multiply(double d)
•
DoubleBinding multiply(float f)
•
DoubleBinding multiply(long l)
•
DoubleBinding multiply(int i)
•
DoubleBinding divide(ObservableNumberValue n)
•
DoubleBinding divide(double d)
•
DoubleBinding divide(float f)
•
DoubleBinding divide(long l)
•
DoubleBinding divide(int i)
For StringProperty and StringBinding
•
StringExpression concat(Object obj)
•
BooleanBinding isEqualTo(ObservableStringValue str)
•
BooleanBinding isEqualTo(String str)
•
BooleanBinding isNotEqualTo(ObservableStringValue str)
•
BooleanBinding isNotEqualTo(String str)
•
BooleanBinding isEqualToIgnoreCase(ObservableStringValue str)
•
BooleanBinding isEqualToIgnoreCase(String str)
•
BooleanBinding isNotEqualToIgnoreCase(ObservableStringValue str)
•
BooleanBinding isNotEqualToIgnoreCase(String str)
•
BooleanBinding greaterThan(ObservableStringValue str)
•
BooleanBinding greaterThan(String str)
•
BooleanBinding lessThan(ObservableStringValue str)
•
BooleanBinding lessThan(String str)
•
BooleanBinding greaterThanOrEqualTo(ObservableStringValue str)
Chapter 3 ■ Properties and Bindings
•
•
BooleanBinding greaterThanOrEqualTo(String str)
•
BooleanBinding lessThanOrEqualTo(ObservableStringValue str)
•
BooleanBinding lessThanOrEqualTo(String str)
•
BooleanBinding isNull()
•
BooleanBinding isNotNull()
•
IntegerBinding length()
•
BooleanExpression isEmpty()
•
BooleanExpression isNotEmpty()
For ObjectProperty and ObjectBinding
•
BooleanBinding isEqualTo(ObservableObjectValue obj)
•
BooleanBinding isEqualTo(Object obj)
•
BooleanBinding isNotEqualTo(ObservableObjectValue obj)
•
BooleanBinding isNotEqualTo(Object obj)
•
BooleanBinding isNull()
•
BooleanBinding isNotNull()
With these methods, you can create an infinite variety of bindings by starting with a property and
calling one of the methods that is appropriate for the type of the property to get a binding, and calling one
of the methods that is appropriate for the type of the binding to get another binding, and so on. One fact
that is worth pointing out here is that all the methods for the type-specific numeric expressions are defined
in the NumberExpression base interface with a return type of NumberBinding, and are overridden in the
type-specific expression classes with an identical parameter signature but a more specific return type. This
way of overriding a method in a subclass with an identical parameter signature but a more specific return
type is called covariant return-type overriding, and has been a Java language feature since Java 5. One of
the consequences of this fact is that numeric bindings built with the fluent interface API have more specific
types than those built with factory methods in the Bindings class.
Sometimes it is necessary to convert a type-specific expression into an object expression holding the
same type of value. This can be done with the asObject() method in the type-specific expression class. The
conversion back can be done using static methods in the expressions class. For IntegerExpression, these
static methods are as follows:
static IntegerExpression integerExpression(ObservableIntegerValue value)
static IntegerExpression integerExpression(ObservableValue value)
The program in Listing 3-6 is a modification of the triangle area example in Listing 3-5 that uses the
fluent interface API instead of calling factory methods in the Bindings class.
Listing 3-6. TriangleAreaFluentExample.java
import
import
import
import
import
javafx.beans.binding.Bindings;
javafx.beans.binding.NumberBinding;
javafx.beans.binding.StringExpression;
javafx.beans.property.IntegerProperty;
javafx.beans.property.SimpleIntegerProperty;
107
Chapter 3 ■ Properties and Bindings
public class TriangleAreaFluentExample {
public static void main(String[] args) {
IntegerProperty x1 = new SimpleIntegerProperty(0);
IntegerProperty y1 = new SimpleIntegerProperty(0);
IntegerProperty x2 = new SimpleIntegerProperty(0);
IntegerProperty y2 = new SimpleIntegerProperty(0);
IntegerProperty x3 = new SimpleIntegerProperty(0);
IntegerProperty y3 = new SimpleIntegerProperty(0);
final NumberBinding area = x1.multiply(y2)
.add(x2.multiply(y3))
.add(x3.multiply(y1))
.subtract(x1.multiply(y3))
.subtract(x2.multiply(y1))
.subtract(x3.multiply(y2))
.divide(2.0D);
StringExpression output = Bindings.format(
"For A(%d,%d), B(%d,%d), C(%d,%d), the area of triangle ABC is %3.1f",
x1, y1, x2, y2, x3, y3, area);
x1.set(0); y1.set(0);
x2.set(6); y2.set(0);
x3.set(4); y3.set(3);
System.out.println(output.get());
x1.set(1); y1.set(0);
x2.set(2); y2.set(2);
x3.set(0); y3.set(1);
System.out.println(output.get());
}
}
Notice how the 13 lines of code and 12 intermediate variables used in Listing 3-5 to build up the area
binding are reduced to the 7 lines of code with no intermediate variables used in Listing 3-6. We also used
the Bindings.format() method to build up a StringExpression object called output. There are two
overloaded Bindings.format() methods with signatures:
StringExpression format(Locale locale, String format, Object... args)
StringExpression format(String format, Object... args)
They work similarly to the corresponding String.format() methods in that they format the values args
according to the format specification format and the Locale locale, or the default Locale. If any of the args
is an ObservableValue, its change is reflected in the StringExpression.
When we run the program in Listing 3-6, the following output is printed to the console:
For A(0,0), B(6,0), C(4,3), the area of triangle ABC is 9.0
For A(1,0), B(2,2), C(0,1), the area of triangle ABC is 1.5
108
Chapter 3 ■ Properties and Bindings
Next we unravel the mystery of the When class and the role it plays in constructing bindings that are
essentially if/then/else expressions. The When class has a constructor that takes an ObservableBooleanValue
argument:
public When(ObservableBooleanValue b)
It has the following 11 overloaded then() methods.
When.NumberConditionBuilder then(ObservableNumberValue n)
When.NumberConditionBuilder then(double d)
When.NumberConditionBuilder then(float f)
When.NumberConditionBuilder then(long l)
When.NumberConditionBuilder then(int i)
When.BooleanConditionBuilder then(ObservableBooleanValue b)
When.BooleanConditionBuilder then(boolean b)
When.StringConditionBuilder then(ObservableStringValue str)
When.StringConditionBuilder then(String str)
When.ObjectConditionBuilder then(ObservableObjectValue obj)
When.ObjectConditionBuilder then(T obj)
The type of object returned from the then() method depends on the type of the argument.
If the argument is a numeric type, either observable or unobservable, the return type is a nested
class When.NumberConditionBuilder. Similarly, for Boolean arguments, the return type is When.
BooleanConditionBuilder; for string arguments, When.StringConditionBuilder; and for object arguments,
When.ObjectConditionBuilder.
These condition builders in turn have the following otherwise() methods.
•
•
•
•
For When.NumberConditionBuilder
•
NumberBinding otherwise(ObservableNumberValue n)
•
DoubleBinding otherwise(double d)
•
NumberBinding otherwise(float f)
•
NumberBinding otherwise(long l)
•
NumberBinding otherwise(int i)
For When.BooleanConditionBuilder
•
BooleanBinding otherwise(ObservableBooleanValue b)
•
BooleanBinding otherwise(boolean b)
For When.StringConditionBuilder
•
StringBinding otherwise(ObservableStringValue str)
•
StringBinding otherwise(String str)
For When.ObjectConditionBuilder
•
ObjectBinding otherwise(ObservableObjectValue
•
ObjectBinding otherwise(T obj)
obj)
109
Chapter 3 ■ Properties and Bindings
The net effect of these method signatures is that you can build up a binding that resembles an if/then/
else expression this way:
new When(b).then(x).otherwise(y)
b is an ObservableBooleanValue, and x and y are of similar types and can be either observable or
unobservable. The resulting binding will be of a type similar to that of x and y.
The program in Listing 3-7 uses the fluent interface API from the When class to calculate the area of a
triangle with given sides a, b, and c. Recall that to form a triangle, the three sides must satisfy the following
conditions:
a + b > c, b + c > a, c + a > b.
When the preceding conditions are satisfied, the area of the triangle can be calculated using Heron’s
formula:
Area = sqrt(s * (s – a) * (s – b) * (s – c))
where s is the semiperimeter:
s = (a + b + c) / 2.
Listing 3-7. HeronsFormulaExample.java
import javafx.beans.binding.DoubleBinding;
import javafx.beans.binding.When;
import javafx.beans.property.DoubleProperty;
import javafx.beans.property.SimpleDoubleProperty;
public class HeronsFormulaExample {
public static void main(String[] args) {
DoubleProperty a = new SimpleDoubleProperty(0);
DoubleProperty b = new SimpleDoubleProperty(0);
DoubleProperty c = new SimpleDoubleProperty(0);
DoubleBinding s = a.add(b).add(c).divide(2.0D);
final DoubleBinding areaSquared = new When(
a.add(b).greaterThan(c)
.and(b.add(c).greaterThan(a))
.and(c.add(a).greaterThan(b)))
.then(s.multiply(s.subtract(a))
.multiply(s.subtract(b))
.multiply(s.subtract(c)))
.otherwise(0.0D);
a.set(3);
b.set(4);
c.set(5);
System.out.printf("Given sides a = %1.0f, b = %1.0f, and c = %1.0f," +
110
Chapter 3 ■ Properties and Bindings
" the area of the triangle is %3.2f\n", a.get(), b.get(), c.get(),
Math.sqrt(areaSquared.get()));
a.set(2);
b.set(2);
c.set(2);
System.out.printf("Given sides a = %1.0f, b = %1.0f, and c = %1.0f," +
" the area of the triangle is %3.2f\n", a.get(), b.get(), c.get(),
Math.sqrt(areaSquared.get()));
}
}
Inasmuch as there is no ready-made binding method in DoubleExpression that calculates the square
root, we create a DoubleBinding for areaSquared instead. The constructor argument for When() is a
BooleanBinding built out of the three conditions on a, b, and c. The argument for the then() method is a
DoubleBinding that calculates the square of the area of the triangle. And because the then() argument is
numeric, the otherwise() argument also has to be numeric. We choose to use 0.0D to signal that an invalid
triangle is encountered.
■■Note
Instead of using the When() constructor, you can also use the factory method when() in the
Bindings utility class to create the When object.
When we run the program in Listing 3-7, the following output is printed to the console:
Given sides a = 3, b = 4, and c = 5, the area of the triangle is 6.00.
Given sides a = 2, b = 2, and c = 2, the area of the triangle is 1.73.
If the binding defined in Listing 3-7 makes your head spin a little, you are not alone. We choose this
example simply to illustrate the use of the fluent interface API offered by the When class. As a matter of
fact, this example might be better served with a direct subclassing approach we first introduced in the
“Understanding the Binding Interface” section.
The program in Listing 3-8 solves the same problem as Listing 3-7 by using the direct extension method.
Listing 3-8. HeronsFormulaDirectExtensionExample.java
import javafx.beans.binding.DoubleBinding;
import javafx.beans.property.DoubleProperty;
import javafx.beans.property.SimpleDoubleProperty;
public class HeronsFormulaDirectExtensionExample {
public static void main(String[] args) {
final DoubleProperty a = new SimpleDoubleProperty(0);
final DoubleProperty b = new SimpleDoubleProperty(0);
final DoubleProperty c = new SimpleDoubleProperty(0);
111
Chapter 3 ■ Properties and Bindings
DoubleBinding area = new DoubleBinding() {
{
super.bind(a, b, c);
}
@Override
protected double computeValue() {
double a0 = a.get();
double b0 = b.get();
double c0 = c.get();
if ((a0 + b0 > c0) && (b0 + c0 > a0) && (c0 + a0 > b0)) {
double s = (a0 + b0 + c0) / 2.0D;
return Math.sqrt(s * (s - a0) * (s - b0) * (s - c0));
} else {
return 0.0D;
}
}
};
a.set(3);
b.set(4);
c.set(5);
System.out.printf("Given sides a = %1.0f, b = %1.0f, and c = %1.0f," +
" the area of the triangle is %3.2f\n", a.get(), b.get(), c.get(),
area.get());
a.set(2);
b.set(2);
c.set(2);
System.out.printf("Given sides a = %1.0f, b = %1.0f, and c = %1.0f," +
" the area of the triangle is %3.2f\n", a.get(), b.get(), c.get(),
area.get());
}
}
The direct extension method is preferred for complicated expressions and for expressions that go
beyond the available operators.
Now that you have mastered all the APIs in the javafx.beans, javafx.beans.binding, javafx.beans.
property, and javafx.beans.value packages, you are ready to step beyond the details of the JavaFX
properties and bindings framework and learn how these properties are organized into bigger components
called JavaFX Beans.
Understanding the JavaFX Beans Convention
JavaFX introduces the concept of JavaFX Beans, a set of conventions that provide properties support for Java
objects. In this section, we talk about the naming conventions for specifying JavaFX Beans properties, several
ways of implementing JavaFX Beans properties, and finally the use of selection bindings.
112
Chapter 3 ■ Properties and Bindings
The JavaFX Beans Specification
For many years Java has used the JavaBeans API to represent a property of an object. A JavaBeans property
is represented by a pair of getter and setter methods. Property changes are propagated to property change
listeners through the firing of property change events in the setter code.
JavaFX introduces the JavaFX Beans specification that adds properties support to Java objects through
the help of the properties classes from the JavaFX properties and bindings framework.
■■Caution The word property is used here with two distinct meanings. When we say, “JavaFX Beans
properties,” it should be understood to mean a higher-level concept similar to JavaBeans properties. When
we say, “JavaFX properties and bindings framework properties,” it should be understood to mean the
various implementations of the Property or ReadOnlyProperty interfaces, such as IntegerProperty,
StringProperty, and so on. JavaFX Beans properties are specified using the JavaFX properties and bindings
framework properties.
Like their JavaBeans counterparts, JavaFX Beans properties are specified by a set of methods in a Java
class. To define a JavaFX Beans property in a Java class, you provide three methods: the getter, the setter, and
the property getter. For a property named height of type double, the three methods are:
public final double getHeight();
public final void setHeight(double h);
public DoubleProperty heightProperty();
The names of the getter and setter methods follow the JavaBeans convention. They are obtained
by concatenating “get” and “set” with the name of the property with the first character capitalized. For
boolean type properties, the getter name can also start with “is”. The name of the property getter is obtained
by concatenating the name of the property with “Property”. To define a read-only JavaFX Beans property,
you can either remove the setter method or change it to a private method and change the return type of the
property getter to be a ReadOnlyProperty.
This specification speaks only about the interface of JavaFX Beans properties and does not impose
any implementation constraints. Depending on the number of properties a JavaFX Bean may have, and
the usage patterns of these properties, there are several implementation strategies. Not surprisingly, all of
them use the JavaFX properties and bindings framework properties as the backing store for the values of the
JavaFX Beans properties. We show you these strategies in the next two subsections.
Understanding the Eagerly Instantiated Properties Strategy
The eagerly instantiated properties strategy is the simplest way to implement JavaFX Beans properties. For
every JavaFX Beans property you want to define in an object, you introduce a private field in the class that
is of the appropriate JavaFX properties and bindings framework property type. These private fields are
instantiated at bean construction time. The getter and setter methods simply call the private field’s get()
and set() methods. The property getter simply returns the private field itself.
The program in Listing 3-9 defines a JavaFX Bean with an int property i, a String property str, and a
Color property color.
113
Chapter 3 ■ Properties and Bindings
Listing 3-9. JavaFXBeanModelExample.java
import
import
import
import
import
import
import
javafx.beans.property.IntegerProperty;
javafx.beans.property.ObjectProperty;
javafx.beans.property.SimpleIntegerProperty;
javafx.beans.property.SimpleObjectProperty;
javafx.beans.property.SimpleStringProperty;
javafx.beans.property.StringProperty;
javafx.scene.paint.Color;
public class JavaFXBeanModelExample {
private IntegerProperty i = new SimpleIntegerProperty(this, "i", 0);
private StringProperty str = new SimpleStringProperty(this, "str", "Hello");
private ObjectProperty color = new SimpleObjectProperty(this, "color",
Color.BLACK);
public final int getI() {
return i.get();
}
public final void setI(int i) {
this.i.set(i);
}
public IntegerProperty iProperty() {
return i;
}
public final String getStr() {
return str.get();
}
public final void setStr(String str) {
this.str.set(str);
}
public StringProperty strProperty() {
return str;
}
public final Color getColor() {
return color.get();
}
public final void setColor(Color color) {
this.color.set(color);
}
public ObjectProperty colorProperty() {
return color;
}
}
114
Chapter 3 ■ Properties and Bindings
This is a straightforward Java class. There are only two things we want to point out in this
implementation. First, the getter and setter methods are declared final by convention. Second, when the
private fields are initialized, we called the simple properties constructors with the full context information,
supplying them with this as the first parameter. In all of our previous examples in this chapter, we used
null as the first parameter for the simple properties constructors because those properties are not part of a
higher-level JavaFX Bean object.
The program in Listing 3-10 defines a view class that watches over an instance of the JavaFX Bean
defined in Listing 3-9. It observes changes to the i, str, and color properties of the bean by hooking up
change listeners that print out any changes to the console.
Listing 3-10. JavaFXBeanViewExample.java
import javafx.beans.value.ChangeListener;
import javafx.beans.value.ObservableValue;
import javafx.scene.paint.Color;
public class JavaFXBeanViewExample {
private JavaFXBeanModelExample model;
public JavaFXBeanViewExample(JavaFXBeanModelExample model) {
this.model = model;
hookupChangeListeners();
}
private void hookupChangeListeners() {
model.iProperty().addListener(new ChangeListener() {
@Override
public void changed(ObservableValue observableValue, Number
oldValue, Number newValue) {
System.out.println("Property i changed: old value = " + oldValue + ", new
value = " + newValue);
}
});
model.strProperty().addListener(new ChangeListener() {
@Override
public void changed(ObservableValue observableValue, String
oldValue, String newValue) {
System.out.println("Property str changed: old value = " + oldValue + ", new
value = " + newValue);
}
});
model.colorProperty().addListener(new ChangeListener() {
@Override
public void changed(ObservableValue observableValue, Color
oldValue, Color newValue) {
System.out.println("Property color changed: old value = " + oldValue + ",
new value = " + newValue);
}
});
}
}
115
Chapter 3 ■ Properties and Bindings
The program in Listing 3-11 defines a controller that can modify a model object.
Listing 3-11. JavaFXBeanControllerExample.java
import javafx.scene.paint.Color;
public class JavaFXBeanControllerExample {
private JavaFXBeanModelExample model;
private JavaFXBeanViewExample view;
public JavaFXBeanControllerExample(JavaFXBeanModelExample model,
JavaFXBeanViewExampleÉ
view) {
this.model = model;
this.view = view;
}
public void incrementIPropertyOnModel() {
model.setI(model.getI() + 1);
}
public void changeStrPropertyOnModel() {
final String str = model.getStr();
if (str.equals("Hello")) {
model.setStr("World");
} else {
model.setStr("Hello");
}
}
public void switchColorPropertyOnModel() {
final Color color = model.getColor();
if (color.equals(Color.BLACK)) {
model.setColor(Color.WHITE);
} else {
model.setColor(Color.BLACK);
}
}
}
Notice that this is not a full-blown controller and does not do anything with its reference to the view
object. The program in Listing 3-12 provides a main program that assembles and test drives the classes in
Listings 3-9 to 3-11 in a typical model–view–controller pattern.
116
Chapter 3 ■ Properties and Bindings
Listing 3-12. JavaFXbeanMainExample.java
public class JavaFXBeanMainExample {
public static void main(String[] args) {
JavaFXBeanModelExample model = new JavaFXBeanModelExample();
JavaFXBeanViewExample view = new JavaFXBeanViewExample(model);
JavaFXBeanControllerExample controller = new JavaFXBeanControllerExample(model, view);
controller.incrementIPropertyOnModel();
controller.changeStrPropertyOnModel();
controller.switchColorPropertyOnModel();
controller.incrementIPropertyOnModel();
controller.changeStrPropertyOnModel();
controller.switchColorPropertyOnModel();
}
}
When we run the program in Listings 3-9 to 3-12, the following output is printed to the console:
Property
Property
Property
Property
Property
Property
i changed: old value = 0, new value = 1
str changed: old value = Hello, new value = World
color changed: old value = 0x000000ff, new value = 0xffffffff
i changed: old value = 1, new value = 2
str changed: old value = World, new value = Hello
color changed: old value = 0xffffffff, new value = 0x000000ff
Understanding the Lazily Instantiated Properties Strategy
If your JavaFX Bean has many properties, instantiating all the properties objects up front at bean creation
time may be too heavy an approach. The memory for all the properties objects is truly wasted if only a few of
the properties are actually used. In such situations, you can use one of several lazily instantiated properties
strategies. Two typical such strategies are the half-lazy instantiation strategy and the full-lazy instantiation
strategy.
In the half-lazy strategy, the property object is instantiated only if the setter is called with a value that is
different from the default value, or if the property getter is called. The program in Listing 3-13 illustrates how
this strategy is implemented.
Listing 3-13. JavaFXBeanModelHalfLazyExample.java
import javafx.beans.property.SimpleStringProperty;
import javafx.beans.property.StringProperty;
public class JavaFXBeanModelHalfLazyExample {
private static final String DEFAULT_STR = "Hello";
private StringProperty str;
public final String getStr() {
if (str != null) {
return str.get();
} else {
117
Chapter 3 ■ Properties and Bindings
return DEFAULT_STR;
}
}
public final void setStr(String str) {
if ((this.str != null) || !(str.equals(DEFAULT_STR))) {
strProperty().set(str);
}
}
public StringProperty strProperty() {
if (str == null) {
str = new SimpleStringProperty(this, "str", DEFAULT_STR);
}
return str;
}
}
In this strategy, the client code can call the getter many times without the property object being
instantiated. If the property object is null, the getter simply returns the default value. As soon as the setter
is called with a value that is different from the default value, it will call the property getter, which lazily
instantiates the property object. The property object is also instantiated if the client code calls the property
getter directly.
In the full-lazy strategy, the property object is instantiated only if the property getter is called. The
getter and setter go through the property object only if it is already instantiated; otherwise, they go through a
separate field.
The program in Listing 3-14 shows an example of a full-lazy property.
Listing 3-14. JavaFXBeanModelFullLazyExample.java
import javafx.beans.property.SimpleStringProperty;
import javafx.beans.property.StringProperty;
public class JavaFXBeanModelFullLazyExample {
private static final String DEFAULT_STR = "Hello";
private StringProperty str;
private String _str = DEFAULT_STR;
public final String getStr() {
if (str != null) {
return str.get();
} else {
return _str;
}
}
public final void setStr(String str) {
if (this.str != null) {
this.str.set(str);
} else {
_str = str;
}
}
118
Chapter 3 ■ Properties and Bindings
public StringProperty strProperty() {
if (str == null) {
str = new SimpleStringProperty(this, "str", _str);
}
return str;
}
}
■■Caution The full-lazy instantiation strategy incurs the cost of an extra field to stave off the need for
property instantiation a little longer. Similarly, both the half-lazy and the full-lazy instantiation strategies incur
costs of implementation complexity and runtime performance to gain the benefit of a potentially reduced
runtime memory footprint. This is a classic trade-off situation in software engineering. Which strategy you
choose will depend on the circumstance of your application. Our advice is to introduce optimization only if there
is a need.
Using Selection Bindings
As you saw in the “Understanding the Bindings Utility Class” section, the Bindings utility class contains
seven selection operators. The method signatures of these operators are:
•
select(Object root, String… steps)
•
selectBoolean(Object root, String… steps)
•
selectDouble(Object root, String… steps)
•
selectFloat(Object root, String… steps)
•
selectInteger(Object root, String… steps)
•
selectLong(Object root, String… steps)
•
selectString(Object root, String… steps)
These selection operators allow you to create bindings that observe deeply nested JavaFX Beans
properties. Suppose that you have a JavaFX bean that has a property, whose type is a JavaFX bean that has
a property, whose type is a JavaFX bean that has a property, and so on. Suppose also that you are observing
the root of this properties chain through an ObjectProperty. You can then create a binding that observes
the deeply nested JavaFX Beans property by calling one of the select methods whose type matches the type
of the deeply nested JavaFX Beans property with the ObjectProperty as the root, and the successive JavaFX
Beans property names that reach into the deeply nested JavaFX Beans property as the rest of the arguments.
■■Note There is another set of select methods that takes an ObservableValue as the first parameter. They
were introduced in JavaFX 2.0. The set of select methods that takes an Object as the first parameter allows us
to use any Java object, not merely JavaFX Beans, as the root of a selection binding.
119
Chapter 3 ■ Properties and Bindings
In the following example, we use a few classes from the javafx.scene.effect package—Lighting and
Light—to illustrate how the selection operator works. We teach you how to apply lighting to a JavaFX scene
graph in a later chapter of the book. For now, our interest lies in the fact that Lighting is a JavaFX bean that
has a property named light whose type is Light, and that Light is also a JavaFX bean that has a property
named color whose type is Color (in javafx.scene.paint).
The program in Listing 3-15 illustrates how to observe the color of the light of the lighting.
Listing 3-15. SelectBindingExample.java
import
import
import
import
import
import
import
import
import
javafx.beans.binding.Bindings;
javafx.beans.binding.ObjectBinding;
javafx.beans.property.ObjectProperty;
javafx.beans.property.SimpleObjectProperty;
javafx.beans.value.ChangeListener;
javafx.beans.value.ObservableValue;
javafx.scene.effect.Light;
javafx.scene.effect.Lighting;
javafx.scene.paint.Color;
public class SelectBindingExample {
public static void main(String[] args) {
ObjectProperty root = new SimpleObjectProperty<>(new Lighting());
final ObjectBinding selectBinding = Bindings.select(root, "light", "color");
selectBinding.addListener(new ChangeListener() {
@Override
public void changed(ObservableValue observableValue, Color
oldValue, Color newValue) {
System.out.println("\tThe color changed:\n\t\told color = " +
oldValue + ",\n\t\tnew color = " + newValue);
}
});
System.out.println("firstLight is black.");
Light firstLight = new Light.Point();
firstLight.setColor(Color.BLACK);
System.out.println("secondLight is white.");
Light secondLight = new Light.Point();
secondLight.setColor(Color.WHITE);
System.out.println("firstLighting has firstLight.");
Lighting firstLighting = new Lighting();
firstLighting.setLight(firstLight);
System.out.println("secondLighting has secondLight.");
Lighting secondLighting = new Lighting();
secondLighting.setLight(secondLight);
System.out.println("Making root observe firstLighting.");
root.set(firstLighting);
120
Chapter 3 ■ Properties and Bindings
System.out.println("Making root observe secondLighting.");
root.set(secondLighting);
System.out.println("Changing secondLighting's light to firstLight");
secondLighting.setLight(firstLight);
System.out.println("Changing firstLight's color to red");
firstLight.setColor(Color.RED);
}
}
In this example, the root is an ObjectProperty that observes Lighting objects. The binding
colorBinding observes the color property of the light property of the Lighting object that is the value of
root. We then created some Light and Lighting objects and changed their configuration in various ways.
When we run the program in Listing 3-15, the following output is printed to the console:
firstLight is black.
secondLight is white.
firstLighting has firstLight.
secondLighting has secondLight.
Making root observe firstLighting.
The color changed:
old color = 0xffffffff,
new color = 0x000000ff
Making root observe secondLighting.
The color changed:
old color = 0x000000ff,
new color = 0xffffffff
Changing secondLighting's light to firstLight
The color changed:
old color = 0xffffffff,
new color = 0x000000ff
Changing firstLight's color to red
The color changed:
old color = 0x000000ff,
new color = 0xff0000ff
As expected, a change event is fired for every change in the configuration of the object being observed
by root, and the value of colorBinding always reflects the color of the light of the current Lighting object in
root.
■■Caution The JavaFX properties and bindings framework does not issue any warnings if the supplied
property names do not match any property names in a JavaFX bean. It will simply have the default value for the
type: null for object type, zero for numeric types, false for boolean type, and the empty string for string type.
121
Chapter 3 ■ Properties and Bindings
Adapting JavaBeans Properties to JavaFX Properties
Over the many years since the JavaBeans specification was published, a lot of JavaBeans were written for
various projects, products, and libraries. To better help Java developers leverage these JavaBeans, a set of
adapters were provided in the javafx.beans.properties.adapter package to make them useful in the
JavaFX world by creating a JavaFX property out of JavaBeans properties.
In this section, we first briefly review the JavaBeans specification definition of properties, bound
properties, and constrained properties by way of a simple example. We then show you how to create JavaFX
properties out of JavaBeans properties using the adapters.
Understanding JavaBeans Properties
JavaBeans properties are defined using the familiar getter and setter naming convention. A property is “read
only” if only a getter is provided, and it is “read/write” if both a getter and a setter are provided. A JavaBeans
event is made up of the event object, the event listener interface, and listener registration methods on the
JavaBean. Two particular kinds of events are available for use by JavaBeans properties: A PropertyChange
event can be fired when a JavaBeans property is changed; a VetoableChange event can also be fired when
a JavaBeans property is changed; and if the listener throws a PropertyVetoException, the property change
should not take effect. A property whose setter fires PropertyChange events is called a bound property.
A property whose setter fires VetoableChange events is called a constrained property. Helper classes
PropertyChangeSupport and VetoableChangeSupport allow bound properties and constrained properties to
be easily defined in JavaBean classes.
Listing 3-16 defines a JavaBean Person with three properties: name, address, and phoneNumber. The
address property is a bound property, and the phoneNumber property is a constrained property.
Listing 3-16. Person.java
import
import
import
import
import
java.beans.PropertyChangeListener;
java.beans.PropertyChangeSupport;
java.beans.PropertyVetoException;
java.beans.VetoableChangeListener;
java.beans.VetoableChangeSupport;
public class Person {
private PropertyChangeSupport propertyChangeSupport;
private VetoableChangeSupport vetoableChangeSupport;
private String name;
private String address;
private String phoneNumber;
public Person() {
propertyChangeSupport = new PropertyChangeSupport(this);
vetoableChangeSupport = new VetoableChangeSupport(this);
}
public String getName() {
return name;
}
122
Chapter 3 ■ Properties and Bindings
public void setName(String name) {
this.name = name;
}
public String getAddress() {
return address;
}
public void setAddress(String address) {
String oldAddress = this.address;
this.address = address;
propertyChangeSupport.firePropertyChange("address", oldAddress, this.address);
}
public String getPhoneNumber() {
return phoneNumber;
}
public void setPhoneNumber(String phoneNumber) throws PropertyVetoException {
String oldPhoneNumber = this.phoneNumber;
vetoableChangeSupport.fireVetoableChange("phoneNumber", oldPhoneNumber,
phoneNumber);
this.phoneNumber = phoneNumber;
propertyChangeSupport.firePropertyChange("phoneNumber", oldPhoneNumber, this.
phoneNumber);
}
public void addPropertyChangeListener(PropertyChangeListener l) {
propertyChangeSupport.addPropertyChangeListener(l);
}
public void removePropertyChangeListener(PropertyChangeListener l) {
propertyChangeSupport.removePropertyChangeListener(l);
}
public PropertyChangeListener[] getPropertyChangeListeners() {
return propertyChangeSupport.getPropertyChangeListeners();
}
public void addVetoableChangeListener(VetoableChangeListener l) {
vetoableChangeSupport.addVetoableChangeListener(l);
}
public void removeVetoableChangeListener(VetoableChangeListener l) {
vetoableChangeSupport.removeVetoableChangeListener(l);
}
public VetoableChangeListener[] getVetoableChangeListeners() {
return vetoableChangeSupport.getVetoableChangeListeners();
}
}
123
Chapter 3 ■ Properties and Bindings
Understanding the JavaFX Property Adapters
The interfaces and classes in the javafx.beans.property.adapter package can be used to easily adapt
JavaBeans properties to JavaFX properties. The ReadOnlyJavaBeanProperty interface is a subinterface of
ReadOnlyProperty, and adds two methods:
void dispose()
void fireValueChangedEvent()
The JavaBeanProperty interface extends the ReadOnlyJavaBeanProperty and the Property
interfaces. Each of these two interfaces has concrete class specializations for Boolean, Integer, Long,
Float, Double, Object, and String types. These classes do not have public constructors. Instead,
builder classes are provided to create instances of these types. We use the JavaBeanStringProperty
class in the following example code. The same pattern applies to all other JavaFX property adapters. The
JavaBeanStringPropertyBuilder supports the following methods:
public
public
public
public
public
public
public
public
public
static JavaBeanStringPropertyBuilder create()
JavaBeanStringProperty build()
JavaBeanStringPropertyBuilder name(java.lang.String)
JavaBeanStringPropertyBuilder bean(java.lang.Object)
JavaBeanStringPropertyBuilder beanClass(java.lang.Class)
JavaBeanStringPropertyBuilder getter(java.lang.String)
JavaBeanStringPropertyBuilder setter(java.lang.String)
JavaBeanStringPropertyBuilder getter(java.lang.reflect.Method)
JavaBeanStringPropertyBuilder setter(java.lang.reflect.Method)
To use the builder, start by calling its static method create(). Then call a chain of the methods that
returns the builder itself. Finally, the build() method is called to create the property. For most cases, it
suffices to call the bean() and the name() methods to specify the JavaBean instance and the name of the
property. The getter() and setter() methods can be used to specify a getter and setter that does not follow
the naming convention. The beanClass() method can be used to specify the JavaBean class. Setting the
JavaBean class up front on the builder allows you to more efficiently create adapters for the same JavaBeans
property for multiple instances of the same JavaBean class.
■■Note Although the builders of the JavaFX scene, control, and so on, classes have been deprecated, the
builders in the javafx.beans.property.adapter package have not been deprecated. They are required to
generate the JavaBeans property adapters.
The program in Listing 3-17 illustrates the adaption of the three JavaBeans properties of the Person
class into JavaBeanStringProperty objects.
Listing 3-17. JavaBeanPropertiesExamples.java
import javafx.beans.property.SimpleStringProperty;
import javafx.beans.property.adapter.JavaBeanStringProperty;
import javafx.beans.property.adapter.JavaBeanStringPropertyBuilder;
import java.beans.PropertyVetoException;
124
Chapter 3 ■ Properties and Bindings
public class JavaBeanPropertiesExample {
public static void main(String[] args) throws NoSuchMethodException {
adaptJavaBeansProperty();
adaptBoundProperty();
adaptConstrainedProperty();
}
private static void adaptJavaBeansProperty() throws NoSuchMethodException {
Person person = new Person();
JavaBeanStringProperty nameProperty = JavaBeanStringPropertyBuilder.create()
.bean(person)
.name("name")
.build();
nameProperty.addListener((observable, oldValue, newValue) -> {
System.out.println("JavaFX property " + observable + " changed:");
System.out.println("\toldValue = " + oldValue + ", newValue = " + newValue);
});
System.out.println("Setting name on the JavaBeans property");
person.setName("Stephen Chin");
System.out.println("Calling fireValueChange");
nameProperty.fireValueChangedEvent();
System.out.println("nameProperty.get() = " + nameProperty.get());
System.out.println("Setting value on the JavaFX property");
nameProperty.set("Johan Vos");
System.out.println("person.getName() = " + person.getName());
}
private static void adaptBoundProperty() throws NoSuchMethodException {
System.out.println();
Person person = new Person();
JavaBeanStringProperty addressProperty = JavaBeanStringPropertyBuilder.create()
.bean(person)
.name("address")
.build();
addressProperty.addListener((observable, oldValue, newValue) -> {
System.out.println("JavaFX property " + observable + " changed:");
System.out.println("\toldValue = " + oldValue + ", newValue = " + newValue);
});
System.out.println("Setting address on the JavaBeans property");
person.setAddress("12345 Main Street");
}
private static void adaptConstrainedProperty() throws NoSuchMethodException {
System.out.println();
Person person = new Person();
JavaBeanStringProperty phoneNumberProperty = JavaBeanStringPropertyBuilder.create()
.bean(person)
.name("phoneNumber")
.build();
125
Chapter 3 ■ Properties and Bindings
phoneNumberProperty.addListener((observable, oldValue, newValue) -> {
System.out.println("JavaFX property " + observable + " changed:");
System.out.println("\toldValue = " + oldValue + ", newValue = " + newValue);
});
System.out.println("Setting phoneNumber on the JavaBeans property");
try {
person.setPhoneNumber("800-555-1212");
} catch (PropertyVetoException e) {
System.out.println("A JavaBeans property change is vetoed.");
}
System.out.println("Bind phoneNumberProperty to another property");
SimpleStringProperty stringProperty = new SimpleStringProperty("866-555-1212");
phoneNumberProperty.bind(stringProperty);
System.out.println("Setting phoneNumber on the JavaBeans property");
try {
person.setPhoneNumber("888-555-1212");
} catch (PropertyVetoException e) {
System.out.println("A JavaBeans property change is vetoed.");
}
System.out.println("person.getPhoneNumber() = " + person.getPhoneNumber());
}
}
In the adaptJavaBeanProperty() method, we instantiated a Person bean and adapted its name
JavaBeans property into a JavaFX JavaBeanStringProperty. To help you understand when a ChangeEvent
is delivered to the nameProperty, we added a ChangeListener (in the form of a lambda expression) to it.
Because name is not a bound property, when we call person.setName(), the nameProperty is not aware of
the change. To notify nameProperty of the change, we call its fireValueChangedEvent() method. When we
call nameProperty.get(), we get the name that we have set on the person bean. Conversely, after we call
nameProperty.set(), a call to person.getName() will return what we have set on nameProperty.
In the adaptBoundProperty() method, we instantiated a Person bean and adapted its address
JavaBeans property into a JavaFX JavaBeanStringProperty. To help you understand when a ChangeEvent
is delivered to the addressProperty, we added a ChangeListener (in the form of a lambda expression) to
it. Because address is a bound property, the addressProperty is registered as a PropertyChangeListener
to the person bean; therefore, when we call person.setAddress(), the addressProperty is notified
immediately without us having to call the fireValuechangedEvent() method.
In the adaptConstrainedProperty() method, we instantiated a Person bean and adapted its
phoneNumber JavaBeans property into a JavaBeanStringProperty. Again we added a ChangeListener
to it. Because phoneNumber is a constrained property, phoneNumberProperty is capable of vetoing
person.setPhoneNumber() calls. When that happens, the person.setPhoneNumber() call throws a
PropertyVetoException. The phoneNumberProperty will veto such a change if it is itself bound to another
JavaFX property. We call person.setPhoneNumber() twice, once before we bind phoneNumberProperty to
another JavaFX property, and once after phoneNumberProperty is bound. The first call succeeds in altering
the value of the phoneNumberProperty, and the second call throws a PropertyVetoException.
126
Chapter 3 ■ Properties and Bindings
When we run the program in Listing 3-17, the following output is printed to the console:
Setting name on the JavaBeans property
Calling fireValueChange
JavaFX property StringProperty [bean: Person@776ec8df, name: name, value: Stephen Chin] changed:
oldValue = null, newValue = Stephen Chin
nameProperty.get() = Stephen Chin
Setting value on the JavaFX property
JavaFX property StringProperty [bean: Person@776ec8df, name: name, value: Johan Vos] changed:
oldValue = Stephen Chin, newValue = Johan Vos
person.getName() = Johan Vos
Setting address on the JavaBeans property
JavaFX property StringProperty [bean: Person@41629346, name: address, value: 12345 main
Street] changed:
oldValue = null, newValue = 12345 main Street
Setting phoneNumber on the JavaBeans property
JavaFX property StringProperty [bean: Person@6d311334, name: phoneNumber, value: 800-5551212] changed:
oldValue = null, newValue = 800-555-1212
Bind phoneNumberProperty to another property
JavaFX property StringProperty [bean: Person@6d311334, name: phoneNumber, value: 866-5551212] changed:
oldValue = 800-555-1212, newValue = 866-555-1212
Setting phoneNumber on the JavaBeans property
A JavaBeans property change is vetoed.
person.getPhoneNumber() = 866-555-1212
Summary
In this chapter, you learned the fundamentals of the JavaFX properties and bindings framework, and the
JavaFX Beans specification. You should now understand the following important principles.
•
JavaFX properties and bindings are the fundamental workhorses of the framework.
•
They conform to the key interfaces of the framework.
•
They fire two kinds of events: an invalidation event and a change event.
•
All properties and bindings provided by the framework recalculate their values
lazily—only when a value is requested. To force them into eager reevaluation, a
ChangeListener needs to be attached.
•
New bindings are created out of existing properties and bindings in one of three
ways: using the factory methods of the Bindings utility class, using the fluent
interface API, or directly extending the IntegerBinding series of abstract classes.
•
The JavaFX Beans specification uses three methods to define a property: the getter,
the setter, and the property getter.
127
Chapter 3 ■ Properties and Bindings
•
JavaFX Beans properties can be implemented through the eager, half-lazy, and
full-lazy strategies.
•
Old-style JavaBeans properties can be adapted easily to JavaFX properties.
Resources
The following are useful resources on properties and bindings.
128
•
Martin Fowler’s write-up on fluent interface APIs: www.martinfowler.com/bliki/
FluentInterface.html
•
The Properties and Binding tutorial at Oracle’s JavaFX.com: http://docs.oracle.
com/javase/8/javafx/properties-binding-tutorial/
•
Michael Heinrichs’s blog includes entries on JavaFX properties and bindings:
http://blog.netopyr.com/
CHAPTER 4
Using Scene Builder to Create a
User Interface
Give me a lever long enough and a fulcrum on which to place it, and I shall move the
world.
—Archimedes
In Chapter 2, you learned about the two ways of creating a JavaFX UI, programmatically and declaratively,
and how to programmatically create a UI using the JavaFX APIs. You are familiar with the theater metaphor
of the JavaFX UI, with the Stage representing a window in a Windows, Mac, or Linux program, or the touch
screen in a mobile device, the Scene and the Nodes it contains representing the content of the UI. In this
chapter, we tackle the other side of the UI story in JavaFX: the declarative creation of UIs.
At the center of this approach of UI design is the FXML file. It is an XML file format designed specifically
to hold information about UI elements. It contains the “what” of the UI elements, but not the “how.” This is
why this method of creating JavaFX UIs is called declarative. At its core, FXML is a Java object serialization
format that can be used for any Java classes written in a certain way, including all old-style JavaBeans. In
practice, however, it is only used for specifying JavaFX UIs.
Aside from direct editing in a text editor or your favorite Java integrated development environment
(IDE), FXML files can also be manipulated by a graphical tool designed for working with FXML files called
JavaFX Scene Builder. JavaFX Scene Builder 1.0 was released in August 2012, and JavaFX Scene Builder 1.1
was released in September 2013. Both 1.0 and 1.1 work with JavaFX 2. JavaFX Scene Builder 2.0 was released
in May 2014 and works with JavaFX 8. The JavaFX Scene Builder 2.0 code base is released as open source,
and while the Oracle JavaFX team is still contributing to it, the development and release of Scene Builder is
now coordinated by Gluon.
Gluon merges contributions from Oracle, Gluon engineers and community contributors, and maintains
a public code repository and an issue tracker. Also, Gluon creates binary releases for Windows, Mac, and
Linux. All information on Scene Builder, including how to download and install, is now maintained at
http://gluonhq.com/products/scene-builder/.
JavaFX Scene Builder is a fully graphical tool that allows you to paint the screens of your UI out of a
palette of available containers, controls, and other visual nodes, and lay them out by direct manipulation on
the screen and modification of their properties through property editors.
FXML files are loaded into JavaFX applications by the JavaFX runtime using the FXMLLoader class. The
result of loading an FXML file is always a Java object, usually a container Node such as a Group or a Pane.
This object can be used as the root in a Scene, or attached to a bigger programmatically created scene graph
as a node. To the rest of the JavaFX application, the nodes loaded from an FXML file are no different from
programmatically constructed nodes.
© Johan Vos, Stephen Chin, Weiqi Gao, James Weaver, and Dean Iverson 2018
J. Vos et al., Pro JavaFX 9, https://doi.org/10.1007/978-1-4842-3042-8_4
129
Chapter 4 ■ Using Scene Builder to Create a User Interface
We present the intricately related materials about the content and format of FXML files, how they
are loaded at runtime, and how they are fashioned at design time, in a spiraling progression. We start this
chapter with a complete example showing how the StageCoach program in Listing 2-1 from Chapter 2 can
be done using FXML. We then present the FXML loading facility in detail. We then present a series of small
handcrafted FXML files that highlight all the features of the FXML file format. Once you understand the
FXML file format, we show you how to create these FXML files using JavaFX Scene Builder, covering all the
features of JavaFX Scene Builder 2.0.
■■Note
You will need to download and install Gluon’s open source JavaFX Scene Builder 9.0 from
http://gluonhq.com/products/scene-builder/ to go through the examples in this chapter. We also highly
recommend configuring your favorite IDE to use JavaFX Scene Builder 9.0 to edit FXML files. NetBeans and
IntelliJ IDEA come bundled with JavaFX support. Eclipse users can install the e(fx)clipse plug-in. Once configured,
you can right-click any FXML files in your projects in your IDE and select the “Edit with Scene Builder” context
menu item. Of course, you can also use your IDE’s XML file editing capabilities to edit FXML files as XML files.
Setting the Stage with FXML
The process of converting the StageCoach program in Chapter 2 from using a programmatically created UI
to using a declaratively created UI is straightforward.
Creating a User Interface Graphically with JavaFX Scene Builder
We first created an FXML file that represented the root node of the scene with JavaFX Scene Builder.
Figure 4-1 shows a screenshot as this UI is being created.
Figure 4-1. StageCoach.fxml being created in JavaFX Scene Builder
130
Chapter 4 ■ Using Scene Builder to Create a User Interface
We will go into details of how to use JavaFX Scene Builder in the latter half of this chapter. For now,
simply observe the major functional areas of the tool. In the middle is the Content panel showing the look
of the UI being worked on. On the left side are the Library panel at the top, which includes all the possible
nodes that can be used in the Content panel divided into neat subsets such as Containers, Controls, Shapes,
Charts, and so on, and the Document panel below, which shows the scene graph that is being worked on in
the Content panel as a tree structure called the Hierarchy, and the Controller that provides event handler
code for the various controls in the UI. On the right side is the Inspector area that has subareas that allow
you to manipulate Properties, Layout, and Code hookup of the currently selected control.
Understanding the FXML File
Listing 4-1 shows the FXML file that is saved by JavaFX Scene Builder from the UI we have created.
Listing 4-1. StageCoach.fxml
■■Note The FXML file created by JavaFX Scene Builder has longer lines. We reformatted the FXML file to fit
the page of the book.
Most of this FXML file can be understood intuitively: It represents a Group holding two children, a
Rectangle and a VBox. The VBox in turn holds five Text nodes, two CheckBoxes, an HBox, and three Buttons.
The HBox holds a Label and a TextField. Various properties of these nodes are set to some sensible values;
for example, the text on the three Buttons is set to "toBack()", "toFront()" and "close()".
Some of the constructs in this FXML file need a little bit more explanation. The XML processing
instructions at the top of the file
javafx.scene.control.CheckBox?>
javafx.scene.control.Label?>
javafx.scene.control.TextField?>
javafx.scene.Group?>
javafx.scene.layout.HBox?>
javafx.scene.layout.VBox?>
javafx.scene.shape.Rectangle?>
javafx.scene.text.Text?>
inform the consumer of this file, either JavaFX Scene Builder at design time or FXMLLoader at runtime,
to import the mentioned Java classes. These have the same effect as import directives in Java source files.
Two namespace declarations are provided for the top-level element Group. JavaFX Scene Builder puts
these namespaces in every FXML file it creates:
xmlns="http://javafx.com/javafx/8"
xmlns:fx="http://javafx.com/fxml/1"
■■Caution The FXML file is not validated against any XML schemas. The namespaces specified here are
used by the FXMLLoader, JavaFX Scene Builder, and Java IDEs such as NetBeans, Eclipse, and IntelliJ IDEA to
provide assistance when editing FXML files. The actual prefix, empty string for the first namespace and “fx” for
the second namespace, should not be altered.
This FXML file contains two kinds of attributes with the fx prefix, fx:controller and fx:id. The
fx:controller attribute appears on the top-level element Group. It informs the JavaFX runtime that the UI
designed in the current FXML file is meant to work together with a Java class called its controller:
fx:controller="projavafx.stagecoach.ui.StageCoachController"
133
Chapter 4 ■ Using Scene Builder to Create a User Interface
The preceding attribute declares that StageCoach.fxml will work together with the Java class
projavafx.stagecoach.ui.StageCoachController. The fx:id attribute can appear in every element that
represents a JavaFX Node. The value of fx:id is the name of a field in the controller that represents the Node
after the FXML file has been loaded. The StageCoach.fxml file declares the following fx:ids (only lines with
fx:id attribute are shown):