Libxfce4ui.SMClient¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`error_quark` ()
class	`get` ()
class	`get_full` (restart_style, priority, resumed_client_id, current_directory, restart_command, desktop_file)
class	`get_option_group` (argc, argv)
class	`get_with_argv` (argc, argv, restart_style, priority)
	`connect` ()
	`disconnect` ()
	`get_client_id` ()
	`get_current_directory` ()
	`get_priority` ()
	`get_restart_command` ()
	`get_restart_style` ()
	`get_state_file` ()
	`is_connected` ()
	`is_resumed` ()
	`request_shutdown` (shutdown_hint)
	`set_current_directory` (current_directory)
	`set_desktop_file` (desktop_file)
	`set_priority` (priority)
	`set_restart_command` (restart_command)
	`set_restart_style` (restart_style)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`argc`	`int`	w/co	Argument count passed to program
`argv`	[`str`]	w/co	Argument vector passed to program
`client-id`	`str`	r/w/co	A string uniquely identifying the current instance of this client
`current-directory`	`str`	r/w	The directory that should be used as the working directory the next time this client is restarted
`desktop-file`	`str`	r/w	The application’s .desktop file
`priority`		r/w/c	Determines the ordering in which this client is restarted
`restart-command`	[`str`]	r/w	A command used to restart this application, preserving the current state
`restart-style`	`Libxfce4ui.SMClientRestartStyle`	r/w/c	Specifies how the client should be restarted by the session manager
`resumed`	`bool`	r	Whether or not the client was resumed with previous state

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`quit`	Emitted when the application is required to quit.
`quit-cancelled`	Informs the application that it will not need to quit.
`quit-requested`	Signals the client that the session manager will soon want the application to quit, perhaps as a part of ending the session (but this should not be assumed).
`save-state`	Signals the client that it should save a copy of its current state such that it could be restarted later in exactly the same state as it is at the time of signal emission.
`save-state-extended`	Allows the application to save extra state information after all other applications in the session have had a chance to save their state.

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Libxfce4ui.SMClient(**kwargs)¶

Bases:: GObject.Object
Abstract:: No

An opaque struct with only private fields.

classmethod error_quark()¶

Returns:: a #GQuark.
Return type:: int

Gets the XfceSmClient Error Quark.

classmethod get()¶

Returns:: A new or existing Libxfce4ui.SMClient
Return type:: Libxfce4ui.SMClient

Gets the application’s SM client instance. This is best used with Libxfce4ui.SMClient.get_option_group() above (and using the returned GLib.OptionGroup with GLib.OptionContext.parse()), as the command line parsing will figure out many of the SM client’s required property values for you.

If you have already created an Libxfce4ui.SMClient instance using this function, this will return the same instance.

classmethod get_full(restart_style, priority, resumed_client_id, current_directory, restart_command, desktop_file)¶

Parameters:

restart_style (Libxfce4ui.SMClientRestartStyle) – An Libxfce4ui.SMClientRestartStyle
priority (int) – A restart priority
resumed_client_id (str) – The client id used in the previous session
current_directory (str) – The application’s working directory
restart_command (str) – A command that can resume the application’s saved state
desktop_file (str) – The application’s .desktop file

Returns:

A new Libxfce4ui.SMClient instance

Return type:

Libxfce4ui.SMClient

Creates a new SM client instance, allowing the application fine-grained control over the initial properties set. Note that this function does not actually connect to the session manager, so other actions can be taken (such as setting custom properties or connecting signals) before calling Libxfce4ui.SMClient.connect().

It is recommended to use Libxfce4ui.SMClient.get_with_argv(), or, if you are using Gtk or Glib’s command-line option parser, Libxfce4ui.SMClient.get_option_group() and Libxfce4ui.SMClient.get() instead.

classmethod get_option_group(argc, argv)¶

Parameters:

argc (int) – The application’s argument count
argv (str) – The application’s argument vector

Returns:

A new GLib.OptionGroup

Return type:

GLib.OptionGroup

Constructs a GLib.OptionGroup suitable for use with Glib’s command-line option parser.

This function is a bit sneaky in that it will make a copy of the program’s argc and argv <emphasis>before</emphasis> GTK+ etc. has a chance to mess around with it, so Libxfce4ui.SMClient can later construct an accurate restart command. Instead of calling Gtk.init() or Gtk.init_with_args(), instead you’d do something like:

<informalexample><programlisting> GLib.OptionContext *context = g_option_context_new(“”); GLib.OptionContext.add_group(context, Gtk.get_option_group(True)); GLib.OptionContext.add_group(context, Libxfce4ui.SMClient.get_option_group(argc, argv); GLib.OptionContext.parse(context, &argc, &argv, None); </programlisting></informalexample>

Error checking is omitted here for brevity, and of course you could add your app’s own options with GLib.OptionContext.add_main_entries() or similar.

classmethod get_with_argv(argc, argv, restart_style, priority)¶

Parameters:

argc (int) – The number of arguments passed to main()
argv (str) – The argument vector passed to main()
restart_style (Libxfce4ui.SMClientRestartStyle) – An Libxfce4ui.SMClientRestartStyle
priority (int) – A restart priority

Returns:

A new Libxfce4ui.SMClient instance

Return type:

Libxfce4ui.SMClient

Creates a new Libxfce4ui.SMClient instance. It attempts to set all required properties using the app’s command line. Note that this function does not actually connect to the session manager, so other actions can be taken (such as setting custom properties or connecting signals) before calling Libxfce4ui.SMClient.connect().

If you are using Gtk or Glib’s command-line option parser, it is recommended that you use Libxfce4ui.SMClient.get_option_group() and Libxfce4ui.SMClient.get() instead.

connect()¶

Raises:: GLib.Error
Returns:: True on success, False otherwise. If an error occurs, error will be set.
Return type:: bool

Attempts to connect to the session manager.

disconnect()¶

Disconnects the application from the session manager.

This may not remove the application from the saved session (if any) if the user later does not choose to save the session when logging out.

get_client_id()¶

Returns:: an opaque object-owned string
Return type:: str

Retrieves the session client’s unique ID. This ID can be used to construct a filename used to restore the application’s state. Note that this value is only guaranteed to be valid if connected to the session manager.

Instead of constructing a state filename, it is recommended to use Libxfce4ui.SMClient.get_state_file().

get_current_directory()¶

Returns:: an object-owned string
Return type:: str

Retrieves the session client’s working directory. See Libxfce4ui.SMClient.set_current_directory() for more information.

get_priority()¶

Returns:: a value from GObject.G_MININT8 to GObject.G_MAXINT8
Return type:: int

Retrieves the session client’s restart priority. See Libxfce4ui.SMClient.set_priority() for more information.

get_restart_command()¶

Returns:: an object-owned string vector
Return type:: [str]

Retrieves the session client’s restart command. See Libxfce4ui.SMClient.set_restart_command() for more information.

get_restart_style()¶

Returns:: a value from the Libxfce4ui.SMClientRestartStyle enum
Return type:: Libxfce4ui.SMClientRestartStyle

Retrieves the session client’s restart style. See Libxfce4ui.SMClient.set_restart_style() for more information.

get_state_file()¶

Returns:: a file name string, owned by the object or None if the session client is disabled.
Return type:: str

Constructs a filename that can be used to restore or save state information.

When saving state, ote that this file may already exist (and may have been used for saving previous state for the application), so the application should first remove or empty the file if it requires a fresh state file.

On the next application start, this function can be used to check to see if there is any previous saved state, and, if so, the state can be restored from the file.

This function will use a standard location and naming scheme and handle state cleanup (setting of the discard command) for you.

Before calling this function, the application must have a valid client ID (see Libxfce4ui.SMClient.get_client_id()).

is_connected()¶

Returns:: True if connected to the session manager, False otherwise
Return type:: bool

Determines whether or not the application has connected to the session manager.

is_resumed()¶

Returns:: True if resumed from a previous session, False otherwise
Return type:: bool

Determines whether the application was resumed from a previous session, or if the application has been started fresh with no state information associated with it.

request_shutdown(shutdown_hint)¶

Parameters:: shutdown_hint (Libxfce4ui.SMClientShutdownHint) – The type of shutdown requested

Sends a request to the session manager to end the session. Depending on hint, the session manager may prompt for a certain action (log out, halt, reboot, etc.) or may take the requested action without user intervention.

The session manager may or may not support all requested actions, and is also free to ignore the requested action.

set_current_directory(current_directory)¶

Parameters:: current_directory (str) – A valid path name

Sets the startup working directory of self to current_directory. If unset, defaults to the user’s home directory.

set_desktop_file(desktop_file)¶

Parameters:: desktop_file (str) – The path to the application’s .desktop file

Sets the application’s .desktop file. In addition to informing the session manager of the .desktop file so it can present localized names and an icon in session listings and the splash screen, this also calls GLib.set_application_name() and Gtk.Window.set_default_icon_name() (or Gtk.Window.set_default_icon_from_file()) if the Name and Icon keys are present, respectively.

If a relative path to the file is provided, this function will search the standard application directories as specified by the

XDG Desktop Menu Specification.

set_priority(priority)¶

Parameters:: priority (int) – A 8-bit signed priority value

Sets the startup priority for self to priority. Note that the default priority for applications is 50; lower values should be reserved for components of the desktop environment.

set_restart_command(restart_command)¶

Parameters:: restart_command (str) – An argument vector

Sets the application’s “restart” command, which is used to restart the application and restore any saved state from the previous run.

If unset, defaults to the command used to start this instance of the application, with session management related arguments added (if not already present).

set_restart_style(restart_style)¶

Parameters:: restart_style (Libxfce4ui.SMClientRestartStyle) – An Libxfce4ui.SMClientRestartStyle value

Sets the restart style hint to restart_style.

Signal Details¶

Libxfce4ui.SMClient.signals.quit(s_m_client)¶

Signal Name:: quit
Flags:: RUN_LAST
Parameters:: s_m_client (Libxfce4ui.SMClient) – The object which received the signal

Emitted when the application is required to quit. This is not optional: if the client does not quit a short time after receiving this signal, it will likely be terminated in some other way. While not required, the application will usually receive quit-requested before receiving quit. If the application does not connect to this signal, Libxfce4ui.SMClient will call exit(3) with an exit code of zero on behalf of the application.

Libxfce4ui.SMClient.signals.quit_cancelled(s_m_client)¶

Signal Name:: quit-cancelled
Flags:: RUN_LAST
Parameters:: s_m_client (Libxfce4ui.SMClient) – The object which received the signal

Informs the application that it will not need to quit. In most cases, quit-cancelled will be emitted a short time after quit-requested.

Libxfce4ui.SMClient.signals.quit_requested(s_m_client)¶

Signal Name:: quit-requested
Flags:: RUN_LAST
Parameters:: s_m_client (Libxfce4ui.SMClient) – The object which received the signal
Return type:: bool

Signals the client that the session manager will soon want the application to quit, perhaps as a part of ending the session (but this should not be assumed). The application can take this opportunity to prompt the user to save any unsaved work to disk.

This signal also expects a return value from the handler. If the application wishes to cancel the quit request (perhaps because the user selected “Cancel” in prompts to save unsaved work), it should return True from the handler. If the application is satisfied with possibly needing to quit soon, the handler should return False.

Libxfce4ui.SMClient.signals.save_state(s_m_client)¶

Signal Name:: save-state
Flags:: RUN_LAST
Parameters:: s_m_client (Libxfce4ui.SMClient) – The object which received the signal

Signals the client that it should save a copy of its current state such that it could be restarted later in exactly the same state as it is at the time of signal emission.

If the state is simple enough to be encoded in the application’s command line, Libxfce4ui.SMClient.set_restart_command() can be used to set that command line. For more complex state data, Libxfce4ui.SMClient.get_state_file() should be used.

The application should attempt to save its state as quickly as possible, and MUST NOT interact with the user as a part of saving state.

Libxfce4ui.SMClient.signals.save_state_extended(s_m_client)¶

Signal Name:: save-state-extended
Flags:: RUN_LAST
Parameters:: s_m_client (Libxfce4ui.SMClient) – The object which received the signal

Allows the application to save extra state information after all other applications in the session have had a chance to save their state. This is mainly used by the window manager to save window positions. Most applications should not need to connect to this signal.

Property Details¶

Libxfce4ui.SMClient.props.argc¶

Name:: argc
Type:: int
Default Value:: 0
Flags:: WRITABLE, CONSTRUCT_ONLY

Argument count passed to program

Libxfce4ui.SMClient.props.argv¶

Name:: argv
Type:: [str]
Default Value:: []
Flags:: WRITABLE, CONSTRUCT_ONLY

Argument vector passed to program

Libxfce4ui.SMClient.props.client_id¶

Name:: client-id
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

A string uniquely identifying the current instance of this client

Libxfce4ui.SMClient.props.current_directory¶

Name:: current-directory
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

The directory that should be used as the working directory the next time this client is restarted

Libxfce4ui.SMClient.props.desktop_file¶

Name:: desktop-file
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

The application’s .desktop file

Libxfce4ui.SMClient.props.priority¶

Name:: priority
Type:
Default Value:: 50
Flags:: READABLE, WRITABLE, CONSTRUCT

Determines the ordering in which this client is restarted

Libxfce4ui.SMClient.props.restart_command¶

Name:: restart-command
Type:: [str]
Default Value:: []
Flags:: READABLE, WRITABLE

A command used to restart this application, preserving the current state

Libxfce4ui.SMClient.props.restart_style¶

Name:: restart-style
Type:: Libxfce4ui.SMClientRestartStyle
Default Value:: Libxfce4ui.SMClientRestartStyle.NORMAL
Flags:: READABLE, WRITABLE, CONSTRUCT

Specifies how the client should be restarted by the session manager

Libxfce4ui.SMClient.props.resumed¶

Name:: resumed
Type:: bool
Default Value:: False
Flags:: READABLE

Whether or not the client was resumed with previous state