c++-gtk-utils
|
00001 /* Copyright (C) 2009 and 2011 Chris Vine 00002 00003 The library comprised in this file or of which this file is part is 00004 distributed by Chris Vine under the GNU Lesser General Public 00005 License as follows: 00006 00007 This library is free software; you can redistribute it and/or 00008 modify it under the terms of the GNU Lesser General Public License 00009 as published by the Free Software Foundation; either version 2.1 of 00010 the License, or (at your option) any later version. 00011 00012 This library is distributed in the hope that it will be useful, but 00013 WITHOUT ANY WARRANTY; without even the implied warranty of 00014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00015 Lesser General Public License, version 2.1, for more details. 00016 00017 You should have received a copy of the GNU Lesser General Public 00018 License, version 2.1, along with this library (see the file LGPL.TXT 00019 which came with this source code package in the c++-gtk-utils 00020 sub-directory); if not, write to the Free Software Foundation, Inc., 00021 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 00022 00023 */ 00024 00025 #ifndef CGU_PROG_PRESENT_H 00026 #define CGU_PROG_PRESENT_H 00027 00028 #include <glib.h> 00029 00030 #include <c++-gtk-utils/cgu_config.h> 00031 00032 namespace Cgu { 00033 00034 /** 00035 * @defgroup prog_present prog_present 00036 * @anchor prog_presenterAnchor 00037 * 00038 * \#include <c++-gtk-utils/prog_present.h> 00039 * 00040 * The c++-gtk-utils library provides functions to make a single 00041 * instance program. The functionality for a single instance is 00042 * provided by gio (if glib >= 2.26 is installed) or dbus-glib, but 00043 * the interface in this file comprises only two functions, 00044 * register_prog() and present_instance(). register_prog() returns 00045 * 'true' if it is the first program instance to run in a particular 00046 * user session, otherwise 'false'. If false is returned, 00047 * present_instance() is then called to bring up the program instance 00048 * already running. register_prog() is passed a function to carry out 00049 * the program presentation. 00050 * 00051 * Typical usage would be, for example: 00052 * 00053 * @code 00054 * GtkWidget* window; 00055 * gboolean present_func(void* data, const char** args) { 00056 * gdk_x11_window_move_to_current_desktop(gtk_widget_get_window(window)); 00057 * gtk_window_present(GTK_WINDOW(window)); 00058 * return TRUE; 00059 * } 00060 * 00061 * using namespace Cgu; 00062 * 00063 * int main(int argc, char* argv[]) { 00064 * gtk_init(&argc, &argv); 00065 * if (register_prog("my_prog", present_func)) { 00066 * window = gtk_window_new(GTK_WINDOW_TOPLEVEL); 00067 * ... go through normal business of creating GTK+ program interface ... 00068 * gtk_main(); 00069 * } 00070 * else { 00071 * if (!present_instance()) gdk_notify_startup_complete(); 00072 * else { 00073 * ... carry out a dbus failure strategy, which may mean starting 00074 * ... the program anyway with appropriate warnings to the user 00075 * ... that there may be multiple instances running, or may mean 00076 * ... displaying a GtkMessageDialog object to the user suggesting 00077 * ... that the user should check that the session message bus 00078 * ... daemon is running, and then terminating 00079 * } 00080 * } 00081 * return 0; 00082 * } 00083 * @endcode 00084 * 00085 * @b NOTE 00086 * 00087 * These functions are only compiled into the library if either 00088 * dbus-glib >= 0.70, or glib >= 2.26 (for gio's dbus implementation), 00089 * is installed. If both are installed, gio's dbus implementation is 00090 * used. 00091 */ 00092 00093 00094 00095 /** 00096 * Function pointer type that present_instance() will execute via dbus 00097 * and intended to cause eg the program window to show itself. It must 00098 * return TRUE if successful, FALSE if not. Returning FALSE will 00099 * cause present_instance() to return 2. However, generally any 00100 * GDK/GTK+ errors encountered by the function represented by this 00101 * function pointer are best reported by that function bringing up a 00102 * dialog diagnostic rather than by returning FALSE (in other words, 00103 * in most cases you will want to return TRUE, even if there has been 00104 * a problem). It should not throw, as the dbus and dbus-glib 00105 * implementation has C linkage and cannot handle exceptions. 00106 * @param object_data NULL or persistent data, as determined by the 00107 * call to register_prog(). By default it is NULL. 00108 * @param instance_args NULL or a NULL terminated array of strings to 00109 * be passed to the PresentFunc function on a particular invocation, 00110 * as determined by present_instance(). By default it is NULL. 00111 * @return TRUE if successful, FALSE if not and it is important to 00112 * notify the caller of the problem. 00113 * @ingroup prog_present 00114 */ 00115 typedef gboolean(*PresentFunc)(void* object_data, const char** instance_args); 00116 00117 /** 00118 * register_prog() returns 'true' if this is the first instance of the 00119 * program to register itself, otherwise 'false'. false will also be 00120 * returned, and an error logged, if a dbus connection cannot be 00121 * obtained in order to carry out program registration (in which case 00122 * the subsequent call to present_instance() will return 1, 00123 * representing failure). The first argument (prog_name) can be 00124 * anything that contains valid xml name characters (provided that for 00125 * any one program it is always the same for that program), but it is 00126 * best to pass the name of the program to be invoked. The object 00127 * data argument is persistent data passed to each invocation of 00128 * PresentFunc for that program while it is running, so the data 00129 * passed needs to exist throughout program execution (eg, allocate it 00130 * on the heap or have it in the same scope as that in which main() 00131 * returns). By default a NULL value is passed. It does not throw. 00132 * @param prog_name An identifier name comprising valid xml 00133 * characters. 00134 * @param func A function pointer representing the function to be 00135 * executed by present_instance() if the program is already running. 00136 * @param object_data NULL or persistent data to be passed to each 00137 * invocation of func. By default it is NULL. 00138 * @return 'true' if this is the first instance of the program to 00139 * register itself, otherwise 'false'. false will also be returned, 00140 * and an error logged, if a dbus connection cannot be obtained in 00141 * order to carry out program registration (in which case the 00142 * subsequent call to present_instance() will return 1, representing 00143 * failure). 00144 * @ingroup prog_present 00145 */ 00146 bool register_prog(const char* prog_name, PresentFunc func, void* object_data = 0); 00147 00148 /** 00149 * present_instance() is to be called if register_prog() returns 00150 * false. Returns 0 on success, 1 if there has been a dbus error or 2 00151 * if the PresentFunc callback registered by register_prog() has 00152 * returned FALSE. The instance_args argument is passed to 00153 * PresentFunc on this invocation, and is either NULL (the default 00154 * argument), or a NULL terminated array of strings, and in most cases 00155 * you won't need it so NULL is appropriate. It is a blocking call 00156 * (it will wait for the PresentFunc function to complete). It does 00157 * not throw. 00158 * @param instance_args NULL or a NULL terminated array of strings to 00159 * be passed to the PresentFunc function on this invocation. By 00160 * default it is NULL. 00161 * @return 0 on success, 1 on failure (say, because a dbus connection 00162 * could not be obtained in order to carry out program registration) 00163 * or 2 if the PresentFunc callback registered by register_prog() 00164 * returns FALSE. 00165 * @ingroup prog_present 00166 */ 00167 int present_instance(const char** instance_args = 0); 00168 00169 } // namespace Cgu 00170 00171 #endif