glib Functions
Prev | PyGlibClass Reference | Next

## glib Functions

glib Functions — miscellaneous functions

## Synopsis

        def glib.idle_add(callback, ...)
        def glib.timeout_add(interval, callback, ...)
        def glib.timeout_add_seconds(interval, callback, ...)
        def glib.io_add_watch(fd, condition, callback, ...)
        def glib.source_remove(tag)
        def glib.main_context_default()
        def glib.markup_escape_text(text)
        def glib.child_watch_add(pid, function, data=None, priority=glib.PRIORITY_DEFAULT)
        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)
        def glib.get_current_time()
        def glib.get_user_cache_dir()
        def glib.get_user_config_dir()
        def glib.get_user_data_dir()
        def glib.get_user_special_dir(directory)
        def glib.main_depth()
        def glib.threads_init()
        def glib.filename_display_name(filename)
        def glib.filename_display_basename(filename)
        def glib.filename_from_utf8(utf8string)

## Description

These functions are part of the `PyGObject` glib module but are not directly associated with a specific class.

## Functions

### glib.idle_add

        def glib.idle_add(callback, ...)

`callback` : | a function to call when `PyGTK` is idle
`...` : | optionals arguments to be passed to `callback`
Returns : | an integer ID

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, ...)

`interval` : | the time between calls to the function, in milliseconds
`callback` : | the function to call
`...` : | zero or more arguments that will be passed to `callback`
Returns : | an integer ID of the event source

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, ...)

`interval` : | the time between calls to the function, in seconds
`callback` : | the function to call
`...` : | zero or more arguments that will be passed to `callback`
Returns : | an integer ID of the event source

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, ...)

`fd` : | a Python file object or an integer file descriptor ID
`condition` : | a condition mask
`callback` : | a function to call
`...` : | additional arguments to pass to `callback`
Returns : | an integer ID of the event source

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:

`glib.IO_IN` | There is data to read.
`glib.IO_OUT` | Data can be written (without blocking).
`glib.IO_PRI` | There is urgent data to read.
`glib.IO_ERR` | Error condition.
`glib.IO_HUP` | Hung up (the connection has been broken, usually for pipes and sockets).

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)

`tag` : | an integer ID
Returns : | `True` if the event source was removed

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()

Returns : | the default glib.MainContext object

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

### glib.markup_escape_text

        def glib.markup_escape_text(text)

`text` : | the UTF-8 string to be escaped
Returns : | the escaped text

### Note

This function is available in PyGTK 2.8 and above.

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)

`pid` : | process id of a child process to watch
`function` : | the function to call
`data` : | the optional data to pass to `function`
`priority` : | the priority of the idle source - one of the Glib Priority Constants
Returns : | the id of event source.

### Note

This function is available in PyGTK 2.6 and above.

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)

`argv` : | a sequence of strings containing the arguments of the child process
`envp` : | the child's environment or `None` to inherit the parent's environment.
`working_directory` : | the child's current working directory, or `None` to inherit parent's
`flags` : | flags from the Glib Spawn Flag Constants.
`child_setup` : | a function to run in the child just before calling `exec`()
`user_data` : | the user data for the `child_setup` function
`standard_input` : | if `True` return the file descriptor for the child's stdin
`standard_output` : | if `True` return the file descriptor for the child's stdout
`standard_error` : | if `True` return the file descriptor for the child's stderr
Returns : | a 4-tuple containing the child's process id and the stdin, stdout and stderr file descriptor integers.

### Note

This function is available in PyGTK 2.6 and above.

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()

Returns : | the current time as the number of seconds and microseconds from the epoch.

### Note

This function is available in PyGTK 2.8 and above.

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 strings with a path to user's cache directory.

### Note

This function is available in PyGObject 2.18 and above.

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 strings with a path to user's configuration directory.

### Note

This function is available in PyGObject 2.18 and above.

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 strings with a path to user's data directory.

### Note

This function is available in PyGObject 2.18 and above.

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)

directory : | the logical id of special directory, see User Directory constants for the list of supported values
Returns : | a strings with a path to the requested directory.

### Note

This function is available in PyGObject 2.18 and above.

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()

Returns : | the depth of the stack of calls to the main context.

### Note

This function is available in PyGTK 2.8 and above.

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()

Returns : |

### Note

This function is available in PyGTK 2.4 and above.

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()

### Note

This function is available in PyGTK 2.8 and above.

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)

filename : | a pathname in the file name encoding
Returns : | an UTF8 rendition of `filename`.

### Note

This function is available in PyGTK 2.10 and above.

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)

filename : | an absolute pathname in the file name encoding
Returns : | an UTF8 rendition of `filename`.

### Note

This function is available in PyGTK 2.10 and above.

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)

utf8string : | a UTF-8 encoded string.
Returns : | a filename encoded in the GLib filename encoding.

### Note

This function is available in PyGTK 2.10 and above.

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.

Prev | Up | Next
glib.MainLoop | Home | glib Constants