Note

This documentation is for a development version of IPython. There may be significant differences from the latest stable release (1.2.1).

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

Parameters:

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

__init__(**kwargs)

Public constructor

close()

Close method.

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

comm

Gets the Comm associated with this widget.

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

get_state(key=None)

Gets the widget state, or a piece of it.

Parameters:

key : unicode (optional)

A single property’s name to get.

model_id

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.

Parameters:

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.

Parameters:

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)

send(content)

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

Parameters:

content : dict

Content of the message to send.

send_state(key=None)

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

Parameters:

key : unicode (optional)

A single property’s name to sync with the front-end.

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

Bases: IPython.html.widgets.widget.Widget

add_class(class_names, selector='')

Add class[es] to a DOM element.

Parameters:

class_names: unicode or list

Class name(s) to add to the DOM element(s).

selector: unicode (optional)

JQuery selector to select the DOM element(s) that the class(es) will be added to.

get_css(key, selector='')

Get a CSS property of the widget.

Note: This function does not actually request the CSS from the front-end; Only properties that have been set with set_css can be read.

Parameters:

key: unicode

CSS key

selector: unicode (optional)

JQuery selector used when the CSS key/value was set.

remove_class(class_names, selector='')

Remove class[es] from a DOM element.

Parameters:

class_names: unicode or list

Class name(s) to remove from the DOM element(s).

selector: unicode (optional)

JQuery selector to select the DOM element(s) that the class(es) will be removed from.

set_css(dict_or_key, value=None, selector='')

Set one or more CSS properties of the widget.

This function has two signatures: - set_css(css_dict, selector=’‘) - set_css(key, value, selector=’‘)

Parameters:

css_dict : dict

CSS key/value pairs to apply

key: unicode

CSS key

value:

CSS value

selector: unicode (optional, kwarg only)

JQuery selector to use to apply the CSS key/value. If no selector is provided, an empty selector is used. An empty selector makes the front-end try to apply the css to a default element. The default element is an attribute unique to each view, which is a DOM element of the view that should be styled with common CSS (see $el_to_style in the Javascript code).