c++-gtk-utils
prog_present.h
Go to the documentation of this file.
1 /* Copyright (C) 2009 Chris Vine
2 
3 The library comprised in this file or of which this file is part is
4 distributed by Chris Vine under the GNU Lesser General Public
5 License as follows:
6 
7  This library is free software; you can redistribute it and/or
8  modify it under the terms of the GNU Lesser General Public License
9  as published by the Free Software Foundation; either version 2.1 of
10  the License, or (at your option) any later version.
11 
12  This library is distributed in the hope that it will be useful, but
13  WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  Lesser General Public License, version 2.1, for more details.
16 
17  You should have received a copy of the GNU Lesser General Public
18  License, version 2.1, along with this library (see the file LGPL.TXT
19  which came with this source code package in the c++-gtk-utils
20  sub-directory); if not, write to the Free Software Foundation, Inc.,
21  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22 
23 */
24 
25 #ifndef CGU_PROG_PRESENT_H
26 #define CGU_PROG_PRESENT_H
27 
28 #include <glib.h>
29 
31 
32 namespace Cgu {
33 
34 /**
35  * @defgroup prog_present prog_present
36  * @anchor prog_presenterAnchor
37  *
38  * \#include <c++-gtk-utils/prog_present.h>
39  *
40  * The c++-gtk-utils library provides functions to make a single
41  * instance program. The functionality for a single instance is
42  * provided by gio (if glib >= 2.26 is installed) or dbus-glib, but
43  * the interface in this file comprises only two functions,
44  * register_prog() and present_instance(). register_prog() returns
45  * TRUE if it is the first program instance to run in a particular
46  * user session, otherwise FALSE. If FALSE is returned,
47  * present_instance() is then called to bring up the program instance
48  * already running. register_prog() is passed a function to carry out
49  * the program presentation.
50  *
51  * Typical usage would be, for example:
52  *
53  * @code
54  * GtkWidget* window;
55  * gboolean present_func(void* data, const char** args) {
56  * gdk_x11_window_move_to_current_desktop(gtk_widget_get_window(window));
57  * gtk_window_present(GTK_WINDOW(window));
58  * return TRUE;
59  * }
60  *
61  * using namespace Cgu;
62  *
63  * int main(int argc, char* argv[]) {
64  * gtk_init(&argc, &argv);
65  * if (register_prog("my_prog", present_func)) {
66  * window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
67  * ... go through normal business of creating GTK+ program interface ...
68  * gtk_main();
69  * }
70  * else {
71  * if (!present_instance()) gdk_notify_startup_complete();
72  * else {
73  * ... carry out a dbus failure strategy, which may mean starting
74  * ... the program anyway with appropriate warnings to the user
75  * ... that there may be multiple instances running, or may mean
76  * ... displaying a GtkMessageDialog object to the user suggesting
77  * ... that the user should check that the session message bus
78  * ... daemon is running, and then terminating
79  * }
80  * }
81  * return 0;
82  * }
83  * @endcode
84  *
85  * @b NOTE
86  *
87  * These functions are only compiled into the library if either
88  * dbus-glib >= 0.70 is installed or, from version 1.2.7, glib >= 2.26
89  * (for gio's dbus implementation) is installed. If both are
90  * installed, from version 1.2.7 gio's dbus implementation is used.
91  */
92 
93 
94 
95 /**
96  * Function pointer type that present_instance() will execute via dbus
97  * and intended to cause eg the program window to show itself. It must
98  * return TRUE if successful, FALSE if not. From version 1.2.2,
99  * returning FALSE will be cause present_instance() to return 2 (prior
100  * to that it would return 1, the same as a dbus error). However,
101  * generally any GDK/GTK+ errors encountered by the function
102  * represented by this function pointer are best reported by that
103  * function bringing up a dialog diagnostic rather than by returning
104  * FALSE (in other words, in most cases you will want to return TRUE,
105  * even if there has been a problem). It should not throw, as the
106  * dbus and dbus-glib implementation has C linkage and cannot handle
107  * exceptions.
108  * @param object_data NULL or persistent data, as determined by the
109  * call to register_prog(). By default it is NULL.
110  * @param instance_args NULL or a NULL terminated array of strings to
111  * be passed to the PresentFunc function on a particular invocation,
112  * as determined by present_instance(). By default it is NULL.
113  * @return TRUE if successful, FALSE if not and it is important to
114  * notify the caller of the problem.
115  * @ingroup prog_present
116  */
117 typedef gboolean(*PresentFunc)(void* object_data, const char** instance_args);
118 
119 /**
120  * register_prog() returns TRUE if this is the first instance of the
121  * program to register itself, otherwise FALSE. FALSE will also be
122  * returned, and an error logged, if a dbus connection cannot be
123  * obtained in order to carry out program registration (in which case
124  * the subsequent call to present_instance() will return 1,
125  * representing failure). The first argument (prog_name) can be
126  * anything that contains valid xml name characters (provided that for
127  * any one program it is always the same for that program), but it is
128  * best to pass the name of the program to be invoked. The object
129  * data argument is persistent data passed to each invocation of
130  * PresentFunc for that program while it is running, so the data
131  * passed needs to exist throughout program execution (eg, allocate it
132  * on the heap or have it in the same scope as that in which main()
133  * returns). By default a NULL value is passed. It does not throw.
134  * @param prog_name An identifier name comprising valid xml
135  * characters.
136  * @param func A function pointer representing the function to be
137  * executed by present_instance() if the program is already running.
138  * @param object_data NULL or persistent data to be passed to each
139  * invocation of func. By default it is NULL.
140  * @return TRUE if this is the first instance of the program to
141  * register itself, otherwise FALSE. FALSE will also be returned, and
142  * an error logged, if a dbus connection cannot be obtained in order
143  * to carry out program registration (in which case the subsequent
144  * call to present_instance() will return 1, representing failure).
145  * @ingroup prog_present
146  */
147 gboolean register_prog(const char* prog_name, PresentFunc func, void* object_data = 0);
148 
149 /**
150  * present_instance() is to be called if register_prog() returns
151  * FALSE. Returns 0 on success and 1 if there has been a dbus error.
152  * Prior to version 1.2.2, the value 1 would also be returned if the
153  * PresentFunc callback registered by register_prog() has returned
154  * FALSE: however, from version 1.2.2 this causes 2 to be returned.
155  * The instance_args argument is passed to PresentFunc on this
156  * invocation, and is either NULL (the default argument), or a NULL
157  * terminated array of strings, and in most cases you won't need it so
158  * NULL is appropriate. It is a blocking call (it will wait for the
159  * PresentFunc function to complete). It does not throw.
160  * @param instance_args NULL or a NULL terminated array of strings to
161  * be passed to the PresentFunc function on this invocation. By
162  * default it is NULL.
163  * @return 0 on success, 1 on failure (say, because a dbus connection
164  * could not be obtained in order to carry out program registration).
165  * Prior to version 1.2.2, the value 1 would also be returned if the
166  * PresentFunc callback registered by register_prog() returns FALSE:
167  * however, from version 1.2.2 this causes 2 to be returned.
168  * @ingroup prog_present
169  */
170 int present_instance(const char** instance_args = 0);
171 
172 /*
173  * TODO: At a suitable API/ABI break, have register_prog() and
174  * PresentFunc return bool. Note: prog_presenter_present() must
175  * return a gboolean type with value either TRUE or FALSE, because it
176  * is required by dbus-glib to return such a value/type.
177  */
178 
179 } // namespace Cgu
180 
181 #endif
Cgu
Definition: application.h:45
Cgu::register_prog
gboolean register_prog(const char *prog_name, PresentFunc func, void *object_data=0)
Cgu::present_instance
int present_instance(const char **instance_args=0)
Cgu::PresentFunc
gboolean(* PresentFunc)(void *object_data, const char **instance_args)
Definition: prog_present.h:117
cgu_config.h