glib Functions miscellaneous functions glib.idle_add callback ... glib.timeout_add interval callback ... glib.timeout_add_seconds interval callback ... glib.io_add_watch fd condition callback ... glib.source_remove tag glib.main_context_default glib.markup_escape_text text glib.child_watch_add pid function dataNone priorityglib.PRIORITY_DEFAULT glib.spawn_async argv envpNone working_directoryNone flags0 child_setupNone user_dataNone standard_inputNone standard_outputNone standard_errorNone glib.get_current_time glib.get_user_cache_dir glib.get_user_config_dir glib.get_user_data_dir glib.get_user_special_dir directory glib.main_depth glib.threads_init glib.filename_display_name filename glib.filename_display_basename filename glib.filename_from_utf8 utf8string These functions are part of the PyGObject glib module but are not directly associated with a specific class. 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 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 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 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 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 Returns : the default glib.MainContext object The glib.main_context_default() function returns the default glib.MainContext object. glib.markup_escape_text text text : the UTF-8 string to be escaped Returns : the escaped text 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 pid function dataNone priorityglib.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 Returns : the id of event source. 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 argv envpNone working_directoryNone flags0 child_setupNone user_dataNone standard_inputNone standard_outputNone standard_errorNone 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 . 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. 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 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 Returns : the current time as the number of seconds and microseconds from the epoch. 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 Returns : a strings with a path to user's cache directory. 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 Returns : a strings with a path to user's configuration directory. 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 Returns : a strings with a path to user's data directory. 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 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. 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 Returns : the depth of the stack of calls to the main context. 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 Returns : 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 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 filename filename : a pathname in the file name encoding Returns : an UTF8 rendition of filename. 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 filename filename : an absolute pathname in the file name encoding Returns : an UTF8 rendition of filename. 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 utf8string utf8string : a UTF-8 encoded string. Returns : a filename encoded in the GLib filename encoding. 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.