gobject.GObject

gobject.GObject
Prev	PyGObject Class Reference	Next

gobject.GObject — the base class

Synopsis

class gobject.GObject:
    def get_property(property_name)
    def get_properties(first_property_name, ...)
    def set_property(property_name, value)
    def set_properties(property_name=value, ...)
    def freeze_notify()
    def notify(property_name)
    def thaw_notify()
    def get_data(key)
    def set_data(key, data)
    def connect(detailed_signal, handler)
    def connect_after(detailed_signal, handler)
    def connect_object(detailed_signal, handler)
    def connect_object_after(detailed_signal, handler)
    def disconnect(handler_id)
    def handler_disconnect(handler_id)
    def handler_is_connected(handler_id)
    def handler_block(handler_id)
    def handler_unblock(handler_id)
    def handler_block_by_func(callable)
    def handler_unblock_by_func(callable)
    def emit(detailed_signal)
    def stop_emission(detailed_signal)
    def emit_stop_by_name(detailed_signal)
    def chain()

Ancestry

+-- gobject.GObject

Attributes

"props"	Read/Write	This attribute gives full access to GObject properties as simple attributes. It can be used to iterate over all the object properties, and can be used both on class or instance objects. Examples: button = Button() button_label = button.props.label button.props.label = 'Click on this fancy button' for pspec in button.props: print pspec print button.get_property(pspec.name) label_pspec = Button.props.label button_label = button.get_property(label_pspec.name)
"__doc__"	Read	The documentation for the object type. Uses "__gdoc__" if no specific documentation set.
"__gdoc__"	Read	The generated documentation for the underlying GObject type.
"__gtype__"	Read	The underlying GObject type.
"__grefcount__"	Read	The reference count for the underlying GObject.

gobject.GObject Signal Prototypes

"notify"

def callback(gobject, property_spec, user_param1, ...)

Description

The gobject.GObject class is the base class providing the common attributes and methods for the PyGTK classes. The gobject.GObject class is not a user interface widget class.

The gobject.GObject class provides the signal management methods, the object property access methods and the object data management methods.

Methods

gobject.GObject.get_property

    def get_property(property_name)

`property_name` :	a string containing the property name for the GObject
Returns :	a Python object containing the value of the property

The get_property() method returns the value of the property specified by property_name or None if there is no value associated with the property.

The TypeError exception is raised if the property name is not registered with the object class.

gobject.GObject.get_properties

    def get_properties(first_property_name, ...)

`first_property_name` :	a string containing the first property name for the GObject
`...` :	additional property names
Returns :	a tuple containing the property values requested

The get_properties() method returns a tuple containing the values of the properties requested, or None if there is no value associated with the property.

The TypeError exception is raised if the property name is not registered with the object class.

gobject.GObject.set_property

    def set_property(property_name, value)

`property_name` :	a string containing the property name
`value` :	a Python object containing the property value to be set

The set_property() method sets the property specified by property_name to the specified value.

The TypeError exception is raised if the property name is not registered with the object class or if the value specified could not be converted to the property type.

gobject.GObject.set_properties

    def set_properties(property_name=value, ...)

`property_name` :	the property name
`value` :	a Python object containing the property value to be set
`...` :	additional property name and value kwargs

The set_properties() method sets the property specified by property_name to the specified value, followed by pairs of property name and value as keyword arguments.

The TypeError exception is raised if the property name is not registered with the object class or if the value specified could not be converted to the property type.

gobject.GObject.freeze_notify

    def freeze_notify()

The freeze_notify() method freezes the object's property-changed notification queue so that "notify" signals are blocked until the thaw_notify() method is called.

gobject.GObject.notify

    def notify(property_name)

property_name :

a string containing a property name

The notify() method causes the "notify" signal for the property specified by property_name to be emitted.

gobject.GObject.thaw_notify

    def thaw_notify()

The thaw_notify() method thaws the object's property-changed notification queue so that "notify" signals are emitted.

gobject.GObject.get_data

    def get_data(key)

`key` :	a string used as the key
Returns :	a Python object containing the associated data

The get_data() method returns the Python object associated with the specified key or None if there is no data associated with the key or if there is no key associated with the object.

gobject.GObject.set_data

    def set_data(key, data)

`key` :	a string used as a key
`data` :	a Python object that is the value to be associated with the key

The set_data() method associates the specified Python object (data) with key.

gobject.GObject.connect

    def connect(detailed_signal, handler, ...)

`detailed_signal` :	a string containing the signal name
`handler` :	a Python function or method object.
`...` :	additional optional parameters
Returns :	an integer identifier

The connect() method adds a function or method (handler)to the end of the list of signal handlers for the named detailed_signal but before the default class signal handler. An optional set of parameters may be specified after the handler parameter. These will all be passed to the signal handler when invoked.

For example if a function handler was connected to a signal using:

  handler_id = object.connect("signal_name", handler, arg1, arg2, arg3)

The handler should be defined as:

  def handler(object, arg1, arg2, arg3):

A method handler connected to a signal using:

  handler_id = object.connect("signal_name", self.handler, arg1, arg2)

requires an additional argument when defined:

  def handler(self, object, arg1, arg2)

A TypeError exception is raised if detailed_signal identifies a signal name that is not associated with the object.

gobject.GObject.connect_after

    def connect_after(detailed_signal, handler, ...)

`detailed_signal` :	a string containing the signal name
`handler` :	a Python function or method object
`...` :	additional optional parameters
Returns :	an integer handler identifier

The connect_after() method is similar to the connect() method except that the handler is added to the signal handler list after the default class signal handler. Otherwise the details of handler definition and invocation are the same.

gobject.GObject.connect_object

    def connect_object(detailed_signal, handler, gobject)

`detailed_signal` :	a string containing the signal name
`handler` :	a Python function or method object
`gobject` :	a GObject
Returns :	an integer handler identifier

The connect_object() method is the same as the connect() method except that the handler is invoked with the specified gobject in place of the object invoking the connect_object() method. For example, a call with a function handler:

  handler_id = object("signal_name", handler, gobject)

will cause the handler to be invoked as:

  handler(gobject)

Likewise a method handler will be invoked as:

  self.handler(gobject)

This can be helpful in invoking PyGTK widget methods that require no arguments except the widget itself (e.g. widget.destroy()) by using the class method as the handler. For example, a Button "clicked" signal can be set up to invoke the Window destroy() method as:

  handler_id = button.connect_object("clicked", Window.destroy, window)

When the button is clicked the handler is invoked as:

  Window.destroy(window)

which is the same as:

  window.destroy()

Additional arguments may be passed to the handler as with the connect() method handler invocations.

gobject.GObject.connect_object_after

    def connect_object_after(detailed_signal, handler)

`detailed_signal` :	a string containing the signal name
`handler` :	a Python function or method object
`gobject` :	a GObject
Returns :	an integer handler identifier

The connect_object_after() method is similar to the connect_object() method except that the handler is added to the signal handler list after the default class signal handler. Otherwise the details of handler definition and invocation are the same.

gobject.GObject.disconnect

    def disconnect(handler_id)

handler_id :

an integer handler identifier

The disconnect() method removes the signal handler with the specified handler_id from the list of signal handlers for the object.

gobject.GObject.handler_disconnect

    def handler_disconnect(handler_id)

handler_id :

an integer handler identifier

The handler_disconnect() method removes the signal handler with the specified handler_id from the list of signal handlers for the object.

gobject.GObject.handler_is_connected

    def handler_is_connected(handler_id)

`handler_id` :	an integer handler identifier
Returns :	`TRUE` if the signal handler is connected to the object.

The handler_is_connected() method returns TRUE if the signal handler with the specified handler_id is connected to the object.

gobject.GObject.handler_block

    def handler_block(handler_id)

handler_id :

an integer handler identifier

The handler_block() method blocks the signal handler with the specified handler_id from being invoked until it is unblocked.

gobject.GObject.handler_unblock

    def handler_unblock(handler_id)

handler_id :

an integer handler identifier

gobject.GObject.handler_block_by_func

    def handler_block_by_func(callable)

callable :

a callable python object

The handler_block_by_func() method blocks the all signal handler connected to a specific callable from being invoked until the callable is unblocked.

gobject.GObject.handler_unblock_by_func

    def handler_unblock_by_func(callback)

callable :

a callable python object

The handler_unblock_by_func() method unblocks all signal handler connected to a specified callable thereby allowing it to be invoked when the associated signals are emitted.

gobject.GObject.emit

    def emit(detailed_signal, ...)

`detailed_signal` :	a string containing the signal name
`...` :	additional parameters
Returns :	a PyObject*

The emit() method causes the object to emit the signal specified by detailed_signal. The additional parameters must match the number and type of the required signal handler parameters. In most cases no additional parameters are needed. for example:

  button.emit("clicked")

is all that is required to emit the "clicked" signal for a button. The most common case requiring additional parameters occurs when emitting an event signal; for example:

  button.emit("button_press_event", event)

gobject.GObject.stop_emission

    def stop_emission(detailed_signal)

detailed_signal :

a string containing the signal name

The stop_emission() method stops the current emission of the signal specified by detailed_signal. Any signal handlers in the list still to be run will not be invoked.

gobject.GObject.emit_stop_by_name

    def emit_stop_by_name(detailed_signal)

detailed_signal :

a string containing the signal name

The emit_stop_by_name() method stops the current emission of the signal specified by detailed_signal. Any signal handlers in the list still to be run will not be invoked.

gobject.GObject.chain

    def chain(...)

`...` :	additional parameters
Returns :	a Python object

The chain() method does something.

Signals

The GObject "notify" Signal

    def callback(gobject, property_spec, user_param1, ...)

`gobject` :	the gobject that received the signal
`property_spec` :	the `gobject.GParamSpec` of the property that was changed
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "notify" signal is emitted on a gobject when one of its properties has been changed. Note that getting this signal doesn't guarantee that the value of the property has actually changed, it may also be emitted when the setter for the property is called to reinstate the previous value. For example to be notified of the change of the title of a gtk.Window you could connect to the "notify" signal similar to:

  window.connect("notify::title", callback)