public class Stage extends Window
Stage
class is the top level JavaFX container.
The primary Stage is constructed by the platform. Additional Stage
objects may be constructed by the application.
Stage objects must be constructed and modified on the JavaFX Application Thread.
Many of the Stage
properties are read only because they can
be changed externally by the underlying platform and therefore must
not be bindable.
Style
A stage has one of the following styles:
StageStyle.DECORATED
- a stage with a solid white background and
platform decorations.StageStyle.UNDECORATED
- a stage with a solid white background
and no decorations.StageStyle.TRANSPARENT
- a stage with a transparent background
and no decorations.StageStyle.UTILITY
- a stage with a solid white background and
minimal platform decorations.The style must be initialized before the stage is made visible.
On some platforms decorations might not be available. For example, on some mobile or embedded devices. In these cases a request for a DECORATED or UTILITY window will be accepted, but no decorations will be shown.
Owner
A stage can optionally have an owner Window. When a window is a stage's owner, it is said to be the parent of that stage.
Owned Stages are tied to the parent Window. An owned stage will always be on top of its parent window. When a parent window is closed or iconified, then all owned windows will be affected as well. Owned Stages cannot be independantly iconified.
The owner must be initialized before the stage is made visible.
Modality
A stage has one of the following modalities:
Modality.NONE
- a stage that does not block any other window.Modality.WINDOW_MODAL
- a stage that blocks input events from
being delivered to all windows from its owner (parent) to its root.
Its root is the closest ancestor window without an owner.Modality.APPLICATION_MODAL
- a stage that blocks input events from
being delivered to all windows from the same application, except for those
from its child hierarchy.When a window is blocked by a modal stage its Z-order relative to its ancestors
is preserved, and it receives no input events and no window activation events,
but continues to animate and render normally.
Note that showing a modal stage does not necessarily block the caller. The
show()
method returns immediately regardless of the modality of the stage.
Use the showAndWait()
method if you need to block the caller until
the modal stage is hidden (closed).
The modality must be initialized before the stage is made visible.
Example:
import javafx.application.Application;
import javafx.scene.Group;
import javafx.scene.Scene;
import javafx.scene.text.Font;
import javafx.scene.text.Text;
import javafx.stage.Stage;
public class HelloWorld extends Application {
@Override public void start(Stage stage) {
Text text = new Text(10, 40, "Hello World!");
text.setFont(new Font(40));
Scene scene = new Scene(new Group(text));
stage.setTitle("Welcome to JavaFX!");
stage.setScene(scene);
stage.sizeToScene();
stage.show();
}
public static void main(String[] args) {
Application.launch(args);
}
}
produces the following on Windows:
produces the following on Mac OSX:
produces the following on Linux:
Modifier and Type | Class and Description |
---|---|
private class |
Stage.ResizableProperty |
Modifier and Type | Field and Description |
---|---|
private ReadOnlyBooleanWrapper |
alwaysOnTop
Defines whether this
Stage is kept on top of other windows. |
private ReadOnlyBooleanWrapper |
fullScreen
Specifies whether this
Stage should be a full-screen,
undecorated window. |
private ObjectProperty<KeyCombination> |
fullScreenExitCombination |
private ObjectProperty<java.lang.String> |
fullScreenExitHint |
private ReadOnlyBooleanWrapper |
iconified
Defines whether the
Stage is iconified or not. |
private ObservableList<Image> |
icons
Defines the icon images to be used in the window decorations and when
minimized.
|
private boolean |
important |
private boolean |
inNestedEventLoop |
private DoubleProperty |
maxHeight
Defines the maximum height of this
Stage . |
private ReadOnlyBooleanWrapper |
maximized
Defines whether the
Stage is maximized or not. |
private DoubleProperty |
maxWidth
Defines the maximum width of this
Stage . |
private DoubleProperty |
minHeight
Defines the minimum height of this
Stage . |
private DoubleProperty |
minWidth
Defines the minimum width of this
Stage . |
private Modality |
modality |
private Window |
owner |
private boolean |
primary |
private BooleanProperty |
resizable
Defines whether the
Stage is resizable or not by the user. |
private boolean |
securityDialog |
private static StagePeerListener.StageAccessor |
STAGE_ACCESSOR |
private static ObservableList<Stage> |
stages |
private StageStyle |
style |
private StringProperty |
title
Defines the title of the
Stage . |
acc, hasBeenVisible, impl_peer, peerListener
Constructor and Description |
---|
Stage()
Creates a new instance of decorated
Stage . |
Stage(StageStyle style)
Creates a new instance of
Stage . |
Modifier and Type | Method and Description |
---|---|
ReadOnlyBooleanProperty |
alwaysOnTopProperty() |
private ReadOnlyBooleanWrapper |
alwaysOnTopPropertyImpl() |
void |
close()
Closes this
Stage . |
ObjectProperty<java.lang.String> |
fullScreenExitHintProperty() |
ObjectProperty<KeyCombination> |
fullScreenExitKeyProperty()
Get the property for the Full Screen exit key combination.
|
ReadOnlyBooleanProperty |
fullScreenProperty() |
private ReadOnlyBooleanWrapper |
fullScreenPropertyImpl() |
java.lang.String |
getFullScreenExitHint() |
KeyCombination |
getFullScreenExitKeyCombination()
Get the current sequence used to exit Full Screen mode.
|
ObservableList<Image> |
getIcons()
Gets the icon images to be used in the window decorations and when
minimized.
|
double |
getMaxHeight() |
double |
getMaxWidth() |
double |
getMinHeight() |
double |
getMinWidth() |
Modality |
getModality()
Retrieves the modality attribute for this stage.
|
Window |
getOwner()
Retrieves the owner Window for this stage, or null for an unowned stage.
|
StageStyle |
getStyle()
Retrieves the style attribute for this stage.
|
java.lang.String |
getTitle() |
(package private) Window |
getWindowOwner() |
ReadOnlyBooleanProperty |
iconifiedProperty() |
private ReadOnlyBooleanWrapper |
iconifiedPropertyImpl() |
java.lang.String |
impl_getMXWindowType()
Deprecated.
This is an internal API that is not intended for use and will be removed in the next version
|
void |
impl_setImportant(boolean important)
Deprecated.
This is an internal API that is not intended for use and will be removed in the next version
|
void |
impl_setPrimary(boolean primary)
Deprecated.
This is an internal API that is not intended for use and will be removed in the next version
|
protected void |
impl_visibleChanged(boolean value)
Deprecated.
This is an internal API that is not intended for use and will be removed in the next version
|
protected void |
impl_visibleChanging(boolean value)
Deprecated.
This is an internal API that is not intended for use and will be removed in the next version
|
void |
initModality(Modality modality)
Specifies the modality for this stage.
|
void |
initOwner(Window owner)
Specifies the owner Window for this stage, or null for a top-level,
unowned stage.
|
(package private) void |
initSecurityDialog(boolean securityDialog)
Sets a flag indicating that this stage is used for a security dialog and
must always be on top.
|
void |
initStyle(StageStyle style)
Specifies the style for this stage.
|
boolean |
isAlwaysOnTop() |
boolean |
isFullScreen() |
boolean |
isIconified() |
private boolean |
isImportant() |
boolean |
isMaximized() |
(package private) boolean |
isPrimary()
Returns whether this stage is the primary stage.
|
boolean |
isResizable() |
(package private) boolean |
isSecurityDialog()
Returns the state of the securityDialog flag.
|
DoubleProperty |
maxHeightProperty() |
ReadOnlyBooleanProperty |
maximizedProperty() |
private ReadOnlyBooleanWrapper |
maximizedPropertyImpl() |
DoubleProperty |
maxWidthProperty() |
DoubleProperty |
minHeightProperty() |
DoubleProperty |
minWidthProperty() |
BooleanProperty |
resizableProperty() |
void |
setAlwaysOnTop(boolean value) |
void |
setFullScreen(boolean value) |
void |
setFullScreenExitHint(java.lang.String value)
Specifies the text to show when a user enters full screen mode, usually
used to indicate the way a user should go about exiting out of full
screen mode.
|
void |
setFullScreenExitKeyCombination(KeyCombination keyCombination)
Specifies the KeyCombination that will allow the user to exit full screen
mode.
|
void |
setIconified(boolean value) |
void |
setMaxHeight(double value) |
void |
setMaximized(boolean value) |
void |
setMaxWidth(double value) |
void |
setMinHeight(double value) |
void |
setMinWidth(double value) |
void |
setResizable(boolean value) |
void |
setScene(Scene value)
Specify the scene to be used on this stage.
|
void |
setTitle(java.lang.String value) |
void |
show()
Attempts to show this Window by setting visibility to true
|
void |
showAndWait()
Shows this stage and waits for it to be hidden (closed) before returning
to the caller.
|
StringProperty |
titleProperty() |
void |
toBack()
Send the
Window to the background. |
void |
toFront()
Bring the
Window to the foreground. |
addEventFilter, addEventHandler, applyBounds, buildEventDispatchChain, centerOnScreen, createInternalEventDispatcher, decreaseFocusGrabCounter, eventDispatcherProperty, fireEvent, focusedProperty, getEventDispatcher, getHeight, getInternalEventDispatcher, getOnCloseRequest, getOnHidden, getOnHiding, getOnShowing, getOnShown, getOpacity, getProperties, getScene, getUserData, getWidth, getX, getY, hasProperties, heightProperty, hide, impl_getPeer, impl_getWindows, increaseFocusGrabCounter, isFocused, isShowing, notifyLocationChanged, notifySizeChanged, onCloseRequestProperty, onHiddenProperty, onHidingProperty, onShowingProperty, onShownProperty, opacityProperty, removeEventFilter, removeEventHandler, requestFocus, sceneProperty, setEventDispatcher, setEventHandler, setFocused, setHeight, setOnCloseRequest, setOnHidden, setOnHiding, setOnShowing, setOnShown, setOpacity, setUserData, setWidth, setX, setXInternal, setY, setYInternal, showingProperty, sizeToScene, widthProperty, xProperty, yProperty
private boolean inNestedEventLoop
private static ObservableList<Stage> stages
private static final StagePeerListener.StageAccessor STAGE_ACCESSOR
private boolean primary
private boolean securityDialog
private boolean important
private StageStyle style
private Modality modality
private Window owner
private ReadOnlyBooleanWrapper fullScreen
Stage
should be a full-screen,
undecorated window.
The implementation of full-screen mode is platform and profile-dependent.
When set to true
, the Stage
will attempt to enter
full-screen mode when visible. Set to false
to return Stage
to windowed mode.
An IllegalStateException
is thrown if this property is set
on a thread other than the JavaFX Application Thread.
The full-screen mode will be exited (and the fullScreen
attribute
will be set to false
) if the full-screen
Stage
loses focus or if another Stage
enters
full-screen mode on the same Screen
. Note that a Stage
in full-screen mode can become invisible without losing its
full-screen status and will again enter full-screen mode when the
Stage
becomes visible.
Screen
the Stage will enter full-screen mode on by
setting its position to be within the bounds of that Screen
prior to entering full-screen mode.
However once in full-screen mode, Stage
's x
, y
,
width
, and height
variables will continue to represent
the non-full-screen position and size of the window; the same for
iconified
, resizable
, style
, and opacity
. If changes are made to any of these attributes while in
full-screen mode, upon exiting full-screen mode the Stage
will
assume those attributes.
In case that more Stage
modes are set simultaneously their order
of importance is iconified
, fullScreen, maximized
(from
strongest to weakest).
The property is read only because it can be changed externally by the underlying platform and therefore must not be bindable.
The user can unconditionally exit full-screen mode at any time by pressingESC
.
There are differences in behavior between applications if a security manager is present. Applications with permissions are allowed to enter full-screen mode unrestricted. Applications without the proper permissions will have the following restrictions:
Node.mousePressed/mouseReleased/mouseClicked
) or keyboard
(Node.keyPressed/keyReleased/keyTyped
) event handlers. It is
not allowed to enter full-screen mode in response to ESC
key. Attempting to enter full-screen mode from any other context will
be ignored.
If Stage
was constructed as full-screen but not visible
it will enter full-screen mode upon becoming visible, with the same
limitations to when this is allowed to happen as when setting
fullScreen
to true
.
UP, DOWN, LEFT, RIGHT, SPACE, TAB, PAGE_UP, PAGE_DOWN, HOME, END, ENTER
private ObservableList<Image> icons
private StringProperty title
Stage
.private ReadOnlyBooleanWrapper iconified
Stage
is iconified or not.
In case that more Stage
modes are set simultaneously their order
of importance is iconified} fullScreen
, maximized
(from
strongest to weakest).
On some mobile and embedded platforms setting this property to true will
hide the Stage
but not show an icon for it.
The property is read only because it can be changed externally by the underlying platform and therefore must not be bindable.
private ReadOnlyBooleanWrapper maximized
Stage
is maximized or not.
In case that more Stage
modes are set simultaneously their order
of importance is iconified
, fullScreen
, maximized (from
strongest to weakest).
The property is read only because it can be changed externally by the underlying platform and therefore must not be bindable.
private ReadOnlyBooleanWrapper alwaysOnTop
Stage
is kept on top of other windows.
If some other window is already always-on-top then the relative order between these windows is unspecified (depends on platform).
There are differences in behavior between applications if a security manager is present. Applications with permissions are allowed to set "always on top" flag on a Stage. In applications without the proper permissions, an attempt to set the flag will be ignored and the property value will be restored to "false".
The property is read only because it can be changed externally by the underlying platform and therefore must not be bindable.
private BooleanProperty resizable
Stage
is resizable or not by the user.
Programatically you may still change the size of the Stage. This is
a hint which allows the implementation to optionally make the Stage
resizable by the user.
Warning: Since 8.0 the property cannot be bound and will throw
RuntimeException
on an attempt to do so. This is because
the setting of resizable is asynchronous on some systems or generally
might be set by the system / window manager.
Bidirectional binds are still allowed, as they don't block setting of the
property by the system.
private DoubleProperty minWidth
Stage
.private DoubleProperty minHeight
Stage
.private DoubleProperty maxWidth
Stage
.private DoubleProperty maxHeight
Stage
.private final ObjectProperty<KeyCombination> fullScreenExitCombination
private final ObjectProperty<java.lang.String> fullScreenExitHint
public Stage()
Stage
.java.lang.IllegalStateException
- if this constructor is called on a thread
other than the JavaFX Application Thread.public Stage(StageStyle style)
Stage
.style
- The style of the Stage
java.lang.IllegalStateException
- if this constructor is called on a thread
other than the JavaFX Application Thread.public final void setScene(Scene value)
public final void show()
Window
final void initSecurityDialog(boolean securityDialog)
securityDialog
- flag indicating that this Stage is being used to
show a security dialog that should be always-on-topjava.lang.IllegalStateException
- if this property is set after the stage
has ever been made visible.final boolean isSecurityDialog()
@Deprecated public void impl_setPrimary(boolean primary)
boolean isPrimary()
@Deprecated public java.lang.String impl_getMXWindowType()
impl_getMXWindowType
in class Window
@Deprecated public void impl_setImportant(boolean important)
private boolean isImportant()
public void showAndWait()
A Stage is hidden (closed) by one of the following means:
Window.hide()
or close()
method on
this stageAfter the Stage is hidden, and the application has returned from the event handler to the event loop, the nested event loop terminates and this method returns to the caller.
For example, consider the following sequence of operations for different event handlers, assumed to execute in the order shown below:
void evtHander1(...) { stage1.showAndWait(); doSomethingAfterStage1Closed(...) } void evtHander2(...) { stage1.hide(); doSomethingElseHere(...) }evtHandler1 will block at the call to showAndWait. It will resume execution after stage1 is hidden and the current event handler, in this case evtHandler2, returns to the event loop. This means that doSomethingElseHere will execute before doSomethingAfterStage1Closed.
More than one stage may be shown with showAndWait. Each call will start a new nested event loop. The stages may be hidden in any order, but a particular nested event loop (and thus the showAndWait method for the associated stage) will only terminate after all inner event loops have also terminated.
For example, consider the following sequence of operations for different event handlers, assumed to execute in the order shown below:
void evtHander1() { stage1.showAndWait(); doSomethingAfterStage1Closed(...) } void evtHander2() { stage2.showAndWait(); doSomethingAfterStage2Closed(...) } void evtHander3() { stage1.hide(); doSomethingElseHere(...) } void evtHander4() { stage2.hide(); doSomethingElseHereToo(...) }evtHandler1 will block at the call to stage1.showAndWait, starting up a nested event loop just like in the previous example. evtHandler2 will then block at the call to stage2.showAndWait, starting up another (inner) nested event loop. The first call to stage1.showAndWait will resume execution after stage1 is hidden, but only after the inner nested event loop started by stage2.showAndWait has terminated. This means that the call to stage1.showAndWait won't return until after evtHandler2 has returned. The order of execution is: stage1.showAndWait, stage2.showAndWait, stage1.hide, doSomethingElseHere, stage2.hide, doSomethingElseHereToo, doSomethingAfterStage2Closed, doSomethingAfterStage1Closed.
This method must not be called on the primary stage or on a stage that
is already visible.
Additionally, it must either be called from an input event handler or
from the run method of a Runnable passed to
Platform.runLater
.
It must not be called during animation or layout processing.
java.lang.IllegalStateException
- if this method is called on a thread
other than the JavaFX Application Thread.java.lang.IllegalStateException
- if this method is called during
animation or layout processing.java.lang.IllegalStateException
- if this method is called on the
primary stage.java.lang.IllegalStateException
- if this stage is already showing.public final void initStyle(StageStyle style)
style
- the style for this stage.java.lang.IllegalStateException
- if this property is set after the stage
has ever been made visible.public final StageStyle getStyle()
public final void initModality(Modality modality)
modality
- the modality for this stage.java.lang.IllegalStateException
- if this property is set after the stage
has ever been made visible.java.lang.IllegalStateException
- if this stage is the primary stage.public final Modality getModality()
public final void initOwner(Window owner)
owner
- the owner for this stage.java.lang.IllegalStateException
- if this property is set after the stage
has ever been made visible.java.lang.IllegalStateException
- if this stage is the primary stage.public final Window getOwner()
public final void setFullScreen(boolean value)
public final boolean isFullScreen()
public final ReadOnlyBooleanProperty fullScreenProperty()
private ReadOnlyBooleanWrapper fullScreenPropertyImpl()
public final ObservableList<Image> getIcons()
public final void setTitle(java.lang.String value)
public final java.lang.String getTitle()
public final StringProperty titleProperty()
public final void setIconified(boolean value)
public final boolean isIconified()
public final ReadOnlyBooleanProperty iconifiedProperty()
private final ReadOnlyBooleanWrapper iconifiedPropertyImpl()
public final void setMaximized(boolean value)
public final boolean isMaximized()
public final ReadOnlyBooleanProperty maximizedProperty()
private final ReadOnlyBooleanWrapper maximizedPropertyImpl()
public final void setAlwaysOnTop(boolean value)
public final boolean isAlwaysOnTop()
public final ReadOnlyBooleanProperty alwaysOnTopProperty()
private ReadOnlyBooleanWrapper alwaysOnTopPropertyImpl()
public final void setResizable(boolean value)
public final boolean isResizable()
public final BooleanProperty resizableProperty()
public final void setMinWidth(double value)
public final double getMinWidth()
public final DoubleProperty minWidthProperty()
public final void setMinHeight(double value)
public final double getMinHeight()
public final DoubleProperty minHeightProperty()
public final void setMaxWidth(double value)
public final double getMaxWidth()
public final DoubleProperty maxWidthProperty()
public final void setMaxHeight(double value)
public final double getMaxHeight()
public final DoubleProperty maxHeightProperty()
@Deprecated protected void impl_visibleChanging(boolean value)
Window
impl_visibleChanging
in class Window
@Deprecated protected void impl_visibleChanged(boolean value)
Window
impl_visibleChanged
in class Window
public void toFront()
Window
to the foreground. If the Window
is
already in the foreground there is no visible difference.public void toBack()
Window
to the background. If the Window
is
already in the background there is no visible difference. This action
places this Window
at the bottom of the stacking order on
platforms that support stacking.public void close()
Stage
.
This call is equivalent to hide()
.Window getWindowOwner()
getWindowOwner
in class Window
public final void setFullScreenExitKeyCombination(KeyCombination keyCombination)
An internal copy of this value is made when entering FullScreen mode and will be used to trigger the exit from the mode. If an application does not have the proper permissions, this setting will be ignored.
keyCombination
- the key combination to exit onpublic final KeyCombination getFullScreenExitKeyCombination()
public final ObjectProperty<KeyCombination> fullScreenExitKeyProperty()
public final void setFullScreenExitHint(java.lang.String value)
If an application does not have the proper permissions, this setting will be ignored.
value
- the string to be displayed.public final java.lang.String getFullScreenExitHint()
public final ObjectProperty<java.lang.String> fullScreenExitHintProperty()