libs/gtkmm2/gtk/gtkmm/main.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_MAIN_H
   4 #define _GTKMM_MAIN_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   9
  10 /* main.h
  11  *
  12  * Copyright (C) 1998-2003 The gtkmm Development Team
  13  *
  14  * This library is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU Library General Public
  16  * License as published by the Free Software Foundation; either
  17  * version 2 of the License, or (at your option) any later version.
  18  *
  19  * This library is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  22  * Library General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Library General Public
  25  * License along with this library; if not, write to the Free
  26  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  27  */
  28
  29
  30 #include <gtk/gtkmain.h>
  31
  32 #include <sigc++/sigc++.h>
  33 #include <gdkmm/types.h>
  34
  35
  36 namespace Gtk
  37 {
  38
  39 class Widget;
  40 class Window;
  41
  42 //**********************************************************************
  43
  44 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  45 //Actually, I'd like to just keep these out of the alphabetical list. murrayc.
  46
  47 /// Run Signal Class (internal)
  48 class RunSig
  49 {
  50 public:
  51   typedef sigc::slot<void> SlotType;
  52
  53   sigc::connection connect(const SlotType& slot);
  54
  55 protected:
  56   static gboolean gtk_callback(gpointer data);
  57 };
  58
  59
  60 /// Quit Signal Class (internal)
  61 class QuitSig
  62 {
  63 public:
  64   typedef sigc::slot<bool> SlotType;
  65
  66   sigc::connection connect(const SlotType& slot, guint main_level = 0);
  67
  68 protected:
  69   static gboolean gtk_callback(gpointer data); //gtk+ calls this, which then calls our slot.
  70 };
  71
  72
  73 /// KeySnooper Signal Class (internal)
  74 class KeySnooperSig
  75 {
  76 public:
  77   typedef sigc::slot<int, Widget*, GdkEventKey*> SlotType;
  78
  79   sigc::connection connect(const SlotType& slot);
  80
  81 protected:
  82   static int gtk_callback(GtkWidget* widget, GdkEventKey* event, gpointer data);
  83 };
  84
  85 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  86
  87
  88 //**********************************************************************
  89
  90 /** Main application class
  91  * Every application must have one of these objects.
  92  * It may not be global and must be the first Gtk object created.
  93  * It is a singleton so declaring more than one will simply access the first
  94  * created.
  95  *
  96  * Normal use of this class is in the main() function to give argc and argv
  97  * to the gtk initialization. Widgets can use Gtk::Main::quit()
  98  * to exit from the application.
  99  *
 100  * The internals of the widget have been disguised as signals
 101  * so that the user can easily connect using the same methods
 102  * used throughout the widget interface.
 103  *
 104  * Minimal gtkmm application is something like this:
 105  * @code
 106  * int main(int argc, char *argv[]) {
 107  *     Gtk::Main kit(argc, argv);
 108  *     ... create some widgets ...
 109  *     kit.run();
 110  * }
 111  * @endcode
 112  */
 113 class Main : public sigc::trackable
 114 {
 115 public:
 116
 117   //This offers the same functionality as gtk_init_with_args():
 118   /** Scans the argument vector, and strips off all parameters parsed by GTK+ or your @a option_context.
 119    * Add a Glib::OptionGroup to the Glib::OptionContext to parse your own command-line arguments.
 120    *
 121    * Note:  The argument strings themselves won't be modified, although the
 122    * pointers to them might change.  This makes it possible to create your
 123    * own argv of string literals, which have the type 'const char[]' in
 124    * standard C++.  (You might need to use const_cast<>, though.)
 125    *
 126    * This function automatically generates nicely formatted
 127    * <option>--help</option> output. Note that your program will
 128    * be terminated after writing out the help output.
 129    *
 130    * @param argc a reference to the number of command line arguments.
 131    * @param argv a reference to the array of command line arguments.
 132    * @parameter_string a string which is displayed in the first line of <option>--help</option> output,
 133    * after <literal><replaceable>programname</replaceable> [OPTION...]</literal>
 134    * @param option_context A Glib::OptionContext containing Glib::OptionGroups which described the command-line arguments taken by your program.
 135    *
 136    * @throw Glib::OptionError
 137    */
 138   Main(int& argc, char**& argv, Glib::OptionContext& option_context);
 139
 140   /** Scans the argument vector, and strips off all parameters known to GTK+.
 141    * Your application may then handle the remaining arguments.
 142    *
 143    * Note:  The argument strings themself won't be modified, although the
 144    * pointers to them might change.  This makes it possible to create your
 145    * own argv of string literals, which have the type 'const char[]' in
 146    * standard C++.  (You might need to use const_cast<>, though.)
 147    */
 148   Main(int* argc, char*** argv, bool set_locale = true);
 149
 150   /// See Main(int* argc, char*** argv, bool set_locale).
 151   Main(int& argc, char**& argv, bool set_locale = true);
 152
 153
 154   virtual ~Main();
 155
 156   /// Access to the one global instance of Gtk::Main.
 157   static Gtk::Main* instance();
 158
 159   /** Start the event loop.
 160    * This begins the event loop which handles events.  No
 161    * events propagate until this has been called.  It may be
 162    * called recursively to popup dialogs
 163    */
 164   static void run();
 165
 166   /** Returns from the main loop when the window is closed.
 167    * When using this override, you should not use Gtk::Main::quit() to close
 168    * the application, but just call hide() on your Window class.
 169    *
 170    * @param window The window to show. This method will return when the window is hidden.
 171    */
 172   static void run(Window& window);
 173
 174   /** Makes the innermost invocation of the main loop return when it regains control.
 175    */
 176   static void quit();
 177
 178   static guint level();
 179
 180   //This attempts to provide the same functionality as gtk_get_option_group():
 181   /** Add a Glib::OptionGroup, for the commandline arguments recognized
 182    * by GTK+ and GDK, to a Glib::OptionContext, so that these commandline arguments will
 183    * be processed in addition to the existing commandline arguments specified by the Glib::OptionContext.
 184    *
 185    * You do not need to use this method if you pass your Glib::OptionContext to the Main constructor, because
 186    * it adds the gtk option group automatically.
 187    *
 188    * @param option_context Option Context to which the group will be added.
 189    * @param open_default_display Whether to open the default display when parsing the commandline arguments.
 190    */
 191   static void add_gtk_option_group(Glib::OptionContext& option_context, bool open_default_display = true);
 192
 193   /** Runs a single iteration of the main loop.
 194    * If no events are waiting to be processed GTK+ will block until the next event is noticed.
 195    * If you don't want to block then pass false for @a blocking or check if any events are pending with
 196    * pending() first.
 197    *
 198    * @param blocking Whether the caller must wait until the next event is noticed, or return immediately if there are no events.
 199    * @result true if quit() has been called for the innermost main loop.
 200    */
 201   static bool iteration(bool blocking = true);
 202
 203   /** Checks if any events are pending. This can be used to update the GUI and invoke timeouts etc. while doing some time intensive computation.
 204    *
 205    * Example: Updating the GUI during a long computation.
 206    * @code
 207    * // computation going on
 208    * while( Gtk::Main::events_pending() )
 209    *   Gtk::Main::iteration();
 210    *
 211    * // computation continued
 212    * @endcode
 213    *
 214    * @result true if any events are pending, false otherwise.
 215    */
 216   static bool events_pending();
 217
 218   /** Run signal
 219    * @return void
 220    */
 221   static RunSig& signal_run();
 222
 223   /** Quit signal
 224    * You can connect signal handlers to invoke actions when Gtk::Main::quit()
 225    * has been called.  Note that main loops can be nested by calling
 226    * Gtk::Main::run() recursively, therefore receiving this signal doesn't
 227    * necessarily mean the application is about to be terminated.  If you want
 228    * to receive a signal only when the last main loop quits, call connect()
 229    * with <tt>main_level&nbsp;=&nbsp;1</tt>.
 230    * @code
 231    * bool thisclass::mymethod() { return false; }
 232    * Gtk::Main::signal_quit().connect(sigc::mem_fun(this, &thisclass::mymethod));
 233    * @endcode
 234    * @return bool - @c false means callback is removed, @c true means
 235    * it'll be called again the next the main loop quits.
 236    */
 237   static QuitSig& signal_quit();
 238
 239   /** KeySnooper signal
 240    * Allows you to channel keypresses to a signal handler
 241    * without registering with the widget.
 242    *
 243    * @return KeySnooperSig A Signal to which you can connect a sigc::slot< int, Widget *, GdkEventKey * >
 244    *
 245    * It is the responsibility of the snooper to pass the keypress
 246    * to the widget, however, care must be taken that the keypress is
 247    * not passed twice.
 248    */
 249   static KeySnooperSig& signal_key_snooper();
 250
 251   // Initialize table of wrap_new functions.
 252   // Doesn't need an instance of Gtk::Main.
 253   static void init_gtkmm_internals();
 254
 255 protected:
 256   Main();
 257
 258   void init(int* argc, char*** argv, bool set_locale);
 259   // TODO: implement this to use the new Glib::OptionEntry argument parsing classes.
 260   //void init(int* argc, char*** argv, const std::string& parameter_string, const Glib::ArrayHandle<const Glib::OptionEntry&>& entries, const std::string& translation_domain);
 261
 262   virtual void run_impl();
 263   virtual void quit_impl();
 264   virtual guint level_impl();
 265   virtual bool iteration_impl(bool blocking);
 266   virtual bool events_pending_impl();
 267
 268   // Signal handlers:
 269   virtual void on_window_hide();
 270
 271   // Signal proxies:
 272   static RunSig         signal_run_;
 273   static QuitSig        signal_quit_;
 274   static KeySnooperSig  signal_key_snooper_;
 275
 276 private:
 277   static Main* instance_;
 278 };
 279
 280 } // namespace Gtk
 281
 282
 283 #endif /* _GTKMM_MAIN_H */
 284