src/ui/base-window.h

   1 /*
   2  * FileManager-Actions
   3  * A file-manager extension which offers configurable context menu actions.
   4  *
   5  * Copyright (C) 2005 The GNOME Foundation
   6  * Copyright (C) 2006-2008 Frederic Ruaudel and others (see AUTHORS)
   7  * Copyright (C) 2009-2015 Pierre Wieser and others (see AUTHORS)
   8  *
   9  * FileManager-Actions 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  * FileManager-Actions 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 GNU
  17  * General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with FileManager-Actions; see the file COPYING. If not, see
  21  * <http://www.gnu.org/licenses/>.
  22  *
  23  * Authors:
  24  *   Frederic Ruaudel <grumz@grumz.net>
  25  *   Rodrigo Moya <rodrigo@gnome-db.org>
  26  *   Pierre Wieser <pwieser@trychlos.org>
  27  *   ... and many others (see AUTHORS)
  28  */
  29
  30 #ifndef __UI_BASE_WINDOW_H__
  31 #define __UI_BASE_WINDOW_H__
  32
  33 /**
  34  * SECTION: base-window
  35  * @title: BaseWindow
  36  * @short_description: the BaseWindow base window class definition
  37  * @include: ui/base-window.h
  38  *
  39  * This is a base class which manages a Gtk+ toplevel.
  40  *
  41  * One global UI manager is allocated at #BaseWindow class level.
  42  * Each window may have its own, provided that it is willing to
  43  * reinstanciate a new builder each time the window is opened.
  44  *
  45  *   Cf. http://bugzilla.gnome.org/show_bug.cgi?id=589746 against
  46  *   Gtk+ 2.16 : a GtkFileChooserWidget embedded in a GtkAssistant is
  47  *   not displayed when run more than once. As a work-around, reload
  48  *   the XML ui in a new builder each time we run an assistant !
  49  *
  50  * Note that having its own builder implies loading in it the required
  51  * XML file which holds the needed UI definition, and so even if this
  52  * same XML file has already been load in the common builder.
  53  *
  54  * The common #BaseBuilder is never g_object_unref(), so the
  55  * embedded Gtk toplevels are only destroyed when quitting the
  56  * program.
  57  */
  58
  59 #include <gtk/gtk.h>
  60
  61 G_BEGIN_DECLS
  62
  63 #define BASE_TYPE_WINDOW                ( base_window_get_type())
  64 #define BASE_WINDOW( object )           ( G_TYPE_CHECK_INSTANCE_CAST( object, BASE_TYPE_WINDOW, BaseWindow ))
  65 #define BASE_WINDOW_CLASS( klass )      ( G_TYPE_CHECK_CLASS_CAST( klass, BASE_TYPE_WINDOW, BaseWindowClass ))
  66 #define BASE_IS_WINDOW( object )        ( G_TYPE_CHECK_INSTANCE_TYPE( object, BASE_TYPE_WINDOW ))
  67 #define BASE_IS_WINDOW_CLASS( klass )   ( G_TYPE_CHECK_CLASS_TYPE(( klass ), BASE_TYPE_WINDOW ))
  68 #define BASE_WINDOW_GET_CLASS( object ) ( G_TYPE_INSTANCE_GET_CLASS(( object ), BASE_TYPE_WINDOW, BaseWindowClass ))
  69
  70 typedef struct _BaseWindowClassPrivate  BaseWindowClassPrivate;
  71
  72 typedef struct _BaseWindowPrivate       BaseWindowPrivate;
  73
  74 typedef struct {
  75         /*< private >*/
  76         GObject                 parent;
  77         BaseWindowPrivate      *private;
  78 }
  79         BaseWindow;
  80
  81 /**
  82  * BaseWindowClass:
  83  * @initialize_gtk_toplevel: initialize the toplevel GtkWindow (once)
  84  * @initialize_base_window:  initialize the BaseWindow (each time the
  85  *                           window is displayed)
  86  * @all_widgets_showed:      all widgets have been showed
  87  * @run:                     run the dialog box loop
  88  *
  89  * This defines the virtual method a derived class may, should or must implement.
  90  */
  91 typedef struct {
  92         /*< private >*/
  93         GObjectClass            parent;
  94         BaseWindowClassPrivate *private;
  95
  96         /*< public >*/
  97         /**
  98          * initialize_gtk_toplevel:
  99          * @window: this #BaseWindow instance.
 100          * @toplevel: the GtkWindow being initialized.
 101          *
 102          * This virtual method is invoked after the toplevel GtkWindow has been
 103          * allocated and built for the firt time by the GtkBuilder, after all
 104          * connected signal handlers have themselves run.
 105          *
 106          * The derived class should invoke the virtual method of its parent class
 107          * at the end of its processing.
 108          *
 109          * The BaseWindow class ensures that each created instance has its Gtk
 110          * toplevel - if it has been successfully loaded - initialized when
 111          * returning from instanciation.
 112          * The instance has nonetheless still to check if the Gtk toplevel has
 113          * actually been built, and to initialize and show it before anything
 114          * useful may occur (see base_window_init()).
 115          *
 116          * Note that initialization process may fall if the XML UI definition cannot
 117          * be loaded in memory, or if the required Gtk toplevel cannot be found.
 118          * Derived class has so to make sure that a Gtk toplevel actually exists
 119          * before continuing. Calling base_window_init() on the instance may
 120          * do this check.
 121          */
 122         void ( *initialize_gtk_toplevel )( BaseWindow *window, GtkWindow *toplevel );
 123
 124         /**
 125          * initialize_base_window:
 126          * @window: this #BaseWindow instance.
 127          *
 128          * This virtual method is invoked as the first phase of base_window_init(),
 129          * after having checked for the presence of a GtkWindow toplevel, before
 130          * actually displaying the widget, and after all connected signal handlers
 131          * have themselves run.
 132          *
 133          * The derived class should invoke the virtual method of its parent class
 134          * at the end of its processing.
 135          *
 136          * The BaseWindow base class implementation of this method, which is
 137          * so called last, just does nothing.
 138          */
 139         void ( *initialize_base_window ) ( BaseWindow *window );
 140
 141         /**
 142          * show_widgets:
 143          * @window: this #BaseWindow instance.
 144          *
 145          * This virtual method is invoked at the end of initialization process,
 146          * after all connected signal handlers have themselves run.
 147          *
 148          * The derived class should invoke the virtual method of its parent class
 149          * at the end of its processing.
 150          *
 151          * The BaseWindow base class implementation of this method, which is
 152          * so called last, will call gtk_widget_show_all() on the Gtk toplevel.
 153          */
 154         void ( *show_widgets )           ( BaseWindow *window );
 155
 156         /**
 157          * run:
 158          * @window: this #BaseWindow instance.
 159          * @dialog: the toplevel #GtkWindow.
 160          *
 161          * Invoked when it is time to run the main loop for the toplevel if
 162          * the derived class does not rely on the global main loop.
 163          *
 164          * The #BaseWindow -derived instance should implement this method if
 165          * it wants do something special.
 166          *
 167          * Returns: the exit code as set by the derived class.
 168          */
 169         int  ( *run )                    ( BaseWindow *window );
 170 }
 171         BaseWindowClass;
 172
 173 /**
 174  * Properties defined by the BaseWindow class.
 175  * They should be provided at object instanciation time.
 176  *
 177  * Instanciation time requires:
 178  * - MAIN_WINDOW
 179  * - XMLUI_FILENAME
 180  * - TOPLEVEL_NAME
 181  * - HAS_OWN_BUILDER
 182  */
 183 #define BASE_PROP_MAIN_WINDOW                                   "base-prop-window-main-window"
 184 #define BASE_PROP_XMLUI_FILENAME                                "base-prop-window-xmlui-filename"
 185 #define BASE_PROP_HAS_OWN_BUILDER                               "base-prop-window-has-own-builder"
 186 #define BASE_PROP_TOPLEVEL_NAME                                 "base-prop-window-toplevel-name"
 187 #define BASE_PROP_WSP_NAME                                              "base-prop-window-wsp-name"
 188 #define BASE_PROP_DESTROY_ON_DISPOSE                    "base-prop-window-destroy-on-dispose"
 189
 190 /**
 191  * Signals defined by the BaseWindow class.
 192  *
 193  * All signals of this class share the same behavior:
 194  *
 195  * - the message is sent to all derived classes, which are free to
 196  *   connect to the signal in order to implement their own code;
 197  *
 198  * - finally, the default class handler invokes the corresponding
 199  *   virtual method of the derived class. The derived class should
 200  *   call the parent class method at the end of its implementation.
 201  *
 202  * This way, each class is free to choose to implement the action, either
 203  * as a signal handler or as a virtual method if it is a class derived from
 204  * BaseWindow.
 205  *
 206  * See each signal description for detailed informations on exactly
 207  * when the signal is emitted.
 208  */
 209 #define BASE_SIGNAL_INITIALIZE_GTK                              "base-signal-window-initialize-gtk"
 210 #define BASE_SIGNAL_INITIALIZE_WINDOW                   "base-signal-window-initialize-window"
 211 #define BASE_SIGNAL_SHOW_WIDGETS                                "base-signal-window-show-widgets"
 212
 213 GType                 base_window_get_type                ( void );
 214
 215 gboolean              base_window_init                    ( BaseWindow *window );
 216 int                   base_window_run                     ( BaseWindow *window );
 217
 218 #ifdef FMA_MAINTAINER_MODE
 219 void                  base_window_dump_children           ( const BaseWindow *window );
 220 #endif
 221
 222 GtkApplication       *base_window_get_application         ( const BaseWindow *window );
 223 GtkApplicationWindow *base_window_get_main_window         ( const BaseWindow *window );
 224 GtkWindow            *base_window_get_gtk_toplevel        ( const BaseWindow *window );
 225 GtkWindow            *base_window_get_gtk_toplevel_by_name( const BaseWindow *window,
 226                                                                                                                                 const gchar *name );
 227 GtkWidget            *base_window_get_widget              ( const BaseWindow *window,
 228                                                                                                                                 const gchar *name );
 229
 230 void                  base_window_display_error_dlg       ( const BaseWindow *parent,
 231                                                                                                                                 const gchar *primary,
 232                                                                                                                                 const gchar *secondary );
 233 gboolean              base_window_display_yesno_dlg       ( const BaseWindow *parent,
 234                                                                                                                                 const gchar *primary,
 235                                                                                                                                 const gchar *secondary );
 236 void                  base_window_display_message_dlg     ( const BaseWindow *parent,
 237                                                                                                                                 GSList *message );
 238
 239 gulong                base_window_signal_connect          ( BaseWindow *window,
 240                                                                                                                                 GObject *instance,
 241                                                                                                                                 const gchar *signal,
 242                                                                                                                                 GCallback fn );
 243 gulong                base_window_signal_connect_after    ( BaseWindow *window,
 244                                                                                                                                 GObject *instance,
 245                                                                                                                                 const gchar *signal,
 246                                                                                                                                 GCallback fn );
 247 gulong                base_window_signal_connect_by_name  ( BaseWindow *window,
 248                                                                                                                                 const gchar *name,
 249                                                                                                                                 const gchar *signal,
 250                                                                                                                                 GCallback fn );
 251 gulong                base_window_signal_connect_with_data( BaseWindow *window,
 252                                                                                                                                 GObject *instance,
 253                                                                                                                                 const gchar *signal,
 254                                                                                                                                 GCallback fn,
 255                                                                                                                                 void *user_data );
 256 void                  base_window_signal_disconnect       ( BaseWindow *window,
 257                                                                                                                                 gulong handler_id );
 258
 259 G_END_DECLS
 260
 261 #endif /* __UI_BASE_WINDOW_H__ */