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

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_FIRSTInvoke the object method handler in the first emission stage.
gobject.SIGNAL_RUN_LASTInvoke the object method handler in the third emission stage.
gobject.SIGNAL_RUN_CLEANUPInvoke the object method handler in the last emission stage.
gobject.SIGNAL_NO_RECURSESignals 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_DETAILEDThis signal supports "::detail" appendixes to the signal name upon handler connections and emissions.
gobject.SIGNAL_ACTIONAction 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 bytype. 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_INThere is data to read.
gobject.IO_OUTData can be written (without blocking).
gobject.IO_PRIThere is urgent data to read.
gobject.IO_ERRError condition.
gobject.IO_HUPHung 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.