src/nact/base-application.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_APPLICATION_H__
  32 #define __BASE_APPLICATION_H__
  33
  34 /**
  35  * SECTION: base-application
  36  * @title: BaseApplication
  37  * @short_description: The Base Application application base class definition
  38  * @include: base-application.h
  39  *
  40  * #BaseApplication is the base class for the application part of Gtk programs.
  41  * It aims at providing all common services. It interacts with #BaseBuilder
  42  * and #BaseWindow classes.
  43  *
  44  * #BaseApplication is a pure virtual class. A Gtk program should derive
  45  * its own class from #BaseApplication, and instantiate it in its main()
  46  * program entry point.
  47  *
  48  * <example>
  49  *   <programlisting>
  50  *     #include "my-application.h"
  51  *
  52  *     int
  53  *     main( int argc, char **argv )
  54  *     {
  55  *         MyApplication *appli;
  56  *         int code;
  57  *
  58  *         appli = my_application_new_with_args( argc, argv );
  59  *         code = base_appliction_run( BASE_APPLICATION( appli ));
  60  *         g_object_unref( appli );
  61  *
  62  *         return( code );
  63  *     }
  64  *   </programlisting>
  65  * </example>
  66  */
  67
  68 #include "base-builder.h"
  69
  70 G_BEGIN_DECLS
  71
  72 #define BASE_APPLICATION_TYPE                ( base_application_get_type())
  73 #define BASE_APPLICATION( object )           ( G_TYPE_CHECK_INSTANCE_CAST( object, BASE_APPLICATION_TYPE, BaseApplication ))
  74 #define BASE_APPLICATION_CLASS( klass )      ( G_TYPE_CHECK_CLASS_CAST( klass, BASE_APPLICATION_TYPE, BaseApplicationClass ))
  75 #define BASE_IS_APPLICATION( object )        ( G_TYPE_CHECK_INSTANCE_TYPE( object, BASE_APPLICATION_TYPE ))
  76 #define BASE_IS_APPLICATION_CLASS( klass )   ( G_TYPE_CHECK_CLASS_TYPE(( klass ), BASE_APPLICATION_TYPE ))
  77 #define BASE_APPLICATION_GET_CLASS( object ) ( G_TYPE_INSTANCE_GET_CLASS(( object ), BASE_APPLICATION_TYPE, BaseApplicationClass ))
  78
  79 typedef struct _BaseApplicationPrivate       BaseApplicationPrivate;
  80
  81 typedef struct {
  82         /*< private >*/
  83         GObject                 parent;
  84         BaseApplicationPrivate *private;
  85 }
  86         BaseApplication;
  87
  88 typedef struct _BaseApplicationClassPrivate  BaseApplicationClassPrivate;
  89
  90 /**
  91  * BaseApplicationClass:
  92  * @manage_options:  manage the command-line arguments.
  93  * @main_window_new: open and run the first (main) window of the application.
  94  *
  95  * This defines the virtual method a derived class may, should or must implement.
  96  */
  97 typedef struct {
  98         /*< private >*/
  99         GObjectClass                 parent;
 100         BaseApplicationClassPrivate *private;
 101
 102         /*< public >*/
 103         /**
 104          * manage_options:
 105          * @appli: this #BaseApplication -derived instance.
 106          * @code:  a pointer to an integer that the derived application may
 107          *         set as the exit code of the program if it chooses to stop
 108          *         the execution; the code set here will be ignored if execution
 109          *         is allowed to continue.
 110          *
 111          * This is invoked by the BaseApplication base class, after arguments
 112          * in the command-line have been processed by gtk_init_with_args()
 113          * function.
 114          *
 115          * This let the derived class an opportunity to manage command-line
 116          * arguments. Unless it decides to stop the execution of the program,
 117          * the derived class should call the parent class method in order to
 118          * let it manage its own options.
 119          *
 120          * Returns: %TRUE to continue execution, %FALSE to stop it.
 121          */
 122         gboolean  ( *manage_options ) ( const BaseApplication *appli, int *code );
 123
 124         /**
 125          * main_window_new:
 126          * @appli: this #BaseApplication -derived instance.
 127          *
 128          * This is invoked by the BaseApplication base class to let the derived
 129          * class do its own initializations and create its main window.
 130          *
 131          * This is a pure virtual method. Only the most derived class
 132          * main_window_new() method is invoked.
 133          *
 134          * Returns: the main window of the application, as a #BaseWindow
 135          * -derived object. It may or may not have already been initialized.
 136          */
 137         GObject * ( *main_window_new )( const BaseApplication *appli, int *code );
 138 }
 139         BaseApplicationClass;
 140
 141 /**
 142  * Properties defined by the BaseApplication class.
 143  * They should be provided at object instantiation time.
 144  *
 145  * @BASE_PROP_ARGC:             count of arguments in command-line.
 146  * @BASE_PROP_ARGV:             array of command-line arguments.
 147  * @BASE_PROP_OPTIONS:          array of command-line options descriptions.
 148  * @BASE_PROP_APPLICATION_NAME: application name.
 149  * @BASE_PROP_DESCRIPTION:      short description.
 150  * @BASE_PROP_ICON_NAME:        icon name.
 151  * @BASE_PROP_UNIQUE_APP_NAME:  unique name of the application (if apply)
 152  */
 153 #define BASE_PROP_ARGC                                          "base-application-argc"
 154 #define BASE_PROP_ARGV                                          "base-application-argv"
 155 #define BASE_PROP_OPTIONS                                       "base-application-options"
 156 #define BASE_PROP_APPLICATION_NAME                      "base-application-name"
 157 #define BASE_PROP_DESCRIPTION                           "base-application-description"
 158 #define BASE_PROP_ICON_NAME                                     "base-application-icon-name"
 159 #define BASE_PROP_UNIQUE_APP_NAME                       "base-application-unique-app-name"
 160
 161 typedef enum {
 162         BASE_EXIT_CODE_START_FAIL = -1,
 163         BASE_EXIT_CODE_OK = 0,
 164         BASE_EXIT_CODE_ARGS,
 165         BASE_EXIT_CODE_UNIQUE_APP,
 166         BASE_EXIT_CODE_MAIN_WINDOW,
 167         BASE_EXIT_CODE_INIT_FAIL,
 168         BASE_EXIT_CODE_PROGRAM,
 169         /*
 170          * BaseApplication -derived class may use program return codes
 171          * starting with this value
 172          */
 173         BASE_EXIT_CODE_USER_APP = 32
 174 }
 175         BaseExitCode;
 176
 177 GType        base_application_get_type( void );
 178
 179 int          base_application_run( BaseApplication *application );
 180
 181 gchar       *base_application_get_application_name( const BaseApplication *application );
 182 BaseBuilder *base_application_get_builder         ( const BaseApplication *application );
 183
 184 G_END_DECLS
 185
 186 #endif /* __BASE_APPLICATION_H__ */