Libxfce4ui.SMClient¶
- Subclasses:
None
Methods¶
- Inherited:
- Structs:
class |
|
class |
|
class |
|
class |
|
class |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Virtual Methods¶
- Inherited:
Properties¶
Name |
Type |
Flags |
Short Description |
---|---|---|---|
w/co |
Argument count passed to program |
||
[ |
w/co |
Argument vector passed to program |
|
r/w/co |
A string uniquely identifying the current instance of this client |
||
r/w |
The directory that should be used as the working directory the next time this client is restarted |
||
r/w |
The application’s .desktop file |
||
r/w/c |
Determines the ordering in which this client is restarted |
||
[ |
r/w |
A command used to restart this application, preserving the current state |
|
r/w/c |
Specifies how the client should be restarted by the session manager |
||
r |
Whether or not the client was resumed with previous state |
Signals¶
- Inherited:
Name |
Short Description |
---|---|
Emitted when the application is required to quit. |
|
Informs the application that it will not need to quit. |
|
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). |
|
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. |
|
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:
Class Details¶
- class Libxfce4ui.SMClient(**kwargs)¶
- Bases:
- Abstract:
No
An opaque struct with only private fields.
- 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:
Gets the application’s SM client instance. This is best used with
Libxfce4ui.SMClient.get_option_group
() above (and using the returnedGLib.OptionGroup
withGLib.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
) – AnLibxfce4ui.SMClientRestartStyle
priority (
int
) – A restart priorityresumed_client_id (
str
) – The client id used in the previous sessioncurrent_directory (
str
) – The application’s working directoryrestart_command (
str
) – A command that can resume the application’s saved statedesktop_file (
str
) – The application’s .desktop file
- Returns:
A new
Libxfce4ui.SMClient
instance- Return type:
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
() andLibxfce4ui.SMClient.get
() instead.
- classmethod get_option_group(argc, argv)¶
- Parameters:
- Returns:
A new
GLib.OptionGroup
- Return type:
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 callingGtk.init
() orGtk.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
) – AnLibxfce4ui.SMClientRestartStyle
priority (
int
) – A restart priority
- Returns:
A new
Libxfce4ui.SMClient
instance- Return type:
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 callingLibxfce4ui.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
() andLibxfce4ui.SMClient.get
() instead.
- connect()¶
- Raises:
- Returns:
True
on success,False
otherwise. If an error occurs, error will be set.- Return type:
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:
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:
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
toGObject.G_MAXINT8
- Return type:
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:
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:
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()¶
-
Determines whether or not the application has connected to the session manager.
- is_resumed()¶
-
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
() andGtk.Window.set_default_icon_name
() (orGtk.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
- 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
) – AnLibxfce4ui.SMClientRestartStyle
value
Sets the restart style hint to restart_style.
Signal Details¶
- Libxfce4ui.SMClient.signals.quit(s_m_client)¶
- Signal Name:
quit
- Flags:
- 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:
- 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:
- Parameters:
s_m_client (
Libxfce4ui.SMClient
) – The object which received the signal- Return type:
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 returnFalse
.
- Libxfce4ui.SMClient.signals.save_state(s_m_client)¶
- Signal Name:
save-state
- Flags:
- 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:
- 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:
- Default Value:
0
- Flags:
Argument count passed to program
- Libxfce4ui.SMClient.props.argv¶
- Name:
argv
- Type:
[
str
]- Default Value:
[]
- Flags:
Argument vector passed to program
- Libxfce4ui.SMClient.props.client_id¶
- Name:
client-id
- Type:
- Default Value:
- Flags:
A string uniquely identifying the current instance of this client
- Libxfce4ui.SMClient.props.current_directory¶
-
The directory that should be used as the working directory the next time this client is restarted
- Libxfce4ui.SMClient.props.desktop_file¶
-
The application’s .desktop file
- Libxfce4ui.SMClient.props.priority¶
-
Determines the ordering in which this client is restarted
- Libxfce4ui.SMClient.props.restart_command¶
-
A command used to restart this application, preserving the current state
- Libxfce4ui.SMClient.props.restart_style¶
- Name:
restart-style
- Type:
- Default Value:
- Flags:
Specifies how the client should be restarted by the session manager