Libxfce4ui.SMClient

g GObject.Object GObject.Object Libxfce4ui.SMClient Libxfce4ui.SMClient GObject.Object->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 Libxfce4ui.SMClient instance -transfer full- on the first call only, other calls to this function are transfer none

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, i.e. you should *only* unref the first 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:
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