
@c %start of fragment

@deftp Class <gnome-client>
Derives from @code{<gtk-object>}.

This class defines no properties, other than those defined by its superclasses.

@end deftp

@defop Signal <gnome-client> save-yourself  (arg0@tie{}@code{<gint>}) (arg1@tie{}@code{<gnome-save-style>}) (arg2@tie{}@code{<gboolean>}) (arg3@tie{}@code{<gnome-interact-style>}) (arg4@tie{}@code{<gboolean>}) @result{}@tie{}@code{<gboolean>}
Called when either a "SaveYourself" or a "SaveYourselfPhase2" call is made by
the session manager.

@end defop

@defop Signal <gnome-client> die 
Called when the session manager wants the client to shut down.

@end defop

@defop Signal <gnome-client> save-complete 
Called when the session manager has finished checkpointing all of the clients.
Clients are then free to change their state.

@end defop

@defop Signal <gnome-client> shutdown-cancelled 
Called if the session manager had sent a "SaveYourself" to all clients in
preparation for shutting down and the shutdown was then cancelled. A client can
then continue running and change its state.

@end defop

@defop Signal <gnome-client> connect  (arg0@tie{}@code{<gboolean>})
Called once the client has been connected to the signal manager.

@end defop

@defop Signal <gnome-client> disconnect 
Called when the client is disconnected from the session manager.

@end defop

@deffn Function gnome-master-client  @result{}@tie{} (ret@tie{}@code{<gnome-client>})
Get the master session management client. This master client gets a client id,
that may be specified by the '--sm-client-id' command line option. A master
client will be generated by @code{gnome-program-init}. If possible the master
client will contact the session manager after command-line parsing is finished
(unless @code{gnome-client-disable-master-connection} was called). The master
client will also set the SM_CLIENT_ID property on the client leader window of
your application.

Additionally, the master client gets some static arguments set automatically
(see @code{gnome-client-add-static-arg} for static arguments):
@code{gnome-program-init} passes all the command line options which are
recognised by gtk as static arguments to the master client.

@table @var
@item ret
Pointer to the master client

@end table

@end deffn

@deffn Function gnome-client-get-config-prefix  (self@tie{}@code{<gnome-client>}) @result{}@tie{} (ret@tie{}@code{mchars})
@deffnx Method get-config-prefix
Get the config prefix for a client. This config prefix provides a suitable place
to store any details about the state of the client which can not be described
using the app's command line arguments (as set in the restart command). You may
push the returned value using @code{gnome-config-push-prefix} and read or write
any values you require.

@table @var
@item client
Pointer to GNOME session client object.

@item ret
Config prefix. The returned string belongs to libgnomeui library and should NOT
be freed by the caller.

@end table

@end deffn

@deffn Function gnome-client-get-flags  (self@tie{}@code{<gnome-client>}) @result{}@tie{} (ret@tie{}@code{<gnome-client-flags>})
@deffnx Method get-flags
Determine the client's status with the session manager.,

@table @var
@item client
Pointer to GNOME session client object.

@item ret
Various @code{<gnome-client-flag>} flags which have been or'd together.

@end table

@end deffn

@deffn Function gnome-client-set-restart-style  (self@tie{}@code{<gnome-client>}) (style@tie{}@code{<gnome-restart-style>})
@deffnx Method set-restart-style
Tells the session manager how the client should be restarted in future session.
The options are given by the @code{<gnome-restart-style>} enum.

@table @var
@item client
Pointer to GNOME session client object.

@item style
When to restart the client.

@end table

@end deffn

@deffn Function gnome-client-set-priority  (self@tie{}@code{<gnome-client>}) (priority@tie{}@code{unsigned-int})
@deffnx Method set-priority
The gnome-session manager restarts clients in order of their priorities in a
similar way to the start up ordering in SysV. This function allows the app to
suggest a position in this ordering. The value should be between 0 and 99. A
default value of 50 is assigned to apps that do not provide a value. The user
may assign a different priority.

@table @var
@item client
Pointer to GNOME session client object.

@item priority
Position of client in session start up ordering.

@end table

@end deffn

@deffn Function gnome-client-set-current-directory  (self@tie{}@code{<gnome-client>}) (dir@tie{}@code{mchars})
@deffnx Method set-current-directory
Set the directory to be in when running shutdown, discard, restart, etc.
commands.

@table @var
@item client
Pointer to GNOME session client object.

@item dir
Directory path.

@end table

@end deffn

@deffn Function gnome-client-set-environment  (self@tie{}@code{<gnome-client>}) (name@tie{}@code{mchars}) (value@tie{}@code{mchars})
@deffnx Method set-environment
Set an environment variable to be placed in the client's environment prior to
running restart, shutdown, discard, etc. commands.

@table @var
@item client
Pointer to GNOME session client object.

@item name
Name of the environment variable

@item value
Value of the environment variable

@end table

@end deffn

@deffn Function gnome-client-set-process-id  (self@tie{}@code{<gnome-client>}) (pid@tie{}@code{int})
@deffnx Method set-process-id
The client should tell the session manager the result of @code{getpid}. However,
GNOME does this automatically; so you do not need this function.

@table @var
@item client
Pointer to GNOME session client object.

@item pid
PID to set as the client's PID.

@end table

@end deffn

@deffn Function gnome-client-set-program  (self@tie{}@code{<gnome-client>}) (program@tie{}@code{mchars})
@deffnx Method set-program
Used to tell the session manager the name of your program. Set automatically;
this function isn't needed.

@table @var
@item client
Pointer to GNOME session client object.

@item program
Name of the program.

@end table

@end deffn

@deffn Function gnome-client-set-user-id  (self@tie{}@code{<gnome-client>}) (id@tie{}@code{mchars})
@deffnx Method set-user-id
Tell the session manager the user's login name. GNOME does this automatically;
no need to call the function.

@table @var
@item client
Pointer to GNOME session client object.

@item id
Username.

@end table

@end deffn

@deffn Function gnome-client-save-any-dialog  (self@tie{}@code{<gnome-client>}) (dialog@tie{}@code{<gtk-dialog>})
@deffnx Method save-any-dialog
May be called during a "save_youself" handler to request that a (modal) dialog
is presented to the user. The session manager decides when the dialog is shown,
but it will not be shown it unless the session manager is sending an interaction
style of @code{<gnome-interact-any>}. A "Cancel Logout" button will be added
during a shutdown.

@table @var
@item client
Pointer to @code{<gnome-client>} object.

@item dialog
Pointer to GNOME dialog widget (a @code{<gtk-dialog>} widget).

@end table

@end deffn

@deffn Function gnome-client-save-error-dialog  (self@tie{}@code{<gnome-client>}) (dialog@tie{}@code{<gtk-dialog>})
@deffnx Method save-error-dialog
May be called during a "save_youself" handler when an error has occurred during
the save. The session manager decides when the dialog is shown, but it will not
be shown it unless the session manager is sending an interaction style of
@code{<gnome-interact-any>}. A "Cancel Logout" button will be added during a
shutdown.

@table @var
@item client
Pointer to @code{<gnome-client>} object.

@item dialog
Pointer to GNOME dialog widget (a @code{<gtk-dialog>} widget).

@end table

@end deffn

@deffn Function gnome-client-request-phase-2  (self@tie{}@code{<gnome-client>})
@deffnx Method request-phase-2
Request the session managaer to emit the "save_yourself" signal for a second
time after all the clients in the session have ceased interacting with the user
and entered an idle state. This might be useful if your app manages other apps
and requires that they are in an idle state before saving its final data.

@table @var
@item client
A @code{<gnome-client>} object.

@end table

@end deffn

@deffn Function gnome-client-request-save  (self@tie{}@code{<gnome-client>}) (save_style@tie{}@code{<gnome-save-style>}) (shutdown@tie{}@code{bool}) (interact_style@tie{}@code{<gnome-interact-style>}) (fast@tie{}@code{bool}) (global@tie{}@code{bool})
@deffnx Method request-save
Request the session manager to save the session in some way. The arguments
correspond with the arguments passed to the "save_yourself" signal handler.

The save_style indicates whether the save should affect data accessible to other
users (@code{<gnome-save-global>}) or only the state visible to the current user
(@code{<gnome-save-local>}) or both. Setting shutdown to @samp{@code{#t}} will
initiate a logout. The interact_style specifies which kinds of interaction will
be available. Setting fast to @samp{@code{#t}} will limit the save to setting
the session manager properties plus any essential data. Setting the value of
global to @samp{@code{#t}} will request that all the other apps in the session
do a save as well. A global save is mandatory when doing a shutdown.

@table @var
@item client
Pointer to GNOME session client object.

@item save-style
Save style to request.

@item shutdown
Whether to log out of the session.

@item interact-style
Whether to allow user interaction.

@item fast
Minimize activity to save as soon as possible.

@item global
Request that all other apps in the session also save their state.

@end table

@end deffn

@deffn Function gnome-client-flush  (self@tie{}@code{<gnome-client>})
@deffnx Method flush
This will force the underlying connection to the session manager to be flushed.
This is useful if you have some pending changes that you want to make sure get
committed.

@table @var
@item client
A @code{<gnome-client>} instance.

@end table

@end deffn

@deffn Function gnome-client-new  @result{}@tie{} (ret@tie{}@code{<gnome-client>})
Allocates memory for a new GNOME session management client object. After
allocating, the client tries to connect to a session manager. You probably want
to use @code{gnome-master-client} instead.

@table @var
@item ret
Pointer to a newly allocated GNOME session management client object.

@end table

@end deffn

@deffn Function gnome-client-new-without-connection  @result{}@tie{} (ret@tie{}@code{<gnome-client>})
Allocates memory for a new GNOME session management client object. You probably
want to use @code{gnome-master-client} instead.

@table @var
@item ret
Pointer to a newly allocated GNOME session management client object.

@end table

@end deffn

@deffn Function gnome-client-connect  (self@tie{}@code{<gnome-client>})
@deffnx Method connect
Causes the client to connect to the session manager. Usually happens
automatically; no need to call this function.

@table @var
@item client
A @code{<gnome-client>} instance.

@end table

@end deffn

@deffn Function gnome-client-disconnect  (self@tie{}@code{<gnome-client>})
@deffnx Method disconnect
Disconnect the client from the session manager.

@table @var
@item client
A @code{<gnome-client>} instance.

@end table

@end deffn

@deffn Function gnome-client-set-id  (self@tie{}@code{<gnome-client>}) (id@tie{}@code{mchars})
@deffnx Method set-id
Set the client's session management ID; must be done before connecting to the
session manager. There is usually no reason to call this function.

@table @var
@item client
A @code{<gnome-client>} instance.

@item id
Session management ID.

@end table

@end deffn

@deffn Function gnome-client-get-id  (self@tie{}@code{<gnome-client>}) @result{}@tie{} (ret@tie{}@code{mchars})
@deffnx Method get-id
Returns session management ID

@table @var
@item client
A @code{<gnome-client>} instance.

@item ret
Session management ID for this client; @samp{@code{#f}} if not connected to a
session manager.

@end table

@end deffn

@deffn Function gnome-client-get-previous-id  (self@tie{}@code{<gnome-client>}) @result{}@tie{} (ret@tie{}@code{mchars})
@deffnx Method get-previous-id
Get the session management ID from the previous session.

@table @var
@item client
A @code{<gnome-client>} instance.

@item ret
Pointer to the session management ID the client had in the last session, or
@samp{@code{#f}} if it was not in a previous session.

@end table

@end deffn

@deffn Function gnome-client-get-desktop-id  (self@tie{}@code{<gnome-client>}) @result{}@tie{} (ret@tie{}@code{mchars})
@deffnx Method get-desktop-id
Get the client ID of the desktop's current instance, i.e. if you consider the
desktop as a whole as a session managed app, this returns its session ID using a
GNOME extension to session management. May return @samp{@code{#f}} for apps not
running under a recent version of gnome-session; apps should handle that case.

@table @var
@item client
A @code{<gnome-client>} instance.

@item ret
Session ID of GNOME desktop instance, or @samp{@code{#f}} if none.

@end table

@end deffn


@c %end of fragment
