src/nact/base-window.h

   1 /*
   2  * Nautilus-Actions
   3  * A Nautilus extension which offers configurable context menu actions.
   4  *
   5  * Copyright (C) 2005 The GNOME Foundation
   6  * Copyright (C) 2006, 2007, 2008 Frederic Ruaudel and others (see AUTHORS)
   7  * Copyright (C) 2009, 2010, 2011 Pierre Wieser and others (see AUTHORS)
   8  *
   9  * This Program is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU General Public License as
  11  * published by the Free Software Foundation; either version 2 of
  12  * the License, or (at your option) any later version.
  13  *
  14  * This Program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public
  20  * License along with this Library; see the file COPYING.  If not,
  21  * write to the Free Software Foundation, Inc., 59 Temple Place,
  22  * Suite 330, Boston, MA 02111-1307, USA.
  23  *
  24  * Authors:
  25  *   Frederic Ruaudel <grumz@grumz.net>
  26  *   Rodrigo Moya <rodrigo@gnome-db.org>
  27  *   Pierre Wieser <pwieser@trychlos.org>
  28  *   ... and many others (see AUTHORS)
  29  */
  30
  31 #ifndef __BASE_WINDOW_H__
  32 #define __BASE_WINDOW_H__
  33
  34 /**
  35  * SECTION: base-window
  36  * @title: BaseWindow
  37  * @short_description: the BaseWindow base window class definition
  38  * @include: base-window.h
  39  *
  40  * This is a base class which encapsulates a Gtk+ windows.
  41  * It works together with the BaseApplication class to run a Gtk+
  42  * application.
  43  *
  44  * Note that two properties of #BaseApplication may be overriden on a
  45  * per-#BaseWindow basis. These are :
  46  *
  47  * - the #GtkBuilder UI manager
  48  *   the application has one global UI manager, but each window may
  49  *   have its own, provided that it is willing to reallocate a new
  50  *   one each time the window is opened.
  51  *
  52  *   Cf. http://bugzilla.gnome.org/show_bug.cgi?id=589746 against
  53  *   Gtk+ 2.16 : a GtkFileChooserWidget embedded in a GtkAssistant is
  54  *   not displayed when run more than once. As a work-around, reload
  55  *   the XML ui each time we run an assistant !
  56  *
  57  * - the filename which handled the window XML definition
  58  *   the application provides with one global default file, but each
  59  *   window may decide to provide its own.
  60  *
  61  *   Cf. http://bugzilla.gnome.org/show_bug.cgi?id=579345 against
  62  *   GtkBuilder : duplicate ids are no more allowed in a file. But we
  63  *   require this ability to have the same widget definition
  64  *   (ActionsList) in main window and export assistant.
  65  *   As a work-around, we have XML definition of export assistant in
  66  *   its own file.
  67  *   Another work-around could have be to let the IActionsList
  68  *   interface asks from the actual widget name to its implementor...
  69  *
  70  *   Sharing a same XML UI definition file implies sharing the same builder.
  71  */
  72
  73 #include "base-application.h"
  74
  75 G_BEGIN_DECLS
  76
  77 #define BASE_WINDOW_TYPE                ( base_window_get_type())
  78 #define BASE_WINDOW( object )           ( G_TYPE_CHECK_INSTANCE_CAST( object, BASE_WINDOW_TYPE, BaseWindow ))
  79 #define BASE_WINDOW_CLASS( klass )      ( G_TYPE_CHECK_CLASS_CAST( klass, BASE_WINDOW_TYPE, BaseWindowClass ))
  80 #define BASE_IS_WINDOW( object )        ( G_TYPE_CHECK_INSTANCE_TYPE( object, BASE_WINDOW_TYPE ))
  81 #define BASE_IS_WINDOW_CLASS( klass )   ( G_TYPE_CHECK_CLASS_TYPE(( klass ), BASE_WINDOW_TYPE ))
  82 #define BASE_WINDOW_GET_CLASS( object ) ( G_TYPE_INSTANCE_GET_CLASS(( object ), BASE_WINDOW_TYPE, BaseWindowClass ))
  83
  84 typedef struct _BaseWindowPrivate       BaseWindowPrivate;
  85
  86 typedef struct {
  87         /*< private >*/
  88         GObject            parent;
  89         BaseWindowPrivate *private;
  90 }
  91         BaseWindow;
  92
  93 typedef struct _BaseWindowClassPrivate  BaseWindowClassPrivate;
  94
  95 /**
  96  * BaseWindowClass:
  97  * @initial_load_toplevel: initialize the toplevel GtkWindow
  98  * @runtime_init_toplevel:
  99  * @all_widgets_showed:
 100  * @dialog_response:
 101  * @delete_event:
 102  * @get_toplevel_name:
 103  * @get_iprefs_window_id:
 104  * @get_ui_filename:
 105  * @is_willing_to_quit:
 106  *
 107  * This defines the virtual method a derived class may, should or must implement.
 108  */
 109 typedef struct {
 110         /*< private >*/
 111         GObjectClass            parent;
 112         BaseWindowClassPrivate *private;
 113
 114         /*< public >*/
 115         /**
 116          * initial_load_toplevel:
 117          * @window: this #BaseWindow instance.
 118          * @user_data: not used
 119          *
 120          * Invoked when the toplevel GtkWindow is allocated for the firt time
 121          * by the GtkBuilder, after all connected handlers have themselves run.
 122          *
 123          * The BaseWindow class takes care of successively invoking the
 124          * initial_load_toplevel() method of each derived class, starting from
 125          * the topmost derived class, up to the BaseWindow itself.
 126          *
 127          * The BaseWindow base class implementation of this method, which is
 128          * so called last, set this GtkWindow toplevel window transient for
 129          * its parent window.
 130          */
 131         void              ( *initial_load_toplevel )( BaseWindow *window, gpointer user_data );
 132
 133         /**
 134          * runtime_init_toplevel:
 135          * @window: this #BaseWindow instance.
 136          * @user_data: not used
 137          *
 138          * Invoked after the GtkWindow toplevel has been initialized, before
 139          * actually dsplaying the widget, and after all connected handlers
 140          * have themselves run.
 141          *
 142          * The BaseWindow class takes care of successively invoking the
 143          * runtime_init_toplevel() method of each derived class, starting from
 144          * the topmost derived class, up to the BaseWindow itself.
 145          *
 146          * The BaseWindow base class implementation of this method, which is
 147          * so called last, reset last size and position of the window.
 148          */
 149         void              ( *runtime_init_toplevel )( BaseWindow *window, gpointer user_data );
 150
 151         /**
 152          * all_widgets_showed:
 153          * @window: this #BaseWindow instance.
 154          */
 155         void              ( *all_widgets_showed )   ( BaseWindow *window, gpointer user_data );
 156
 157         /**
 158          * dialog_response:
 159          * @window: this #BaseWindow instance.
 160          */
 161         gboolean          ( *dialog_response )      ( GtkDialog *dialog, gint code, BaseWindow *window );
 162
 163         /**
 164          * delete_event:
 165          * @window: this #BaseWindow instance.
 166          *
 167          * The #BaseWindow class connects to the "delete-event" signal,
 168          * and transforms it into a virtual function. The derived class
 169          * can so implement the virtual function, without having to take
 170          * care of the signal itself.
 171          */
 172         gboolean          ( *delete_event )         ( BaseWindow *window, GtkWindow *toplevel, GdkEvent *event );
 173
 174         /**
 175          * window_get_toplevel_name:
 176          * @window: this #BaseWindow instance.
 177          *
 178          * Pure virtual function.
 179          */
 180         gchar *           ( *get_toplevel_name )    ( const BaseWindow *window );
 181
 182         /**
 183          * get_iprefs_window_id:
 184          * @window: this #BaseWindow instance.
 185          *
 186          * Asks the derived class for the string which must be used to
 187          * store last size and position of the window in GConf preferences.
 188          *
 189          * This delegates to #BaseWindow-derived classes the NactIPrefs
 190          * interface virtual function.
 191          */
 192         gchar *           ( *get_iprefs_window_id ) ( const BaseWindow *window );
 193
 194         /**
 195          * get_ui_filename:
 196          * @window: this #BaseWindow instance.
 197          *
 198          * Asks the derived class for the filename of the XML definition of
 199          * the user interface for this window. This XML definition must be
 200          * suitable in order to be loaded via GtkBuilder.
 201          *
 202          * Defaults to application UI filename.
 203          *
 204          * Returns: the filename of the XML definition, to be g_free() by
 205          * the caller.
 206          */
 207         gchar *           ( *get_ui_filename )      ( const BaseWindow *window );
 208
 209         /**
 210          * is_willing_to_quit:
 211          * @window: this #BaseWindow instance.
 212          *
 213          * Asks the derived class for the filename of the XML definition of
 214          * the user interface for this window. This XML definition must be
 215          * suitable in order to be loaded via GtkBuilder.
 216          *
 217          * Defaults to application UI filename.
 218          *
 219          * Returns: the filename of the XML definition, to be g_free() by
 220          * the caller.
 221          */
 222         gboolean          ( *is_willing_to_quit )   ( const BaseWindow *window );
 223 }
 224         BaseWindowClass;
 225
 226 /**
 227  * Properties defined by the BaseWindow class.
 228  * They should be provided at object instanciation time.
 229  */
 230 #define BASE_PROP_PARENT                                                "base-window-parent"
 231 #define BASE_PROP_APPLICATION                                   "base-window-application"
 232 #define BASE_PROP_XMLUI_FILENAME                                "base-window-xmlui-filename"
 233 #define BASE_PROP_HAS_OWN_BUILDER                               "base-window-has-own-builder"
 234 #define BASE_PROP_TOPLEVEL_NAME                                 "base-window-toplevel-name"
 235
 236 /**
 237  * Signals defined by the BaseWindow class.
 238  *
 239  * All signals of this class have the same behavior:
 240  *
 241  * - the message is sent to all derived classes, which are free to
 242  *   connect to the signal in order to implement their own code;
 243  *
 244  * - finally, the default class handler points to a function
 245  *   which successively invokes the corresponding virtual method of each
 246  *   derived class.
 247  *
 248  * This way, each class is free to choose to implement the action, either
 249  * as a signal handler or as a virtual method if it is a class derived from
 250  * BaseWindow.
 251  */
 252 #define BASE_SIGNAL_INITIALIZE_GTK                              "base-window-initialize-gtk"
 253 #define BASE_SIGNAL_INITIALIZE_WINDOW                   "base-window-initialize-window"
 254 #define BASE_SIGNAL_ALL_WIDGETS_SHOWED                  "base-window-all-widgets-showed"
 255
 256 GType            base_window_get_type( void );
 257
 258 gboolean         base_window_init( BaseWindow *window );
 259 int              base_window_run ( BaseWindow *window );
 260
 261 BaseApplication *base_window_get_application         ( const BaseWindow *window );
 262 BaseWindow      *base_window_get_parent              ( const BaseWindow *window );
 263 GtkWindow       *base_window_get_gtk_toplevel        ( const BaseWindow *window );
 264 GtkWindow       *base_window_get_gtk_toplevel_by_name( const BaseWindow *window, const gchar *name );
 265 GtkWidget       *base_window_get_widget              ( const BaseWindow *window, const gchar *name );
 266
 267 gboolean         base_window_is_willing_to_quit      ( const BaseWindow *window );
 268
 269 void             base_window_display_error_dlg       ( const BaseWindow *parent, const gchar *primary, const gchar *secondary );
 270 gboolean         base_window_display_yesno_dlg       ( const BaseWindow *parent, const gchar *primary, const gchar *secondary );
 271 void             base_window_display_message_dlg     ( const BaseWindow *parent, GSList *message );
 272
 273 gulong           base_window_signal_connect          ( BaseWindow *window, GObject *instance, const gchar *signal, GCallback fn );
 274 gulong           base_window_signal_connect_after    ( BaseWindow *window, GObject *instance, const gchar *signal, GCallback fn );
 275 gulong           base_window_signal_connect_by_name  ( BaseWindow *window, const gchar *name, const gchar *signal, GCallback fn );
 276 gulong           base_window_signal_connect_with_data( BaseWindow *window, GObject *instance, const gchar *signal, GCallback fn, void *user_data );
 277
 278 G_END_DECLS
 279
 280 #endif /* __BASE_WINDOW_H__ */