gobject Functions
Prev | The gobject Class Reference | Next

## gobject Functions

gobject Functions — miscellaneous functions

## Synopsis

        def gobject.type_name(type)
        def gobject.type_from_name(type_name)
        def gobject.type_parent(type)
        def gobject.type_is_a(type, parent_type)
        def gobject.type_children(type)
        def gobject.type_interfaces(type)
        def gobject.type_register(class)
        def gobject.signal_new(signal_name, type, flags, return_type, param_types)
        def gobject.signal_list_names(type)
        def gobject.signal_list_ids(type)
        def gobject.signal_lookup(name, type)
        def gobject.signal_name(signal_id)
        def gobject.signal_query(name, type)
        def gobject.signal_query(signal_id)
        def gobject.list_properties(type)
        def gobject.new(type, ...)
        def gobject.idle_add(callback, ...)
        def gobject.timeout_add(interval, callback, ...)
        def gobject.io_add_watch(fd, condition, callback, ...)
        def gobject.source_remove(tag)
        def gobject.main_context_default()
        def gobject.markup_escape_text(text)
        def gobject.child_watch_add(pid, function, data=None, priority=gobject.PRIORITY_DEFAULT)
        def gobject.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 gobject.get_current_time()
        def gobject.main_depth()
        def gobject.threads_init()
        def gobject.signal_accumulator_true_handled()
        def gobject.add_emission_hook(type, name, callback, ...)
        def gobject.remove_emission_hook(type, name, hook_id)
        def gobject._install_metaclass(metaclass)
        def gobject.filename_display_name(filename)
        def gobject.filename_display_basename(filename)
        def gobject.filename_from_utf8(utf8string)

## Description

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

## Functions

### gobject.type_name

        def 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

        def 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

        def 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

        def 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

        def 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

        def 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

        def 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

        def 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

        def 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`

### Note

The type keyword is available in PyGTK 2.6 and above.

### gobject.signal_list_ids

        def gobject.signal_list_ids(type)

`type` : | a GObject type, type ID or instance
Returns : | a list of the signal ids supported by `type`

### Note

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

        def 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.

### Note

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 by`type`. 0 is returned if the signal is not found.

### gobject.signal_name

        def gobject.signal_name(signal_id)

`signal_id` : | an integer signal id
Returns : | the name of the signal or `None`.

### Note

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

        def 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`

### Note

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 GObject Signal Flag Constants)
- 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

        def gobject.signal_query(signal_id)

`signal_id` : | the integer id of a signal
Returns : | a 6-tuple containing signal information or `None`

### Note

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 GObject Signal Flag Constants)
- 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

        def 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

        def 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

        def 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

        def 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

        def 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

        def 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

        def 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

        def gobject.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 `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

        def gobject.child_watch_add(pid, function, data=None, priority=gobject.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 GObject Priority Constants
Returns : | the id of event source.

### Note

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

        def gobject.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 GObject 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 `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 GObject Spawn Flag Constants 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

        def gobject.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 `gobject.get_current_time`() function reurns the current time of day as the number of seconds and microseconds from the epoch.

### gobject.main_depth

        def gobject.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 `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.

### gobject.threads_init

        def gobject.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 gobject module. This function is different than the `gtk.gdk.threads_init`() function as that function also initializes the gdk threads.

### gobject.signal_accumulator_true_handled

        def gobject.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.

### gobject.add_emission_hook

        def gobject.add_emission_hook(type, name, callback, ...)

type : | a Python GObject instance or type
name : | a signal name
callback : | a function
... : | zero or more extra arguments that will be passed to callback.
Returns : | the hook id, for later use with `gobject.signal_remove_emission_hook`().

### Note

This function is available in PyGTK 2.8 and above.

The `add_emission_hook`() function adds an emission hook for the signal specified by `name`, which will get called for any emission of that signal, independent of the instance. This is possible only for signals which don't have the `gobject.SIGNAL_NO_HOOKS` flag set.

### gobject.remove_emission_hook

        def gobject.remove_emission_hook(type, name, hook_id)

type : | a Python GObject instance or type
name : | a signal name
hook_id : | the id of the emission hook as returned by the `gobject.add_emission_hook`()) function.
Returns : |

### Note

This function is available in PyGTK 2.8 and above.

The `remove_emission_hook`() function deletes an emission hook.

### gobject._install_metaclass

        def gobject._install_metaclass(metaclass)

metaclass : |

### Note

This function is available in PyGTK 2.10 and above.

The `_install_metaclass`() function installs the metaclass specified by `metaclass`.

### gobject.filename_display_name

        def gobject.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 `gobject.filename_display_basename`() function, since that allows location-based translation of filenames.

### gobject.filename_display_basename

        def gobject.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 `gobject.filename_display_name`() function if you know the whole path, as it allows translation.

### gobject.filename_from_utf8

        def gobject.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
gobject.MainLoop | Home | gobject Constants