libgnome-gnome-program.html

最新gtk中文资料集

<a class="indexterm" name="id2786420"></a><pre class="programlisting">typedef struct {
    const char *name;
    const char *version;
    const char *description;
    GnomeModuleRequirement *requirements; /* last element has NULL version */

    GnomeModuleHook instance_init;
    GnomeModuleHook pre_args_parse, post_args_parse;

#ifdef GNOME_DISABLE_DEPRECATED
    struct poptOption *_options;
#else
    struct poptOption *options;
#endif

    GnomeModuleInitHook init_pass;

    GnomeModuleClassInitHook class_init;

    const char *opt_prefix;
    GnomeModuleGetGOptionGroupFunc get_goption_group_func;
} GnomeModuleInfo;
</pre>
<p>
A structure containing information about a module. This contains descriptive
information about the module, as well as how to initialise it and what its
dependencies are (chained via the <em class="parameter"><code>requirements</code></em> parameter).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term">const&#160;char&#160;*<em class="structfield"><code>name</code></em>;</span></td>
<td>The module name.
</td>
</tr>
<tr>
<td>
<span class="term">const&#160;char&#160;*<em class="structfield"><code>version</code></em>;</span></td>
<td>The module's version string.
</td>
</tr>
<tr>
<td>
<span class="term">const&#160;char&#160;*<em class="structfield"><code>description</code></em>;</span></td>
<td>A string describing the module (can be <a
href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"
><code class="literal">NULL</code></a>).
</td>
</tr>
<tr>
<td>
<span class="term"><a href="libgnome-gnome-program.html#GnomeModuleRequirement">GnomeModuleRequirement</a>&#160;*<em class="structfield"><code>requirements</code></em>;</span></td>
<td>A pointer to an array of modules that are required by this
module. The last module in the array should have its required_version field set
to <a
href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"
><code class="literal">NULL</code></a>.
</td>
</tr>
<tr>
<td>
<span class="term"><a href="libgnome-gnome-program.html#GnomeModuleHook">GnomeModuleHook</a>&#160;<em class="structfield"><code>instance_init</code></em>;</span></td>
<td>A function to call to initialise an instance of this module
(can be <a
href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"
><code class="literal">NULL</code></a>).
</td>
</tr>
<tr>
<td>
<span class="term"><a href="libgnome-gnome-program.html#GnomeModuleHook">GnomeModuleHook</a>&#160;<em class="structfield"><code>pre_args_parse</code></em>;</span></td>
<td>A function to call before parsing the arguments for this
module (can be <a
href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"
><code class="literal">NULL</code></a>).
</td>
</tr>
<tr>
<td>
<span class="term"><a href="libgnome-gnome-program.html#GnomeModuleHook">GnomeModuleHook</a>&#160;<em class="structfield"><code>post_args_parse</code></em>;</span></td>
<td>A function to call after parsing the arguments for this
module (can be <a
href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"
><code class="literal">NULL</code></a>).
</td>
</tr>
<tr>
<td>
<span class="term"><a href="libgnome-gnome-program.html#GnomeModuleClassInitHook">GnomeModuleClassInitHook</a>&#160;<em class="structfield"><code>class_init</code></em>;</span></td>
<td>A function to call to initialise this module prior to creating any
instances (can be <a
href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"
><code class="literal">NULL</code></a>).
</td>
</tr>
<tr>
<td>
<span class="term">const&#160;char&#160;*<em class="structfield"><code>opt_prefix</code></em>;</span></td>
<td>Unused.
</td>
</tr>
<tr>
<td>
<span class="term">GnomeModuleGetGOptionGroupFunc&#160;<em class="structfield"><code>get_goption_group_func</code></em>;</span></td>
<td>A function which must return a non-<a
href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"
><code class="literal">NULL</code></a> <a
href="/usr/share/gtk-doc/html/glib/glib-Commandline-option-parser.html#GOptionGroup"
><span class="type">GOptionGroup</span></a>,
which will be added to the <a href="libgnome-gnome-program.html#GnomeProgram"><span class="type">GnomeProgram</span></a> s <a
href="/usr/share/gtk-doc/html/glib/glib-Commandline-option-parser.html#GOptionContext"
><span class="type">GOptionContext</span></a> during
#<a href="libgnome-gnome-program.html#gnome-program-init"><code class="function">gnome_program_init()</code></a>.

</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2786787"></a><h3>
<a name="GnomeModuleRequirement"></a>GnomeModuleRequirement</h3>
<a class="indexterm" name="id2786799"></a><pre class="programlisting">typedef struct {
    const char *required_version;
    const GnomeModuleInfo *module_info;
} GnomeModuleRequirement;
</pre>
<p>
A structure which allows a module to specify the minimum required versions of
modules it depends upon.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term">const&#160;char&#160;*<em class="structfield"><code>required_version</code></em>;</span></td>
<td>The version required by the parent module.
</td>
</tr>
<tr>
<td>
<span class="term">const&#160;<a href="libgnome-gnome-program.html#GnomeModuleInfo">GnomeModuleInfo</a>&#160;*<em class="structfield"><code>module_info</code></em>;</span></td>
<td>A <a href="libgnome-gnome-program.html#GnomeModuleInfo"><span class="type">GnomeModuleInfo</span></a> structure detailing the required module.

</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2786875"></a><h3>
<a name="GnomeModuleInitHook"></a>GnomeModuleInitHook ()</h3>
<a class="indexterm" name="id2786888"></a><pre class="programlisting">void        (*GnomeModuleInitHook)          (const <a href="libgnome-gnome-program.html#GnomeModuleInfo">GnomeModuleInfo</a> *mod_info);</pre>
<p>
A function that will be called to allow a module to do any pre-initialisation
it might need to do prior to having arguments parsed by the controlling parent
module (the parent will do the argument parsing for all modules in the
hierarchy).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>mod_info</code></em>&#160;:</span></td>
<td>The current module.


</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2786939"></a><h3>
<a name="GnomeModuleClassInitHook"></a>GnomeModuleClassInitHook ()</h3>
<a class="indexterm" name="id2786952"></a><pre class="programlisting">void        (*GnomeModuleClassInitHook)     (GnomeProgramClass *klass,
                                             const <a href="libgnome-gnome-program.html#GnomeModuleInfo">GnomeModuleInfo</a> *mod_info);</pre>
<p>
A function called to perform any class specific setup that is required by each
module.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>klass</code></em>&#160;:</span></td>
<td>The class of the parent module (which could be this module's class).
This will usually be <span class="type">GnomeProgramClass</span>.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>mod_info</code></em>&#160;:</span></td>
<td>The current module.


</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2787032"></a><h3>
<a name="GnomeModuleHook"></a>GnomeModuleHook ()</h3>
<a class="indexterm" name="id2787044"></a><pre class="programlisting">void        (*GnomeModuleHook)              (<a href="libgnome-gnome-program.html#GnomeProgram">GnomeProgram</a> *program,
                                             <a href="libgnome-gnome-program.html#GnomeModuleInfo">GnomeModuleInfo</a> *mod_info);</pre>
<p>
A function that is called to perform some intialisation in a module (which
could be either the main init function or the pre or post argument parsing
phase).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>program</code></em>&#160;:</span></td>
<td>The <a href="libgnome-gnome-program.html#GnomeProgram"><span class="type">GnomeProgram</span></a> instance which is being initialised.
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>mod_info</code></em>&#160;:</span></td>
<td>The current module's <a href="libgnome-gnome-program.html#GnomeModuleInfo"><span class="type">GnomeModuleInfo</span></a> structure.


</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2787133"></a><h3>
<a name="gnome-program-init"></a>gnome_program_init ()</h3>
<a class="indexterm" name="id2787146"></a><pre class="programlisting"><a href="libgnome-gnome-program.html#GnomeProgram">GnomeProgram</a>* gnome_program_init            (const char *app_id,
                                             const char *app_version,
                                             const <a href="libgnome-gnome-program.html#GnomeModuleInfo">GnomeModuleInfo</a> *module_info,
                                             int argc,
                                             char **argv,
                                             const char *first_property_name,
                                             ...);</pre>
<p>
Initialises the current GNOME libraries for use by the application.</p>
<p>
Every GNOME application will need to call this function (or
<a href="libgnome-gnome-program.html#gnome-program-initv"><code class="function">gnome_program_initv()</code></a>) early in its lifetime to initialize the various GNOME
libraries in a consistent fashion. This function is very flexible in allowing
the user to specify which modules should be initialised and any special
paramter values that should be passed to these modules (along with processing
commandline options).
</p>
<p>
It loads the specified <em class="parameter"><code>module_info</code></em>, which is normally <a href="libgnome-gnome-init.html#LIBGNOME-MODULE:CAPS"><span class="type">LIBGNOME_MODULE</span></a> or
<a
href="/usr/share/gtk-doc/html/libgnomeui/libgnomeui-gnome-ui-init.html#LIBGNOMEUI-MODULE:CAPS"
><span class="type">LIBGNOMEUI_MODULE</span></a> and pulls in all the dependencies.  Programs that are not
running in setuid or setgid mode will also load modules specified in the
<em class="parameter"><code>--load-modules</code></em> and also in the <em class="parameter"><code>GNOME_MODULES</code></em> environment variable.
</p>
<p>
After setting up the module loading, this function then calls (in order)
<a href="libgnome-gnome-program.html#gnome-program-preinit"><code class="function">gnome_program_preinit()</code></a>, <a href="libgnome-gnome-program.html#gnome-program-parse-args"><code class="function">gnome_program_parse_args()</code></a> and
<a href="libgnome-gnome-program.html#gnome-program-postinit"><code class="function">gnome_program_postinit()</code></a>.
</p>
<p>The following example shows how one might initialise a typical program
using a goption table that is defined elsewhere.
</p>
<div class="example">
<a name="id2787327"></a><p class="title"><b>Example&#160;1.&#160;Initializing a GNOME application (deprecated, using popt)</b></p>
<pre class="programlisting">
int main(int argc, char **argv) {
	GnomeProgram *my_app;
	GOptionContext *option_context;
	
	/* We assume PACKAGE and VERSION are set to the program name and version
	 * number respectively. Also, assume that 'options' is a global array of
	 * poptOptions.
	 */
	option_context = g_option_context_new (PACKAGE);
	g_option_context_add_main_entries (option_context, options, NULL);
	my_app = gnome_program_init(PACKAGE, VERSION, LIBGNOMEUI_MODULE,
	                            argc, argv,
				    GNOME_PARAM_GOPTION_CONTEXT, option_context,
				    GNOME_PARAM_NONE);
	/* Now process any extra args, etc ... */
}
</pre>
</div>
<p>
Even though many applications still use popt for command-line option parsing,
it has been deprecated in Gnome-2.14 and its use is discouraged for
newly-written code. GNOME applications should aim to use the new
<span class="type">GOption</span> API. Here an example that shows how one might initialize a typical
program using a GOptionEntry table (see the GLib documentation for a more
elaborate example of an option entry table):
</p>
<div class="example">
<a name="id2787369"></a><p class="title"><b>Example&#160;2.&#160;Initializing a GNOME application (new, using GOption)</b></p>
<pre class="programlisting">
int main(int argc, char **argv) {
	gchar **remaining_args = NULL;
	GOptionEntry option_entries[] = {
		/* ... your application's command line options go here ... */