java-gnome version 4.1.2

org.gnome.gtk
Class Application

Object
  extended by org.freedesktop.bindings.Pointer
      extended by org.freedesktop.bindings.Proxy
          extended by org.gnome.glib.Object
              extended by org.gnome.glib.Application
                  extended by 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
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
Application(long pointer)
           
Application(String id)
          Creates a new Application instance.
Application(String id, ApplicationFlags flags)
          Creates a new Application instance.
 
Method Summary
 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


java-gnome