javafx.scene.control.package-info Maven / Gradle / Ivy
/*
* Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* The JavaFX User Interface Controls (UI Controls or just Controls) are
* specialized Nodes in the JavaFX Scenegraph especially suited for reuse in
* many different application contexts. They are designed to be highly
* customizable visually by designers and developers. They are designed to work
* well with layout systems. Examples of prominent controls include {@link javafx.scene.control.Button Button},
* {@link javafx.scene.control.Label Label}, {@link javafx.scene.control.ListView ListView}, and {@link javafx.scene.control.TextField TextField}.
*
* Since Controls are {@link javafx.scene.Node Nodes} in the scenegraph,
* they can be freely mixed with {@link javafx.scene.Group Groups},
* {@link javafx.scene.image.ImageView Images},
* {@link javafx.scene.media.MediaView Media},
* {@link javafx.scene.text.Text Text}, and
* {@link javafx.scene.shape.Shape basic geometric shapes}. While
* writing new UI Controls is not trivial, using and styling them
* is very easy, especially to existing web developers.
*
* The remainder of this document will describe the basic architecture of
* the JavaFX UI Control library, how to style existing controls, write custom
* skins, and how to use controls to build up more complicated user interfaces.
*
*
* Architecture
*
* Controls follow the classic MVC design pattern. The {@link javafx.scene.control.Control Control} is
* the "model". It contains both the state and the functions which manipulate
* that state. The Control class itself does not know how it is rendered or
* what the user interaction is. These tasks are delegated to the
* {@link javafx.scene.control.Skin Skin} ("view"), which may internally separate
* out the view and controller functionality into separate classes, although
* at present there is no public API for the "controller" aspect.
*
* All Controls extend from the Control class, which is in turn a
* {@link javafx.scene.Parent Parent} node, and which is a
* {@link javafx.scene.Node Node}. Every Control has a reference to a single Skin, which
* is the view implementation for the Control. The Control delegates to the
* Skin the responsibility of computing the min, max, and pref sizes of the
* Control, the baseline offset, and hit testing (containment and
* intersection). It is also the responsibility of the Skin, or a delegate of
* the Skin, to implement and repond to all relevant key
* events which occur on the Control when it contains the focus.
*
* Control
*
* Control extends from {@link javafx.scene.Parent Parent}, and as such, is
* not a leaf node. From the perspective of a developer or designer the Control
* can be thought of as if it were a leaf node in many cases. For example, the
* developer or designer can consider a Button as if it were a Rectangle or
* other simple leaf node.
*
* Since a Control is resizable, a Control
* will be auto-sized to its preferred size on each scenegraph
* pulse. Setting the width and height of the Control does not affect its
* preferred size. When used in a layout container, the layout constraints
* imposed upon the Control (or manually specified on the Control) will
* determine how it is positioned and sized.
*
* The Skin of a Control can be changed at any time. Doing so will mark the
* Control as needing to be laid out since changing the Skin likely has changed
* the preferred size of the Control. If no Skin is specified at the time that
* the Control is created, then a default CSS-based skin will be provided for
* all of the built-in Controls.
*
* Each Control may have an optional tooltip specified. The Tooltip is a
* Control which displays some (usually textual) information about the control
* to the user when the mouse hovers over the Control from some period of time.
* It can be styled from CSS the same as with other Controls.
*
* {@code focusTraversable} is overridden in Control to be true by default,
* whereas with Node it is false by default. Controls which should not be
* focusable by default (such as Label) override this to be false.
*
* The getMinWidth, getMinHeight, getPrefWidth, getPrefHeight, getMaxWidth,
* and getMaxHeight functions are delegated directly to the Skin. The
* baselineOffset method is delegated to the node of the skin. It is not
* recommended that subclasses alter these delegations.
*
* Styling Controls
*
* There are two methods for customizing the look of a Control. The most
* difficult and yet most flexible approach is to write a new Skin for the
* Control which precisely implements the visuals which you
* desire for the Control. Consult the Skin documentation for more details.
*
* The easiest and yet very powerful method for styling the built in
* Controls is by using CSS. Please note that in this release the following
* CSS description applies only to the default Skins provided for the built
* in Controls. Subsequent releases will make this generally available for
* any custom third party Controls which desire to take advantage of these
* CSS capabilities.
*
* Each of the default Skins for the built in Controls is comprised of
* multiple individually styleable areas or regions. This is much like an
* HTML page which is made up of {@literal
's} and then styled from
* CSS. Each individual region may be drawn with backgrounds, borders, images,
* padding, margins, and so on. The JavaFX CSS support includes the ability
* to have multiple backgrounds and borders, and to derive colors. These
* capabilities make it extremely easy to alter the look of Controls in
* JavaFX from CSS.
*
* The colors used for drawing the default Skins of the built in Controls
* are all derived from a base color, an accent color and a background
* color. Simply by modifying the base color for a Control you can alter the
* derived gradients and create Buttons or other Controls which visually fit
* in with the default Skins but visually stand out.
*
* As with all other Nodes in the scenegraph, Controls can be styled by
* using an external stylesheet, or by specifying the style directly on the
* Control. Although for examples it is easier to express and understand by
* specifying the style directly on the Node, it is recommended to use an
* external stylesheet and use either the styleClass or id of the Control,
* just as you would use the "class" or id of an HTML element with HTML
* CSS.
*
* Each UI Control specifies a styleClass which may be used to
* style controls from an external stylesheet. For example, the Button
* control is given the "button" CSS style class. The CSS style class names
* are hyphen-separated lower case as opposed to camel case, otherwise, they
* are exactly the same. For example, Button is "button", RadioButton is
* "radio-button", Tooltip is "tooltip" and so on.
*
* The class documentation for each Control defines the default Skin
* regions which can be styled. For further information regarding the CSS
* capabilities provided with JavaFX, see the
* CSS Reference Guide.
*/
package javafx.scene.control;
© 2015 - 2024 Weber Informatics LLC | Privacy Policy