Summary

Update the API specification for Window and Stage to indicate that some properties are controlled by the platform; values set by the application might be ignored on some platforms.

Problem

Several properties of a Window can be set programmatically, but are ultimately under control of the platform. Such properties include a window's position on the screen, its size, its stacking order relative to other windows, and whether or not the window is iconified or maximized. Many platforms have a window system that allows these properties to be specified by the program, but then allows the end-user to alter them.

The API specification for the Window and Stage classes doesn't clearly indicate which properties might be ignored or treated as hints.

By way of example, a window's initial position and size can be specified, but the end-user can later drag or resize the window, which will affect the values of these properties. A tiling window manager might even move and resize a window from its initial position and size in order to not overlap another window. Similarly, the stacking order and whether or not a window is iconified or maximized can be altered by the end-user. Some systems (e.g., mobile or embedded systems), have a fixed position and size that can't be changed by the application at all.

Solution

Update the API specification for the Window and Stage classes to clarify that the values for some properties and methods can be changed or ignored by the platform. Several of the properties already have a comment to the effect that the value can change externally, and thus the properties are not bindable, but this should be clarified further and for all such properties and methods.

Specification

javafx.stage.Stage

  * <p>
- * Many of the {@code Stage} properties are read only because they can
- * be changed externally by the underlying platform and therefore must
- * not be bindable.
+ * Some {@code Stage} properties are read-only, even though they have
+ * corresponding set methods, because they can be changed externally by the
+ * underlying platform, and therefore must not be bindable.
+ * Further, these properties might be ignored on some platforms, depending on
+ * whether or not there is a window manager and how it is configured.
+ * For example, a platform without a window manager might ignore the
+ * {@code iconified} property.
  * </p>
 ...
  */
 public class Stage extends Window {

      * <p>
-     * The property is read only because it can be changed externally
-     * by the underlying platform and therefore must not be bindable.
+     * This property is read-only because it can be changed externally
+     * by the underlying platform.
+     * Further, setting this property might be ignored on some platforms.
      * </p>
 ...
     private ReadOnlyBooleanWrapper fullScreen;
     public final void setFullScreen(boolean value)
     public final boolean isFullScreen()
     public final ReadOnlyBooleanProperty fullScreenProperty()

      * <p>
-     * The property is read only because it can be changed externally
-     * by the underlying platform and therefore must not be bindable.
+     * This property is read-only because it can be changed externally
+     * by the underlying platform.
+     * Further, setting this property might be ignored on some platforms.
      * </p>
      *
      * @defaultValue false
      */
     private ReadOnlyBooleanWrapper iconified;
     public final void setIconified(boolean value)
     public final boolean isIconified()
     public final ReadOnlyBooleanProperty iconifiedProperty()

      * <p>
-     * The property is read only because it can be changed externally
-     * by the underlying platform and therefore must not be bindable.
+     * This property is read-only because it can be changed externally
+     * by the underlying platform.
+     * Further, setting this property might be ignored on some platforms.
      * </p>
      *
      * @defaultValue false
      * @since JavaFX 8.0
      */
     private ReadOnlyBooleanWrapper maximized;
     public final void setMaximized(boolean value)
     public final boolean isMaximized()
     public final ReadOnlyBooleanProperty maximizedProperty()

      * <p>
-     * The property is read only because it can be changed externally
-     * by the underlying platform and therefore must not be bindable.
+     * This property is read-only because it can be changed externally
+     * by the underlying platform.
+     * Further, setting this property might be ignored on some platforms.
      * </p>
      *
      * @defaultValue false
      * @since JavaFX 8u20
      */
     private ReadOnlyBooleanWrapper alwaysOnTop;
     public final void setAlwaysOnTop(boolean value)
     public final boolean isAlwaysOnTop()
     public final ReadOnlyBooleanProperty alwaysOnTopProperty()

     /**
-     * Bring the {@code Window} to the foreground.  If the {@code Window} is
-     * already in the foreground there is no visible difference.
+     * Brings this {@code Stage} to the front if the stage is visible.
+     * This action places this {@code Stage} at the top of the stacking
+     * order and shows it in front of any other {@code Stage} created by this
+     * application.
+     * <p>
+     * Some platforms do not allow applications to control the stacking order
+     * at all, in which case this method does nothing.
+     * Other platforms have restrictions on stacking order, so might not
+     * place a window above another application's windows
+     * nor allow a window that owns other windows to appear on top of those
+     * owned windows.
+     * Every attempt will be made to move this {@code Stage} as high as
+     * possible in the stacking order; however, developers should not assume
+     * that this method will move this {@code Stage} above all other windows
+     * in every situation.
+     * </p>
      */
     public void toFront()

     /**
-     * Send the {@code Window} to the background.  If the {@code Window} is
-     * already in the background there is no visible difference.  This action
-     * places this {@code Window} at the bottom of the stacking order on
-     * platforms that support stacking.
+     * Sends this {@code Stage} to the back if the stage is visible.
+     * This action places this {@code Stage} at the bottom of the stacking
+     * order and shows it behind any other {@code Stage} created by this
+     * application.
+     * <p>
+     * Some platforms do not allow applications to control the stacking order
+     * at all, in which case this method does nothing.
+     * Other platforms have restrictions on stacking order, so might not
+     * place a window below another application's windows
+     * nor allow a window that is owned by another window to appear below their
+     * owner.
+     * Every attempt will be made to move this {@code Stage} as low as
+     * possible in the stacking order; however, developers should not assume
+     * that this method will move this {@code Stage} below all other windows
+     * in every situation.
+     * </p>
      */
     public void toBack()

javafx.stage.Window

+ * <p>
+ * Some {@code Window} properties are read-only, even though they have
+ * corresponding set methods, because they can be changed externally by the
+ * underlying platform, and therefore must not be bindable.
+ * Further, these properties might be ignored on some platforms, depending on
+ * whether or not there is a window manager and how it is configured.
+ * For example, a tiling window manager might ignore the {@code x} and {@code y}
+ * properties, or treat them as hints, placing the window in a location of its
+ * choosing.
+ * </p>
  *
  * @since JavaFX 2.0
  */
 public class Window implements EventTarget {

+     * <p>
+     * This property is read-only because it can be changed externally
+     * by the underlying platform.
+     * Further, setting this property might be ignored on some platforms.
+     * </p>
      */
     private ReadOnlyDoubleWrapper x
     public final void setX(double value)
     public final double getX()
     public final ReadOnlyDoubleProperty xProperty()

+     * <p>
+     * This property is read-only because it can be changed externally
+     * by the underlying platform.
+     * Further, setting this property might be ignored on some platforms.
+     * </p>
      */
     private ReadOnlyDoubleWrapper y
     public final void setY(double value)
     public final double getY()
     public final ReadOnlyDoubleProperty yProperty()

      * <p>
-     * The property is read only because it can be changed externally
-     * by the underlying platform and therefore must not be bindable.
+     * This property is read-only because it can be changed externally
+     * by the underlying platform.
+     * Further, setting this property might be ignored on some platforms.
      * </p>
      */
     private ReadOnlyDoubleWrapper width =
     public final void setWidth(double value)
     public final double getWidth()
     public final ReadOnlyDoubleProperty widthProperty()

      * <p>
-     * The property is read only because it can be changed externally
-     * by the underlying platform and therefore must not be bindable.
+     * This property is read-only because it can be changed externally
+     * by the underlying platform.
+     * Further, setting this property might be ignored on some platforms.
      * </p>
      */
     private ReadOnlyDoubleWrapper height
     public final void setHeight(double value)
     public final double getHeight()
     public final ReadOnlyDoubleProperty heightProperty()

-     * <p>
-     * The property is read only because it can be changed externally
-     * by the underlying platform and therefore must not be bindable.
-     * </p>
      */
     private ReadOnlyBooleanWrapper focused
     final void setFocused(boolean value)