"""Implement common widgets layouts as reusable components"""
import re
from collections import defaultdict
from traitlets import Instance, Bool, Unicode, CUnicode, CaselessStrEnum, Tuple
from traitlets import Integer
from traitlets import HasTraits, TraitError
from traitlets import observe, validate
from .widget import Widget
from .widget_box import GridBox
from .docutils import doc_subst
_doc_snippets = {
'style_params' : """
grid_gap : str
CSS attribute used to set the gap between the grid cells
justify_content : str, in ['flex-start', 'flex-end', 'center', 'space-between', 'space-around']
CSS attribute used to align widgets vertically
align_items : str, in ['top', 'bottom', 'center', 'flex-start', 'flex-end', 'baseline', 'stretch']
CSS attribute used to align widgets horizontally
width : str
height : str
width and height"""
}
[docs]@doc_subst(_doc_snippets)
class LayoutProperties(HasTraits):
"""Mixin class for layout templates
This class handles mainly style attributes (height, grid_gap etc.)
Parameters
----------
{style_params}
Note
----
This class is only meant to be used in inheritance as mixin with other
classes. It will not work, unless `self.layout` attribute is defined.
"""
# style attributes (passed to Layout)
grid_gap = Unicode(
None,
allow_none=True,
help="The grid-gap CSS attribute.")
justify_content = CaselessStrEnum(
['flex-start', 'flex-end', 'center',
'space-between', 'space-around'],
allow_none=True,
help="The justify-content CSS attribute.")
align_items = CaselessStrEnum(
['top', 'bottom',
'flex-start', 'flex-end', 'center',
'baseline', 'stretch'],
allow_none=True, help="The align-items CSS attribute.")
width = Unicode(
None,
allow_none=True,
help="The width CSS attribute.")
height = Unicode(
None,
allow_none=True,
help="The width CSS attribute.")
[docs] def __init__(self, **kwargs):
super().__init__(**kwargs)
self._property_rewrite = defaultdict(dict)
self._property_rewrite['align_items'] = {'top': 'flex-start',
'bottom': 'flex-end'}
self._copy_layout_props()
self._set_observers()
def _delegate_to_layout(self, change):
"delegate the trait types to their counterparts in self.layout"
value, name = change['new'], change['name']
value = self._property_rewrite[name].get(value, value)
setattr(self.layout, name, value) # pylint: disable=no-member
def _set_observers(self):
"set observers on all layout properties defined in this class"
_props = LayoutProperties.class_trait_names()
self.observe(self._delegate_to_layout, _props)
def _copy_layout_props(self):
_props = LayoutProperties.class_trait_names()
for prop in _props:
value = getattr(self, prop)
if value:
value = self._property_rewrite[prop].get(value, value)
setattr(self.layout, prop, value) #pylint: disable=no-member
[docs]@doc_subst(_doc_snippets)
class AppLayout(GridBox, LayoutProperties):
""" Define an application like layout of widgets.
Parameters
----------
header: instance of Widget
left_sidebar: instance of Widget
center: instance of Widget
right_sidebar: instance of Widget
footer: instance of Widget
widgets to fill the positions in the layout
merge: bool
flag to say whether the empty positions should be automatically merged
pane_widths: list of numbers/strings
the fraction of the total layout width each of the central panes should occupy
(left_sidebar,
center, right_sidebar)
pane_heights: list of numbers/strings
the fraction of the width the vertical space that the panes should occupy
(left_sidebar, center, right_sidebar)
{style_params}
Examples
--------
"""
# widget positions
header = Instance(Widget, allow_none=True)
footer = Instance(Widget, allow_none=True)
left_sidebar = Instance(Widget, allow_none=True)
right_sidebar = Instance(Widget, allow_none=True)
center = Instance(Widget, allow_none=True)
# extra args
pane_widths = Tuple(CUnicode(), CUnicode(), CUnicode(),
default_value=['1fr', '2fr', '1fr'])
pane_heights = Tuple(CUnicode(), CUnicode(), CUnicode(),
default_value=['1fr', '3fr', '1fr'])
merge = Bool(default_value=True)
[docs] def __init__(self, **kwargs):
super().__init__(**kwargs)
self._update_layout()
@staticmethod
def _size_to_css(size):
if re.match(r'\d+\.?\d*(px|fr|%)$', size):
return size
if re.match(r'\d+\.?\d*$', size):
return size + 'fr'
raise TypeError("the pane sizes must be in one of the following formats: "
"'10px', '10fr', 10 (will be converted to '10fr')."
"Got '{}'".format(size))
def _convert_sizes(self, size_list):
return list(map(self._size_to_css, size_list))
def _update_layout(self):
grid_template_areas = [["header", "header", "header"],
["left-sidebar", "center", "right-sidebar"],
["footer", "footer", "footer"]]
grid_template_columns = self._convert_sizes(self.pane_widths)
grid_template_rows = self._convert_sizes(self.pane_heights)
all_children = {'header': self.header,
'footer': self.footer,
'left-sidebar': self.left_sidebar,
'right-sidebar': self.right_sidebar,
'center': self.center}
children = {position : child
for position, child in all_children.items()
if child is not None}
if not children:
return
for position, child in children.items():
child.layout.grid_area = position
if self.merge:
if len(children) == 1:
position = list(children.keys())[0]
grid_template_areas = [[position, position, position],
[position, position, position],
[position, position, position]]
else:
if self.center is None:
for row in grid_template_areas:
del row[1]
del grid_template_columns[1]
if self.left_sidebar is None:
grid_template_areas[1][0] = grid_template_areas[1][1]
if self.right_sidebar is None:
grid_template_areas[1][-1] = grid_template_areas[1][-2]
if (self.left_sidebar is None and
self.right_sidebar is None and
self.center is None):
grid_template_areas = [['header'], ['footer']]
grid_template_columns = ['1fr']
grid_template_rows = ['1fr', '1fr']
if self.header is None:
del grid_template_areas[0]
del grid_template_rows[0]
if self.footer is None:
del grid_template_areas[-1]
del grid_template_rows[-1]
grid_template_areas_css = "\n".join('"{}"'.format(" ".join(line))
for line in grid_template_areas)
self.layout.grid_template_columns = " ".join(grid_template_columns)
self.layout.grid_template_rows = " ".join(grid_template_rows)
self.layout.grid_template_areas = grid_template_areas_css
self.children = tuple(children.values())
@observe("footer", "header", "center", "left_sidebar", "right_sidebar", "merge",
"pane_widths", "pane_heights")
def _child_changed(self, change): #pylint: disable=unused-argument
self._update_layout()
[docs]@doc_subst(_doc_snippets)
class GridspecLayout(GridBox, LayoutProperties):
""" Define a N by M grid layout
Parameters
----------
n_rows : int
number of rows in the grid
n_columns : int
number of columns in the grid
{style_params}
Examples
--------
>>> from ipywidgets import GridspecLayout, Button, Layout
>>> layout = GridspecLayout(n_rows=4, n_columns=2, height='200px')
>>> layout[:3, 0] = Button(layout=Layout(height='auto', width='auto'))
>>> layout[1:, 1] = Button(layout=Layout(height='auto', width='auto'))
>>> layout[-1, 0] = Button(layout=Layout(height='auto', width='auto'))
>>> layout[0, 1] = Button(layout=Layout(height='auto', width='auto'))
>>> layout
"""
n_rows = Integer()
n_columns = Integer()
[docs] def __init__(self, n_rows=None, n_columns=None, **kwargs):
super().__init__(**kwargs)
self.n_rows = n_rows
self.n_columns = n_columns
self._grid_template_areas = [['.'] * self.n_columns for i in range(self.n_rows)]
self._grid_template_rows = 'repeat(%d, 1fr)' % (self.n_rows,)
self._grid_template_columns = 'repeat(%d, 1fr)' % (self.n_columns,)
self._children = {}
self._id_count = 0
@validate('n_rows', 'n_columns')
def _validate_integer(self, proposal):
if proposal['value'] > 0:
return proposal['value']
raise TraitError('n_rows and n_columns must be positive integer')
def _get_indices_from_slice(self, row, column):
"convert a two-dimensional slice to a list of rows and column indices"
if isinstance(row, slice):
start, stop, stride = row.indices(self.n_rows)
rows = range(start, stop, stride)
else:
rows = [row]
if isinstance(column, slice):
start, stop, stride = column.indices(self.n_columns)
columns = range(start, stop, stride)
else:
columns = [column]
return rows, columns
def __setitem__(self, key, value):
row, column = key
self._id_count += 1
obj_id = 'widget%03d' % self._id_count
value.layout.grid_area = obj_id
rows, columns = self._get_indices_from_slice(row, column)
for row in rows:
for column in columns:
current_value = self._grid_template_areas[row][column]
if current_value != '.' and current_value in self._children:
del self._children[current_value]
self._grid_template_areas[row][column] = obj_id
self._children[obj_id] = value
self._update_layout()
def __getitem__(self, key):
rows, columns = self._get_indices_from_slice(*key)
obj_id = None
for row in rows:
for column in columns:
new_obj_id = self._grid_template_areas[row][column]
obj_id = obj_id or new_obj_id
if obj_id != new_obj_id:
raise TypeError('The slice spans several widgets, but '
'only a single widget can be retrieved '
'at a time')
return self._children[obj_id]
def _update_layout(self):
grid_template_areas_css = "\n".join('"{}"'.format(" ".join(line))
for line in self._grid_template_areas)
self.layout.grid_template_columns = self._grid_template_columns
self.layout.grid_template_rows = self._grid_template_rows
self.layout.grid_template_areas = grid_template_areas_css
self.children = tuple(self._children.values())
[docs]@doc_subst(_doc_snippets)
class TwoByTwoLayout(GridBox, LayoutProperties):
""" Define a layout with 2x2 regular grid.
Parameters
----------
top_left: instance of Widget
top_right: instance of Widget
bottom_left: instance of Widget
bottom_right: instance of Widget
widgets to fill the positions in the layout
merge: bool
flag to say whether the empty positions should be automatically merged
{style_params}
Examples
--------
>>> from ipywidgets import TwoByTwoLayout, Button
>>> TwoByTwoLayout(top_left=Button(description="Top left"),
... top_right=Button(description="Top right"),
... bottom_left=Button(description="Bottom left"),
... bottom_right=Button(description="Bottom right"))
"""
# widget positions
top_left = Instance(Widget, allow_none=True)
top_right = Instance(Widget, allow_none=True)
bottom_left = Instance(Widget, allow_none=True)
bottom_right = Instance(Widget, allow_none=True)
# extra args
merge = Bool(default_value=True)
[docs] def __init__(self, **kwargs):
super().__init__(**kwargs)
self._update_layout()
def _update_layout(self):
grid_template_areas = [["top-left", "top-right"],
["bottom-left", "bottom-right"]]
all_children = {'top-left' : self.top_left,
'top-right' : self.top_right,
'bottom-left' : self.bottom_left,
'bottom-right' : self.bottom_right}
children = {position : child
for position, child in all_children.items()
if child is not None}
if not children:
return
for position, child in children.items():
child.layout.grid_area = position
if self.merge:
if len(children) == 1:
position = list(children.keys())[0]
grid_template_areas = [[position, position],
[position, position]]
else:
columns = ['left', 'right']
for i, column in enumerate(columns):
top, bottom = children.get('top-' + column), children.get('bottom-' + column)
i_neighbour = (i + 1) % 2
if top is None and bottom is None:
# merge each cell in this column with the neighbour on the same row
grid_template_areas[0][i] = grid_template_areas[0][i_neighbour]
grid_template_areas[1][i] = grid_template_areas[1][i_neighbour]
elif top is None:
# merge with the cell below
grid_template_areas[0][i] = grid_template_areas[1][i]
elif bottom is None:
# merge with the cell above
grid_template_areas[1][i] = grid_template_areas[0][i]
grid_template_areas_css = "\n".join('"{}"'.format(" ".join(line))
for line in grid_template_areas)
self.layout.grid_template_columns = '1fr 1fr'
self.layout.grid_template_rows = '1fr 1fr'
self.layout.grid_template_areas = grid_template_areas_css
self.children = tuple(children.values())
@observe("top_left", "bottom_left", "top_right", "bottom_right", "merge")
def _child_changed(self, change): #pylint: disable=unused-argument
self._update_layout()
Try Jupyter Widgets