gobject.GObject
Prev | PyGObject Class Reference | Next

## gobject.GObject

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)

Prev | Up | Next
PyGObject Class Reference | Home | gobject.GBoxed