org.gnome.gtk

## Class Application

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.glib.Application
        - - org.gnome.gtk.Application

-     public class Application
      extends Application

  This class handles the lifecycle of a java-gnome application. It ensures that the application is unique and manages a list of top-level windows whose life-cycle is automatically tied to the life-cycle of the application.

  Applications are unique in your desktop session; once the program is running subsequent invocations of the binary will result in a signal being sent to the original, known as the "primary" instance.

  You can model several different program styles this way. A straight forward and common use is for subsequent invocations merely to "wake" the primary, perhaps bringing it to front. In this example, you start by constructing an Application object:

       app = new Application("com.example.MasterControlProgram");

  in this case "registering" the DBus name `com.example.MasterControlProgram` as the unique identifier for this application. As with a plain GTK program, you then enter the main loop, but instead of `Gtk.main()` you use Application's `run()` to do so:

       app.run(args);

  the original process blocks in this call (and runs a GTK main loop and your widgets start receiving event signals). Subsequent programs attempting to register that name (ie, this same code being run through a second time but by a different invocation of your program) will implicitly discover that they are not the primary instance; the remote will return from the call to `run()` although how fast this occurs depends on actions the primary takes.

  ## Signals

  The `Application.Startup` will be fired once for an instance when it becomes primary. So, that's the place to put your UI setup code.

  `Application.Activate` will occurs when when Application's `activate()` is called. It is also raised when the primary begins running the first time if no flags were passed to the Application constructor.

  If the application has been configured as passing command line arguments from remote instances to the primary, then instead of `Application.Activate`, the `Application.CommandLine` signal will be raised on the primary. You can always call `activate()` from this handler thereby concentrating the code to deal with raising the UI there.

  ## Life cycle

  For each principle GTK Window you create, call Application's `addWindow()` and be sure to put a call to Application's `removeWindow()` in that Window's `Window.DeleteEvent` handler. The runtime system will keep track of these registered Windows; your application will terminate when the last one is destroyed.

  You can also call Application's `quit()` to exit the program.

  ## Initialization

  The call to `Gtk.init()` or creating a `new Application()` must be the first thing done in your program.

  Since:
    4.1.2
  Author:
    Guillaume Mazoyer, Andrew Cowie

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Application.Activate` This signal is emitted on the primary instance when an activation occurs.
    `static interface` | `Application.CommandLine` This signal is emitted on the primary instance when command line arguments are to be processed.
    `static interface` | `Application.Startup` This signal is emitted on the primary instance when any of the conditions starting the program are raised.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Application(long pointer)`
    `Application(String id)` Creates a new Application instance.
    `Application(String id, ApplicationFlags flags)` Creates a new Application instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addWindow(Window window)` Adds a window from the Application.
    `void` | `connect(Application.Activate handler)` Hook up the `Application.Activate` handler.
    `void` | `connect(Application.CommandLine handler)` Hook up the `Application.CommandLine` handler.
    `void` | `connect(Application.Startup handler)` Hook up the `Application.Startup` handler.
    `Window[]` | `getWindows()` Returns an array of the `windows` currently associated with Application.
    `void` | `removeWindow(Window window)` Removes a window from the Application.

    - ### Methods inherited from class org.gnome.glib.Application

      `activate, getApplicationId, getFlags, getInactivityTimeout, hold, isRemote, quit, run, setApplicationId, setFlags, setInactivityTimeout, unhold`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Application

          public Application(long pointer)

    - #### Application

          public Application(String id)

      Creates a new Application instance. The `id` must be a valid identifier; see `isValidID()`. This id needs to be common between all instances of the application; it is what enables the uniqueness mechanism.

      This constructor implies a normal application with default uniqueness behaviour: first instance will become primary, subsequent instances will communicate activation to the primary then terminate.

      Since:
        4.1.2

    - #### Application

          public Application(String id,
                     ApplicationFlags flags)

      Creates a new Application instance. The `id` needs to be a valid identifier, see `isValidID()` for details. The `flags` argument allows you to specify different behaviour, marking this program as a `launcher` or `service`, for example.
      Since:
        4.1.2

  - ### Method Detail

    - #### addWindow

          public void addWindow(Window window)

      Adds a window from the Application. GTK+ will keep the Application running as long as it has any windows. The connection between the Application and the window will remain until the window is destroyed or `removeWindow()` is called.
      Since:
        4.1.2

    - #### connect

          public void connect(Application.Activate handler)

      Hook up the `Application.Activate` handler.
      Since:
        4.1.2

    - #### connect

          public void connect(Application.CommandLine handler)

      Hook up the `Application.CommandLine` handler. This signal will only be raised if the Application was constructed with the `HANDLES_COMMAND_LINE` flag.
      Since:
        4.1.2

    - #### connect

          public void connect(Application.Startup handler)

      Hook up the `Application.Startup` handler.
      Since:
        4.1.2

    - #### getWindows

          public Window[] getWindows()

      Returns an array of the `windows` currently associated with Application.
      Since:
        4.1.2

    - #### removeWindow

          public void removeWindow(Window window)

      Removes a window from the Application. The Application will stop running if the last window is removed.
      Since:
        4.1.2