Application (JavaFX 19)
Description: declaration: module: javafx.graphics, package: javafx.application, class: Application

Module javafx.graphics
Package javafx.application

# Class Application

java.lang.Object
javafx.application.Application

Direct Known Subclasses:
  `Preloader`

public abstract class Application extends Object
Application class from which JavaFX applications extend.

Life-cycle

The entry point for JavaFX applications is the Application class. The JavaFX runtime does the following, in order, whenever an application is launched:

1. Starts the JavaFX runtime, if not already started (see `Platform.startup(Runnable)` for more information)
2. Constructs an instance of the specified Application class
3. Calls the `init()` method
4. Calls the `start(javafx.stage.Stage)` method
5. Waits for the application to finish, which happens when either of the following occur:
   - the application calls `Platform.exit()`
   - the last window has been closed and the `implicitExit` attribute on `Platform` is true
6. Calls the `stop()` method

Note that the `start` method is abstract and must be overridden. The `init` and `stop` methods have concrete implementations that do nothing.

The `Application` subclass must be declared public and must have a public no-argument constructor.

Calling `Platform.exit()` is the preferred way to explicitly terminate a JavaFX Application. Directly calling `System.exit(int)` is an acceptable alternative, but doesn't allow the Application `stop()` method to run.

A JavaFX Application should not attempt to use JavaFX after the FX toolkit has terminated or from a ShutdownHook, that is, after the `stop()` method returns or `System.exit(int)` is called.

Note: The JavaFX classes must be loaded from a set of named `javafx.*` modules on the module path. Loading the JavaFX classes from the classpath is not supported. See `Platform.startup` for more information.

Deploying an Application as a Module

If the `Application` subclass is in a named module then that class must be accessible to the `javafx.graphics` module. Otherwise, an exception will be thrown when the application is launched. This means that in addition to the class itself being declared public, the module must `export` (or `open`) the containing package to at least the `javafx.graphics` module.

For example, if `com.foo.MyApplication` is in the `foo.app` module, the `module-info.java` might look like this:

    module foo.app {
        exports com.foo to javafx.graphics;
    }

Parameters

Application parameters are available by calling the `getParameters()` method from the `init()` method, or any time after the `init` method has been called.

Threading

JavaFX creates an application thread for running the application start method, processing input events, and running animation timelines. Creation of JavaFX `Scene` and `Stage` objects as well as modification of scene graph operations to live objects (those objects already attached to a scene) must be done on the JavaFX application thread.

The Java launcher loads and initializes the specified Application class on the JavaFX Application Thread. If there is no main method in the Application class, or if the main method calls Application.launch(), then an instance of the Application is then constructed on the JavaFX Application Thread.

The `init` method is called on the launcher thread, not on the JavaFX Application Thread. This means that an application must not construct a `Scene` or a `Stage` in the `init` method. An application may construct other JavaFX objects in the `init` method.

All the unhandled exceptions on the JavaFX application thread that occur during event dispatching, running animation timelines, or any other code, are forwarded to the thread's `uncaught exception handler`.

Example

The following example will illustrate a simple JavaFX application.

    import javafx.application.Application;
    import javafx.scene.Group;
    import javafx.scene.Scene;
    import javafx.scene.shape.Circle;
    import javafx.stage.Stage;

    public class MyApp extends Application {
        public void start(Stage stage) {
            Circle circ = new Circle(40, 40, 30);
            Group root = new Group(circ);
            Scene scene = new Scene(root, 400, 300);

            stage.setTitle("My JavaFX Application");
            stage.setScene(scene);
            stage.show();
        }
    }

The above example will produce the following:

Since:
  JavaFX 2.0
See Also:
  - `Platform`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `Application.Parameters`
  Encapsulates the set of parameters for an application.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `STYLESHEET_CASPIAN`
  Constant for user agent stylesheet for the "Caspian" theme.
  `static final String`
  `STYLESHEET_MODENA`
  Constant for user agent stylesheet for the "Modena" theme.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Application()`
  Constructs a new `Application` instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final HostServices`
  `getHostServices()`
  Gets the HostServices provider for this application.
  `final Application.Parameters`
  `getParameters()`
  Retrieves the parameters for this Application, including any arguments passed on the command line.
  `static String`
  `getUserAgentStylesheet()`
  Get the user agent stylesheet used by the whole application.
  `void`
  `init()`
  The application initialization method.
  `static void`
  `launch(Class<? extends Application> appClass, String... args)`
  Launch a standalone application.
  `static void`
  `launch(String... args)`
  Launch a standalone application.
  `final void`
  `notifyPreloader(Preloader.PreloaderNotification info)`
  Notifies the preloader with an application-generated notification.
  `static void`
  `setUserAgentStylesheet(String url)`
  Set the user agent stylesheet used by the whole application.
  `abstract void`
  `start(Stage primaryStage)`
  The main entry point for all JavaFX applications.
  `void`
  `stop()`
  This method is called when the application should stop, and provides a convenient place to prepare for application exit and destroy resources.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### STYLESHEET_CASPIAN

    public static final String STYLESHEET_CASPIAN
    Constant for user agent stylesheet for the "Caspian" theme. Caspian is the theme that shipped as default in JavaFX 2.x.
    Since:
      JavaFX 8.0
    See Also:
      - Constant Field Values

  - ### STYLESHEET_MODENA

    public static final String STYLESHEET_MODENA
    Constant for user agent stylesheet for the "Modena" theme. Modena is the default theme for JavaFX 8.x.
    Since:
      JavaFX 8.0
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Application

    public Application()
    Constructs a new `Application` instance.

- ## Method Details

  - ### launch

    public static void launch(Class<? extends Application> appClass, String... args)
    Launch a standalone application. This method is typically called from the `main` method. It must not be called more than once or an exception will be thrown.

    The launch method does not return until the application has exited, either via a call to `Platform.exit()` or all of the application windows have been closed. The class specified by the `appClass` argument must be a public subclass of `Application` with a public no-argument constructor, in a package that is `exported` (or `open`) to at least the `javafx.graphics` module, or a RuntimeException will be thrown.

    Typical usage is:

             public static void main(String[] args) {
                 Application.launch(MyApp.class, args);
             }

    where `MyApp` is a subclass of Application.
    Parameters:
      `appClass` - the application class that is constructed and executed by the launcher.
      `args` - the command line arguments passed to the application. An application may get these parameters using the `getParameters()` method.
    Throws:
      `IllegalStateException` - if this method is called more than once.
      `IllegalStateException` - if this method is called from the JavaFX application thread.
      `IllegalArgumentException` - if `appClass` is not a subclass of `Application`.
      `RuntimeException` - if there is an error launching the JavaFX runtime, or if the application class cannot be constructed (e.g., if the class is not public or is not in an exported package), or if an Exception or Error is thrown by the Application constructor, init method, start method, or stop method.

  - ### launch

    public static void launch(String... args)
    Launch a standalone application. This method is typically called from the `main` method. It must not be called more than once or an exception will be thrown. This is equivalent to `launch(TheClass.class, args)` where `TheClass` is the immediately enclosing class of the method that called launch. It must be a public subclass of `Application` with a public no-argument constructor, in a package that is `exported` (or `open`) to at least the `javafx.graphics` module, or a RuntimeException will be thrown.

    The launch method does not return until the application has exited, either via a call to `Platform.exit()` or all of the application windows have been closed.

    Typical usage is:

             public static void main(String[] args) {
                 Application.launch(args);
             }

    Parameters:
      `args` - the command line arguments passed to the application. An application may get these parameters using the `getParameters()` method.
    Throws:
      `IllegalStateException` - if this method is called more than once.
      `IllegalStateException` - if this method is called from the JavaFX application thread.
      `RuntimeException` - if there is an error launching the JavaFX runtime, or if the application class cannot be constructed (e.g., if the class is not public or is not in an exported package), or if an Exception or Error is thrown by the Application constructor, init method, start method, or stop method.

  - ### init

    public void init() throws Exception
    The application initialization method. This method is called immediately after the Application class is loaded and constructed. An application may override this method to perform initialization prior to the actual starting of the application.

    The implementation of this method provided by the Application class does nothing.

    NOTE: This method is not called on the JavaFX Application Thread. An application must not construct a Scene or a Stage in this method. An application may construct other JavaFX objects in this method.

    Throws:
      `Exception` - if something goes wrong

  - ### start

    public abstract void start(Stage primaryStage) throws Exception
    The main entry point for all JavaFX applications. The start method is called after the init method has returned, and after the system is ready for the application to begin running.

    NOTE: This method is called on the JavaFX Application Thread.

    Parameters:
      `primaryStage` - the primary stage for this application, onto which the application scene can be set. Applications may create other stages, if needed, but they will not be primary stages.
    Throws:
      `Exception` - if something goes wrong

  - ### stop

    public void stop() throws Exception
    This method is called when the application should stop, and provides a convenient place to prepare for application exit and destroy resources.

    The implementation of this method provided by the Application class does nothing.

    NOTE: This method is called on the JavaFX Application Thread.

    Throws:
      `Exception` - if something goes wrong

  - ### getHostServices

    public final HostServices getHostServices()
    Gets the HostServices provider for this application. This provides the ability to get the code base and document base for this application, and to show a web page in a browser.
    Returns:
      the HostServices provider

  - ### getParameters

    public final Application.Parameters getParameters()
    Retrieves the parameters for this Application, including any arguments passed on the command line.

    NOTE: this method should not be called from the Application constructor, as it will return null. It may be called in the init() method or any time after that.

    Returns:
      the parameters for this Application, or null if called from the constructor.

  - ### notifyPreloader

    public final void notifyPreloader(Preloader.PreloaderNotification info)
    Notifies the preloader with an application-generated notification. Application code calls this method with a PreloaderNotification that is delivered to the `Preloader.handleApplicationNotification` method. This is primarily useful for cases where an application wants the preloader to show progress during a long application initialization step.

    NOTE: the notification will be delivered only to the preloader's handleApplicationNotification() method; this means, for example, that if this method is called with a ProgressNotification, that notification will not be delivered to the `Preloader.handleProgressNotification` method.

    Parameters:
      `info` - the application-generated preloader notification

  - ### getUserAgentStylesheet

    public static String getUserAgentStylesheet()
    Get the user agent stylesheet used by the whole application. This is used to provide default styling for all ui controls and other nodes. A value of null means the platform default stylesheet is being used.

    NOTE: This method must be called on the JavaFX Application Thread.

    Returns:
      The URL to the stylesheet as a String.
    Since:
      JavaFX 8.0

  - ### setUserAgentStylesheet

    public static void setUserAgentStylesheet(String url)
    Set the user agent stylesheet used by the whole application. This is used to provide default styling for all ui controls and other nodes. Each release of JavaFX may have a new default value for this so if you need to guarantee consistency you will need to call this method and choose what default you would like for your application. A value of null will restore the platform default stylesheet. This property can also be set on the command line with `-Djavafx.userAgentStylesheetUrl=[URL]` Setting it on the command line overrides anything set using this method in code.

    The URL is a hierarchical URI of the form [scheme:][//authority][path]. If the URL does not have a [scheme:] component, the URL is considered to be the [path] component only. Any leading '/' character of the [path] is ignored and the [path] is treated as a path relative to the root of the application's classpath.

    The RFC 2397 "data" scheme for URLs is supported in addition to the protocol handlers that are registered for the application. If a URL uses the "data" scheme and the MIME type is either empty, "text/plain", or "text/css", the payload will be interpreted as a CSS file. If the MIME type is "application/octet-stream", the payload will be interpreted as a binary CSS file (see `Stylesheet.convertToBinary(File, File)`).

    NOTE: This method must be called on the JavaFX Application Thread.

    Parameters:
      `url` - The URL to the stylesheet as a String.
    Since:
      JavaFX 8.0