bonobo-application

bonobo-application — a framework for unique application instance and automation

Synopsis

void                (*BonoboAppHookFunc)                (BonoboApplication *app,
                                                         gpointer data);
BonoboApplication*  bonobo_application_new              (const char *name);
void                bonobo_application_register_message (BonoboApplication *app,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         GClosure *opt_closure,
                                                         GType return_type,
                                                         GType first_arg_type,
                                                         ...);
void                bonobo_application_register_message_v
                                                        (BonoboApplication *app,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         GClosure *opt_closure,
                                                         GType return_type,
                                                         GType const arg_types[]);
void                bonobo_application_register_message_va
                                                        (BonoboApplication *app,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         GClosure *opt_closure,
                                                         GType return_type,
                                                         GType first_arg_type,
                                                         va_list var_args);
gint                bonobo_application_new_instance     (BonoboApplication *app,
                                                         gint argc,
                                                         gchar *argv[]);
gchar *             bonobo_application_create_serverinfo
                                                        (BonoboApplication *app,
                                                         gchar const *envp[]);
Bonobo_RegistrationResult  bonobo_application_register_unique
                                                        (BonoboApplication *app,
                                                         gchar const *serverinfo,
                                                         BonoboAppClient **client);
void                bonobo_application_add_hook         (BonoboAppHookFunc func,
                                                         gpointer data);
void                bonobo_application_remove_hook      (BonoboAppHookFunc func,
                                                         gpointer data);

Description

Details

BonoboAppHookFunc ()

void                (*BonoboAppHookFunc)                (BonoboApplication *app,
                                                         gpointer data);

app :
data :

bonobo_application_new ()

BonoboApplication*  bonobo_application_new              (const char *name);

Creates a new BonoboApplication object.

name : application name
Returns : a new BonoboApplication

bonobo_application_register_message ()

void                bonobo_application_register_message (BonoboApplication *app,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         GClosure *opt_closure,
                                                         GType return_type,
                                                         GType first_arg_type,
                                                         ...);

Registers a new message type that the application supports.

When opt_closure is provided (and is non-NULL) it takes care of calling the callback function with the same arguments as registered for the message. On the other hand if opt_closure is NULL, the function arguments are provided in a GValueArray. This enables defining functions that accept variable number of arguments, but is perhaps a little more tedious to implement.

Example 5. Function with a closure

static void
message_open_url_cb (BonoboApplication *app, const char *url, gboolean new_win)
{
	...
}
...
closure = g_cclosure_new (G_CALLBACK (message_open_url_cb), NULL, NULL);
g_closure_set_marshal (closure, my_marshal_VOID__STRING_BOOLEAN);
bonobo_application_register_message (app, "open-url", "Opens a new URL in the browser."
                                     " Parameters: url(string), open-in-new-window(boolean)",
                                     closure, G_TYPE_NONE, G_TYPE_STRING, G_TYPE_BOOLEAN, G_TYPE_NONE);

Example 6. Function accepting variable number of arguments

static GValue *
message_open_url_cb (BonoboApplication *app, const char *message, GValueArray *args)
{
	const char *url;
	gboolean    new_win = TRUE;
	g_return_val_if_fail (strcmp (message, "open-url") == 0, NULL);
	g_return_val_if_fail (args->n_values > 0, NULL);
	g_return_val_if_fail (G_VALUE_HOLDS_STRING (&args->values[0]), NULL);
	url = g_value_get_string (&args->values[0]);
	if (args->n_values > 1)
	{
		g_return_val_if_fail (G_VALUE_HOLDS_BOOLEAN (&args->values[1]), NULL);
		new_win = g_value_get_boolean (&args->values[1]);
	}
	...
	return NULL;
}
...
bonobo_application_register_message (app, "open-url", "Opens a new URL in the browser."
                                     " Parameters: url(string) [, open-in-new-window(boolean)]",
                                     NULL, G_TYPE_NONE, G_TYPE_STRING, G_TYPE_BOOLEAN, G_TYPE_NONE);
g_signal_connect (app, "message::open-url", G_CALLBACK (message_open_url_cb), NULL);

Note

You are not required to register any messages for your application. However, only registered functions are included in the list returned by bonobo_app_client_msg_list()

app : a BonoboApplication
name : message string identifier
description : a string containing a human readable description of the message
opt_closure : a GClosure that will be called for this message, or NULL; Function takes ownership of this closure.
return_type : Message return GType.
first_arg_type : GType of first argument of message, or G_TYPE_NONE.
... : G_TYPE_NONE -terminated list of argument GType's

bonobo_application_register_message_v ()

void                bonobo_application_register_message_v
                                                        (BonoboApplication *app,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         GClosure *opt_closure,
                                                         GType return_type,
                                                         GType const arg_types[]);

See bonobo_application_register_message().

app : a BonoboApplication
name : message string identifier
description : a string containing a human readable description of the message
opt_closure : a GClosure that will be called for this message, or NULL; Function takes ownership of this closure.
return_type : Message return GType.
arg_types : G_TYPE_NONE -terminated vector of argument GType's

bonobo_application_register_message_va ()

void                bonobo_application_register_message_va
                                                        (BonoboApplication *app,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         GClosure *opt_closure,
                                                         GType return_type,
                                                         GType first_arg_type,
                                                         va_list var_args);

See bonobo_application_register_message().

app : a BonoboApplication
name : message string identifier
description : a string containing a human readable description of the message
opt_closure : a GClosure that will be called for this message, or NULL; Function takes ownership of this closure.
return_type : Message return GType.
first_arg_type : GType of first argument of message, or G_TYPE_NONE
var_args : G_TYPE_NONE -terminated valist of argument GType's

bonobo_application_new_instance ()

gint                bonobo_application_new_instance     (BonoboApplication *app,
                                                         gint argc,
                                                         gchar *argv[]);

Emit the "new-instance" signal of the BonoboApplication with the given arguments.

app : a BonoboApplication
argc : number of elements in argv
argv : array of strings (command-line arguments)
Returns : signal return value

bonobo_application_create_serverinfo ()

gchar *             bonobo_application_create_serverinfo
                                                        (BonoboApplication *app,
                                                         gchar const *envp[]);

This utility function provides a simple way to contruct a valid serverinfo XML string.

app : a BonoboApplication
envp : NULL-terminated string vector, containing the enviroment variables we wish to include in the server description.
Returns : a newly allocated string; caller must g_free() it.

bonobo_application_register_unique ()

Bonobo_RegistrationResult  bonobo_application_register_unique
                                                        (BonoboApplication *app,
                                                         gchar const *serverinfo,
                                                         BonoboAppClient **client);

Try to register the running application, or check for an existing application already registered and get a reference to it. Applications already running but on different environments (as defined by the bonobo:environenment server property) than this one are ignored and do not interfere.

If the registration attempt indicates that another instance of this application is already running, then the output variable client will receive a newly created BonoboAppClient associated with the running application. Otherwise, *client is set to NULL.

app : a BonoboApplication instance
serverinfo : the XML server description. bonobo_application_create_server_description() may be used to easily create such description.
client : output parameter that will contain a client object, in case another instance has already running, or NULL if we are the first to register.
Returns : the registration result. Bonobo_ACTIVATION_REG_SUCCESS means the application was registered, since no other running instance was detected. If, however, a running application is detected, Bonobo_ACTIVATION_REG_ALREADY_ACTIVE is returned.

bonobo_application_add_hook ()

void                bonobo_application_add_hook         (BonoboAppHookFunc func,
                                                         gpointer data);

Add a hook function to be called whenever a new BonoboApplication instance is created.

func : hook function
data : user data

bonobo_application_remove_hook ()

void                bonobo_application_remove_hook      (BonoboAppHookFunc func,
                                                         gpointer data);

Removes a hook function previously set with bonobo_application_add_hook().

func : hook function
data : user data