gobject.GObject
3
PyGTK Docs

# gobject.GObject

the base class

## Synopsis

gobject.GObject
get_property
property_name
get_properties
first_property_name
...
set_property
property_name
value
set_properties
property_name
value
...
freeze_notify
notify
property_name
thaw_notify
get_data
key
set_data
key
data
connect
detailed_signal
handler
connect_after
detailed_signal
handler
connect_object
detailed_signal
handler
connect_object_after
detailed_signal
handler
disconnect
handler_id
handler_disconnect
handler_id
handler_is_connected
handler_id
handler_block
handler_id
handler_unblock
handler_id
handler_block_by_func
callable
handler_unblock_by_func
callable
emit
detailed_signal
stop_emission
detailed_signal
emit_stop_by_name
detailed_signal
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"
  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

    	  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

    	  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

    	  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

    	  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

    	  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

    	  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

    	  thaw_notify

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

### gobject.GObject.get_data

    	  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

    	  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

    	  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

    	  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

    	  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

    	  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

    	  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

    	  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

    	  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

    	  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

    	  handler_unblock
    	  handler_id

`handler_id` :

  an integer handler identifier

### gobject.GObject.handler_block_by_func

    	  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

    	  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

    	  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

    	  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

    	  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

    	  chain
    	  ...

`...` :

  additional parameters

Returns :

  a Python object

The chain() method does something.

## Signals

### The GObject "notify" Signal

    	  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)