glib.idle_add

    def glib.idle_add(callback, ...)

The glib.idle_add() function adds a function (specified by callback) to be called whenever there are no higher priority events pending to the default main loop. The function is given the default idle priority, glib.PRIORITY_DEFAULT_IDLE. Additional arguments to pass to callback can be specified after callback. The idle priority can be specified as a keyword-value pair with the keyword "priority". If callback returns False it is automatically removed from the list of event sources and will not be called again.

glib.timeout_add

    def glib.timeout_add(interval, callback, ...)

The glib.timeout_add() function sets a function (specified by callback) to be called at regular intervals (specified by interval, with the default priority, glib.PRIORITY_DEFAULT. Additional arguments to pass to callback can be specified after callback. The idle priority may be specified as a keyword-value pair with the keyword "priority".

The function is called repeatedly until it returns False, at which point the timeout is automatically destroyed and the function will not be called again. The first call to the function will be at the end of the first interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays).

glib.timeout_add_seconds

    def glib.timeout_add_seconds(interval, callback, ...)

The glib.timeout_add_seconds() is similar to glib.timeout_add() except that interval must be specified in seconds, not milliseconds, and the function should cause less CPU wakeups, which is important for laptops' batteries.

Unlike glib.timeout_add(), this function operates at whole second granularity. The initial starting point of the timer is determined by the implementation and the implementation is expected to group multiple timers together so that they fire all at the same time. To allow this grouping, the interval to the first timer is rounded and can deviate up to one second from the specified interval. Subsequent timer iterations will generally run at the specified interval.

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval.

The grouping of timers to fire at the same time results in a more power and CPU efficient behavior so if your timer is in multiples of seconds and you don't require the first timer exactly one second from now, the use of glib.timeout_add_seconds() is preferred over glib.timeout_add().

glib.io_add_watch

    def glib.io_add_watch(fd, condition, callback, ...)

The glib.io_add_watch() function arranges for the file (specified by fd) to be monitored by the main loop for the specified condition. fd may be a Python file object or an integer file descriptor. The value of condition is a combination of:

Additional arguments to pass to callback can be specified after callback. The idle priority may be specified as a keyword-value pair with the keyword "priority". The signature of the callback function is:

  def callback(source, cb_condition, ...)

where source is fd, the file descriptor; cb_condition is the condition that triggered the signal; and, ... are the zero or more arguments that were passed to the glib.io_add_watch() function.

If the callback function returns False it will be automatically removed from the list of event sources and will not be called again. If it returns True it will be called again when the condition is matched.

glib.source_remove

    def glib.source_remove(tag)

The glib.source_remove() function removes the event source specified by tag (as returned by the glib.idle_add(), glib.timeout_add() and glib.io_add_watch() functions)

glib.main_context_default

    def glib.main_context_default()

The glib.main_context_default() function returns the default glib.MainContext object.

glib.markup_escape_text

    def glib.markup_escape_text(text)

The glib.markup_escape_text() function escapes the string specified by text so that the markup parser will parse it verbatim. Less than, greater than, ampersand, etc. are replaced with the corresponding entities. This function would typically be used when writing out a file to be parsed with the markup parser.

Note that this function doesn't protect whitespace and line endings from being processed according to the XML rules for normalization of line endings and attribute values.

glib.child_watch_add

    def glib.child_watch_add(pid, function, data=None, priority=glib.PRIORITY_DEFAULT)

The glib.child_watch_add() function sets the function specified by function to be called with the user data specified by data when the child indicated by pid exits. The signature for the callback is:

def callback(pid, condition, user_data)

where pid is is the child process id, condition is the status information about the child process and user_data is data PyGTK supports only a single callback per process id.

glib.spawn_async

    def glib.spawn_async(argv, envp=None, working_directory=None, flags=0, child_setup=None, user_data=None, standard_input=None, standard_output=None, standard_error=None)

The glib.spawn_async() function executes a child program asynchronously (your program will not block waiting for the child to exit). The child program is specified by the only argument that must be provided, argv. argv should be a sequence of strings, to be passed as the argument vector for the child. The first string in argv is of course the name of the program to execute. By default, the name of the program must be a full path; the PATH shell variable will only be searched if you pass the glib.SPAWN_SEARCH_PATH flag in flags. The function returns a 4-tuple containing the child's process id and the file descriptors for the child's stdin, stdout and stderr. The stdin, stdout and stderr file descriptors are returned only ofthe corresponding standard_input, standard_output or standard_error params are True.

On Windows, the low-level child process creation API (CreateProcess()) doesn't use argument vectors, but a command line. The C runtime library's spawn*() family of functions (which glib.spawn_async() eventually calls) paste the argument vector elements into a command line, and the C runtime startup code does a corresponding reconstruction of an argument vector from the command line, to be passed to main(). Complications arise when you have argument vector elements that contain spaces of double quotes. The spawn*() functions don't do any quoting or escaping, but on the other hand the startup code does do unquoting and unescaping in order to enable receiving arguments with embedded spaces or double quotes. To work around this asymmetry, the glib.spawn_async() function will do quoting and escaping on argument vector elements that need it before calling the C runtime spawn() function.

envp is a sequence of strings, where each string has the form KEY=VALUE. This will become the child's environment. If envp is None or not specified, the child inherits its parent's environment.

flags should be the bitwise OR of the Glib Spawn Flag Constants you want to affect the function's behaviour. The glib.SPAWN_DO_NOT_REAP_CHILD flag means that the child will not automatically be reaped; you must use a GChildWatch source to be notified about the death of the child process. Eventually you must call g_spawn_close_pid() on the child_pid, in order to free resources which may be associated with the child process. (On Unix, using a GChildWatch source is equivalent to calling waitpid() or handling the SIGCHLD signal manually. On Windows, calling g_spawn_close_pid() is equivalent to calling CloseHandle() on the process handle returned).

glib.SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file descriptors will be inherited by the child; otherwise all descriptors except stdin/stdout/stderr will be closed before calling exec() in the child. glib.SPAWN_SEARCH_PATH means that argv[0] need not be an absolute path, it will be looked for in the user's PATH. glib.SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will be discarded, instead of going to the same location as the parent's standard output. If you use this flag, standard_output must be None. glib.SPAWN_STDERR_TO_DEV_NULL means that the child's standard error will be discarded, instead of going to the same location as the parent's standard error. If you use this flag, standard_error must be None. glib.SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's standard input (by default, the child's standard input is attached to /dev/null). If you use this flag, standard_input must be None. glib.SPAWN_FILE_AND_ARGV_ZERO means that the first element of argv is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally the glib.spawn_async() function uses argv[0] as the file to execute, and passes all of argv to the child.

child_setup and user_data are a function and user data. On POSIX platforms, the function is called in the child after GLib has performed all the setup it plans to perform (including creating pipes, closing file descriptors, etc.) but before calling exec(). That is, child_setup is called just before calling exec() in the child. Obviously actions taken in this function will only affect the child, not the parent. On Windows, there is no separate fork() and exec() functionality. Child processes are created and run right away with one API call, CreateProcess(). child_setup is called in the parent process just before creating the child process. You should carefully consider what you do in child_setup if you intend your software to be portable to Windows.

The returned child process id can be used to send signals to the child, or to wait for the child if you specified the glib.SPAWN_DO_NOT_REAP_CHILD flag. On Windows, child pid will be returned only if you specified the glib.SPAWN_DO_NOT_REAP_CHILD flag.

The caller of the glib.spawn_async() must close any returned file descriptors when they are no longer in use.

If standard_input is None, the child's standard input is attached to /dev/null unless glib.SPAWN_CHILD_INHERITS_STDIN is set.

If standard_error is None, the child's standard error goes to the same location as the parent's standard error unless glib.SPAWN_STDERR_TO_DEV_NULL is set.

If standard_output is None, the child's standard output goes to the same location as the parent's standard output unless glib.SPAWN_STDOUT_TO_DEV_NULL is set.

If an error occurs, the glib.GError exception will be raised.

glib.get_current_time

    def glib.get_current_time()

The glib.get_current_time() function reurns the current time of day as the number of seconds and microseconds from the epoch.

glib.get_user_cache_dir

    def glib.get_user_cache_dir()

Returns a base directory in which to store non-essential, cached data specific to particular user.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification.

glib.get_user_config_dir

    def glib.get_user_config_dir()

Returns a base directory in which to store user-specific application configuration information such as user preferences and settings.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification.

glib.get_user_data_dir

    def glib.get_user_data_dir()

Returns a base directory in which to access application data such as icons that is customized for a particular user

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification.

glib.get_user_special_dir

    def glib.get_user_special_dir(directory)

Returns the full path of a special directory using its logical id.

On Unix this is done using the XDG special user directories. For compatibility with existing practise, glib.USER_DIRECTORY_DESKTOP falls back to $HOME/Desktop when XDG special user directories have not been set up.

Depending on the platform, the user might be able to change the path of the special directory without requiring the session to restart; GLib will not reflect any change once the special directories are loaded.

glib.main_depth

    def glib.main_depth()

The main_depth() function returns the depth of the stack of calls in the main context. That is, when called from the toplevel, it gives 0. When called from within a callback from the glib.MainContext.iteration() method (or the glib.MainLoop.run() method, etc.) it returns 1. When called from within a callback to a recursive call to the glib.MainContext.iteration() method), it returns 2. And so forth.

glib.threads_init

    def glib.threads_init()

The threads_init() function initializes the the use of Python threading in the glib module. This function is different than the gtk.gdk.threads_init() function as that function also initializes the gdk threads.

glib.signal_accumulator_true_handled

    def glib.signal_accumulator_true_handled()

The signal_accumulator_true_handled() function is only used as accumulator argument when registering signals.

glib.filename_display_name

    def glib.filename_display_name(filename)

The filename_display_name() function converts a filename into a valid UTF-8 string. The conversion is not necessarily reversible, so you should keep the original around and use the return value of this function only for display purposes. Unlike g_filename_to_utf8(), the result is guaranteed to be non-None even if the filename actually isn't in the file name encoding.

If you know the whole pathname of the file you should use the glib.filename_display_basename() function, since that allows location-based translation of filenames.

glib.filename_display_basename

    def glib.filename_display_basename(filename)

The filename_display_basename() function returns the display basename for the particular filename, guaranteed to be valid UTF-8. The display name might not be identical to the filename, for instance there might be problems converting it to UTF-8, and some files can be translated in the display.

You must pass the whole absolute pathname to this functions so that translation of well known locations can be done.

This function is preferred over the glib.filename_display_name() function if you know the whole path, as it allows translation.

glib.filename_from_utf8

    def glib.filename_from_utf8(utf8string)

The filename_from_utf8() function converts a string from UTF-8 to the encoding GLib uses for filenames. Note that on Windows GLib uses UTF-8 for filenames.