This documentation is for an old version of IPython. You can find docs for newer versions here.

Module: html.widgets.widget

Base Widget class. Allows user to create widgets in the back-end that render in the IPython notebook front-end.

3 Classes

class IPython.html.widgets.widget.CallbackDispatcher(**kwargs)

Bases: IPython.config.configurable.LoggingConfigurable

A structure for registering and running callbacks

register_callback(callback, remove=False)

(Un)Register a callback


callback: method handle

Method to be registered or unregistered.

remove=False: bool

Whether to unregister the callback.

class IPython.html.widgets.widget.Widget(**kwargs)

Bases: IPython.config.configurable.LoggingConfigurable


Public constructor


Close method.

Closes the underlying comm. When the comm is closed, all of the widget views are automatically removed from the front-end.


Gets the widget state, or a piece of it.


key : unicode or iterable (optional)

A single property’s name or iterable of property names to get.

static handle_comm_opened(comm, msg)

Static method, called when a widget is constructed.


Hold syncing any state until the context manager is released


Gets the model id of this widget.

If a Comm doesn’t exist yet, a Comm will be created automagically.

on_displayed(callback, remove=False)

(Un)Register a widget displayed callback.


callback: method handler

Must have a signature of:

callback(widget, **kwargs)

kwargs from display are passed through without modification.

remove: bool

True if the callback should be unregistered.

on_msg(callback, remove=False)

(Un)Register a custom msg receive callback.


callback: callable

callback will be passed two arguments when a message arrives:

callback(widget, content)

remove: bool

True if the callback should be unregistered.

static on_widget_constructed(callback)

Registers a callback to be called when a widget is constructed.

The callback must have the following signature: callback(widget)


Open a comm to the frontend if one isn’t already open.


Sends a custom msg to the widget model in the front-end.


content : dict

Content of the message to send.


Sends the widget state, or a piece of it, to the front-end.


key : unicode, or iterable (optional)

A single property’s name or iterable of property names to sync with the front-end.


Called when a state is received from the front-end.

class IPython.html.widgets.widget.DOMWidget(*pargs, **kwargs)

Bases: IPython.html.widgets.widget.Widget

__init__(*pargs, **kwargs)

1 Function


Returns a decorator registering a widget class in the widget registry. If no key is provided, the class name is used as a key. A key is provided for each core IPython widget so that the frontend can use this key regardless of the language of the kernel