
@c %start of fragment

@deftp Class <gnome-program>
This @code{<gobject>} class defines the following properties:

@table @code
@item app-id
ID string to use for this application

@item app-version
Version of this application

@item human-readable-name
Human readable name of this application

@item gnome-path
Path in which to look for installed files

@item gnome-prefix
Prefix where GNOME was installed

@item gnome-libdir
Library prefix where GNOME was installed

@item gnome-datadir
Data prefix where GNOME was installed

@item gnome-sysconfdir
Configuration prefix where GNOME was installed

@item app-prefix
Prefix where this application was installed

@item app-libdir
Library prefix where this application was installed

@item app-datadir
Data prefix where this application was installed

@item app-sysconfdir
Configuration prefix where this application was installed

@item create-directories
Create standard GNOME directories on startup

@item enable-sound
Enable sound on startup

@item espeaker
How to connect to esd

@item popt-table
The table of options for popt

@item popt-flags
The flags to use for popt

@item popt-context
The popt context pointer that GnomeProgram is using

@item goption-context
The goption context pointer that GnomeProgram is using

@end table

@end deftp

@deffn Function gnome-program-get  @result{}@tie{} (ret@tie{}@code{<gnome-program>})
Retrieves an object that stored information about the application's state. Other
functions assume this will always return a @code{<gnome-program>} object which
(if not @samp{@code{#f}}) has already been initialized.

@table @var
@item ret
The application's @code{<gnome-program>} instance, or @samp{@code{#f}} if it
does not exist.

@end table

@end deffn

@deffn Function gnome-program-get-app-id  (self@tie{}@code{<gnome-program>}) @result{}@tie{} (ret@tie{}@code{mchars})
@deffnx Method get-app-id
This function returns a pointer to a static string that the application has
provided as an identifier. This is not meant as a human-readable identifier so
much as a unique identifier for programs and libraries.

@table @var
@item program
The program object

@item ret
Application ID string.

@end table

@end deffn

@deffn Function gnome-program-get-app-version  (self@tie{}@code{<gnome-program>}) @result{}@tie{} (ret@tie{}@code{mchars})
@deffnx Method get-app-version
This function returns a pointer to a static string that the application has
provided as a version number. This is not meant as a human-readable identifier
so much as a unique identifier for programs and libraries.

@table @var
@item program
The application object

@item ret
Application version string.

@end table

@end deffn

@deffn Function gnome-program-locate-file  (self@tie{}@code{<gnome-program>}) (domain@tie{}@code{<gnome-file-domain>}) (file_name@tie{}@code{mchars}) (only_if_exists@tie{}@code{bool}) (ret_locations@tie{}@code{<gs-list**>}) @result{}@tie{} (ret@tie{}@code{mchars})
@deffnx Method locate-file
This function finds a full path to the @var{file-name} located in the specified
"domain". A domain is a name for a collection of related files. For example,
common domains are "libdir", "pixmap", and "config".

If @var{ret-locations} is @samp{@code{#f}}, only one pathname is returned.
Otherwise, alternative paths are returned in @var{ret-locations}.

User applications should store files in the GNOME_FILE_DOMAIN_APP_* domains.
However you MUST set the correct attributes for @code{<gnome-program>} for the
APP specific prefixes (during the initialization part of the application).

The @var{ret-locations} list and its contents should be freed by the caller, as
should the returned string.

@table @var
@item program
A valid @code{<gnome-program>} object or @samp{@code{#f}} (in which case the
current application is used).

@item domain
A @code{<gnome-file-domain>}.

@item file-name
A file name or path inside the 'domain' to find.

@item only-if-exists
Only return a full pathname if the specified file actually exists

@item ret-locations
If this is not @samp{@code{#f}}, a list of all the possible locations of the
file will be returned.

@item ret
The full path to the file (if it exists or only_if_exists is @samp{@code{#f}})
or @samp{@code{#f}}.

@end table

@end deffn

@deffn Function gnome-program-module-register  (module_info@tie{}@code{<gnome-module-info*>})
This function is used to register a module to be initialized by the GNOME
library framework. The memory pointed to by @var{module-info} must be valid
during the whole application initialization process, and the module described by
@var{module-info} must only use the @var{module-info} pointer to register
itself.

@table @var
@item module-info
A pointer to a GnomeModuleInfo structure describing the module to be initialized

@end table

@end deffn

@deffn Function gnome-program-module-registered  (module_info@tie{}@code{<gnome-module-info*>}) @result{}@tie{} (ret@tie{}@code{bool})
This method checks to see whether a specific module has been initialized in the
specified program.

@table @var
@item module-info
A pointer to a GnomeModuleInfo structure describing the module to be queried

@item ret
A value indicating whether the specified module has been registered/initialized
in the current program

@end table

@end deffn

@deffn Function gnome-program-install-property  (pclass@tie{}@code{<gnome-program-class*>}) (get_fn@tie{}@code{<g-object-get-property-func>}) (set_fn@tie{}@code{<g-object-set-property-func>}) (pspec@tie{}@code{<gparam>}) @result{}@tie{} (ret@tie{}@code{unsigned-int})
Install a collection of available properties, their default values and the
functions to set and retrieve these properties.

Normal applications will never need to call this function, it is mostly for use
by other platform library authors.

@table @var
@item pclass
A @code{<gnome-program-class>}.

@item get-fn
A function to get property values.

@item set-fn
A function to set property values.

@item pspec
A collection of properties.

@item ret
The number of properties installed.

@end table

@end deffn

@deffn Function gnome-program-preinit  (self@tie{}@code{<gnome-program>}) (app_id@tie{}@code{mchars}) (app_version@tie{}@code{mchars}) (argc@tie{}@code{int}) (argv@tie{}@code{<char**>}) @result{}@tie{} (ret@tie{}@code{<popt-context>})
@deffnx Method preinit
This function performs the portion of application initialization that needs to
be done prior to command line argument parsing. The poptContext returned can be
used for @code{getopt}-style option processing.

@table @var
@item program
Application object

@item app-id
application ID string

@item app-version
application version string

@item argc
The number of commmand line arguments contained in 'argv'

@item argv
A string array of command line arguments

@item ret
A poptContext representing the argument parsing state, or @samp{@code{#f}} if
using GOption argument parsing.

@end table

@end deffn

@deffn Function gnome-program-parse-args  (self@tie{}@code{<gnome-program>})
@deffnx Method parse-args
Parses the command line arguments for the application

@table @var
@item program
Application object

@end table

@end deffn

@deffn Function gnome-program-postinit  (self@tie{}@code{<gnome-program>})
@deffnx Method postinit
Called after @code{gnome-program-parse-args}, this function takes care of
post-parse initialization and cleanup

@table @var
@item program
Application object

@end table

@end deffn


@c %end of fragment
