gobject Functions miscellaneous functions gobject.type_name type gobject.type_from_name type_name gobject.type_parent type gobject.type_is_a type parent_type gobject.type_children type gobject.type_interfaces type gobject.type_register class gobject.signal_new signal_name type flags return_type param_types gobject.signal_list_names type gobject.signal_list_ids type gobject.signal_lookup name type gobject.signal_name signal_id gobject.signal_query name type gobject.signal_query signal_id gobject.list_properties type gobject.new type ... gobject.idle_add callback ... gobject.timeout_add interval callback ... gobject.io_add_watch fd condition callback ... gobject.source_remove tag gobject.main_context_default gobject.markup_escape_text text gobject.child_watch_add pid function dataNone prioritygobject.PRIORITY_DEFAULT gobject.spawn_async argv envpNone working_directoryNone flags0 child_setupNone user_dataNone standard_inputNone standard_outputNone standard_errorNone gobject.get_current_time gobject.main_depth These functions are part of the PyGTK gobject module but are not directly associated with a specific class. gobject.type_name type type : a GObject type, type ID or instance Returns : The gobject.type_name() function returns the unique name that is assigned to the specified type. type can be a GObject type, type ID or instance. This function raises a TypeError exception if type isn't a PyGTK type. gobject.type_from_name type_name type_name : a string containing the name of a type Returns : the type ID named type_name The gobject.type_from_name() function returns the type ID of the PyGTK type with the name specified by type_name. This function raises a RuntimeError exception if no type matches type_name. gobject.type_parent type type : a GObject type, type ID or instance Returns : the parent type ID The gobject.type_parent() function returns the direct parent type ID of the specified type. type can be a GObject type, type ID or instance. If type has no parent, i.e. is a fundamental type, the RuntimeError exception is raised. gobject.type_is_a type parent_type type : a GObject type, type ID or instance parent_type : a GObject type, type ID or instance Returns : True if parent_type is an ancestor of type The gobject.type_is_a() function returns True if the specified type is a descendant of the type specified by parent_type. This function also returns True if parent_type is an interface and type conforms to it. gobject.type_children type type : a GObject type, type ID or instance Returns : a list of the child types of type The gobject.type_children() function returns a list containing the child types of the specified type. gobject.type_interfaces type type : a GObject type, type ID or instance Returns : a list of the interface types supported by type The gobject.type_interfaces() function returns a list of the interface types supported by type. type can be a GObject type, type ID or instance. This function returns a RuntimeError exception if type is not a valid type or has no interfaces. gobject.type_register class class : a Python class that is a descendant of gobject.GObject The gobject.type_register() function registers the specified Python class as a PyGTK type. class must be a descendant of gobject.GObject. The function generates a name for the new type. gobject.signal_new signal_name type flags return_type param_types signal_name : a string containing the name of the signal type : the object type that the signal is associated with flags : the signal flags return_type : the return type of the signal handler param_types : the parameter types passed to the signal handler Returns : a unique integer signal ID The gobject.signal_new() function registers a signal with the specified signal_name for the specified object type. The value of flags is a combination of: gobject.SIGNAL_RUN_FIRST Invoke the object method handler in the first emission stage. gobject.SIGNAL_RUN_LAST Invoke the object method handler in the third emission stage. gobject.SIGNAL_RUN_CLEANUP Invoke the object method handler in the last emission stage. gobject.SIGNAL_NO_RECURSE Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted. gobject.SIGNAL_DETAILED This signal supports "::detail" appendixes to the signal name upon handler connections and emissions. gobject.SIGNAL_ACTION Action signals are signals that may freely be emitted on alive objects from user code via gobject.emit()() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as generically callable object methods. gobject.SIGNAL_NO_HOOKS No emissions hooks are supported for this signal. return_type is the type of the return value from a signal handler and may be a gobject type, type ID or instance. The param_types parameter is a list of additional types that are passed to the signal handler. Each parameter type may be specified as a gobject type, type ID or instance. For example, to add a signal to the gtk.Window type called "my-signal" that calls a handler with a gtk.Button widget and an integer value and a return value that is a boolean, use: gobject.signal_new("my_signal", gtk.Window, gobject.SIGNAL_RUN_LAST, gobject.TYPE_BOOLEAN, (gtk.Button, gobject.TYPE_INT)) gobject.signal_list_names type type : a GObject type, type ID or instance Returns : a list of the signal names supported by type The gobject.signal_list_names() function returns a list of the names of the signals that are supported by the specified GObject type The type keyword is available in PyGTK 2.6 and above. gobject.signal_list_ids type type : a GObject type, type ID or instance Returns : a list of the signal ids supported by type This method is available in PyGTK 2.6 and above. The gobject.signal_list_ids() function returns a list of the integer ids of the signals that are supported by the GObject specified by type gobject.signal_lookup name type name : the name of a signal for type type : a GObject type, type ID or instance Returns : the integer id of a signal supported by type or 0. This method is available in PyGTK 2.6 and above. The gobject.signal_lookup() function returns the id of the signal with the name specified by name that is supported by the GObject specified specified bytype. 0 is returned if the signal is not found. gobject.signal_name signal_id signal_id : an integer signal id Returns : the name of the signal or None. This method is available in PyGTK 2.6 and above. The gobject.signal_name() function returns the name of the signal that has the signal id specified by id. gobject.signal_query name type name : the name of a signal for type type : a GObject type, type ID or instance Returns : a 6-tuple containing signal information or None This method is available in PyGTK 2.6 and above. The gobject.signal_query() function returns a 6-tuple containing information about the signal with the name specified by name that is supported by the GObject specified by type. If the signal is not found None is returned. The signal information 6-tuple contains: the integer signal id the signal name the GType that the signal is registered for the signal flags (see the ) the GType of the return from the signal callback function a tuple containing the GTypes of the parameters that are passed to the signal callback function. Note that these may not correspond exactly to the PyGTK signal callback parameters. gobject.signal_query signal_id signal_id : the integer id of a signal Returns : a 6-tuple containing signal information or None This method is available in PyGTK 2.6 and above. The gobject.signal_query() function returns a 6-tuple containing information about the signal with the id specified by signal_id. If the signal is not found None is returned. The signal information 6-tuple contains: the integer signal id the signal name the GType that the signal is registered for the signal flags (see the ) the GType of the return from the signal callback function a tuple containing the GTypes of the parameters that are passed to the signal callback function. Note that these may not correspond exactly to the PyGTK signal callback parameters. gobject.list_properties type type : a GObject type, type ID or instance Returns : a list of the properties (as GParam objects) supported by type The gobject.list_properties() function returns a list of the properties (as GParam objects) supported by type. gobject.new type ... type : a GObject type, type ID or instance ... : zero or more property-value pairs Returns : a new object if the specified type The gobject.new() function returns a new object of the specified type. type must specify a type that is a descendant of gobject.GObject. A TypeError exception is raised if type specifies an abstract class or a type that is not a descendant of gobject.GObject. A set of property-value pairs may be specified to set the value of the object's properties. gobject.idle_add callback ... callback : a function to call when PyGTK is idle ... : optionals arguments to be passed to callback Returns : an integer ID The gobject.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, gobject.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. gobject.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 gobject.timeout_add() function sets a function (specified by callback) to be called at regular intervals (specified by interval, with the default priority, gobject.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). gobject.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 gobject.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: gobject.IO_IN There is data to read. gobject.IO_OUT Data can be written (without blocking). gobject.IO_PRI There is urgent data to read. gobject.IO_ERR Error condition. gobject.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 gobject.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. gobject.source_remove tag tag : an integer ID Returns : True if the event source was removed The gobject.source_remove() function removes the event source specified by tag (as returned by the gobject.idle_add(), gobject.timeout_add() and gobject.io_add_watch() functions) gobject.main_context_default Returns : the default gobject.MainContext object The gobject.main_context_default() function returns the default gobject.MainContext object. gobject.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 gobject.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. gobject.child_watch_add pid function dataNone prioritygobject.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 gobject.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. gobject.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 gobject.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 gobject.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 gobject.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 gobject.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 gobject.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). gobject.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. gobject.SPAWN_SEARCH_PATH means that argv[0] need not be an absolute path, it will be looked for in the user's PATH. gobject.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. gobject.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. gobject.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. gobject.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 gobject.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 gobject.SPAWN_DO_NOT_REAP_CHILD flag. On Windows, child pid will be returned only if you specified the gobject.SPAWN_DO_NOT_REAP_CHILD flag. The caller of the gobject.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 gobject.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 gobject.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 gobject.SPAWN_STDOUT_TO_DEV_NULL is set. If an error occurs, the gobject.GError exception will be raised. gobject.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 gobject.get_current_time() function reurns the current time of day as the number of seconds and microseconds from the epoch. gobject.main_depth Returns : he 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 gobject.MainContext.iteration() method (or the gobject.MainLoop.run() method, etc.) it returns 1. When called from within a callback to a recursive call to the gobject.MainContext.iteration() method), it returns 2. And so forth.