Metadata-Version: 2.0
Name: colosseum
Version: 0.1.2
Summary: An independent implementation of the CSS layout algorithm.
Home-page: https://github.com/pybee/colosseum
Author: Russell Keith-Magee
Author-email: russell@keith-magee.com
License: New BSD
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: User Interfaces

Colosseum
=========

An independent implementation of the CSS layout algorithm. This
implementation is completely standalone - it isn't dependent on
a browser, and can be run over any box-like set of objects that
need to be laid out on a page (either physical or virtual)

At present, the implementation is partial; only **portions** of
the box and flexbox section of the specification are defined:

==========================================================================================  =======================================================================================
Name                                                                                        Value
==========================================================================================  =======================================================================================
width, height                                                                               positive number
min_width, min_height                                                                       positive number
max_width, max_height                                                                       positive number
left, right, top, bottom                                                                    number
margin, margin_left, margin_right, margin_top, margin_bottom                                number
padding, padding_left, padding_right, padding_top, padding_bottom                           positive number
border_width, border_left_width, border_right_width, border_top_width, border_bottom_width  positive number
flex_direction                                                                              ``"column"``, ``"row"``
justify_content                                                                             ``"flex-start"``, ``"center"``, ``"flex-end"``, ``"space-between"``, ``"space-around"``
align_items, align_self                                                                     ``"flex-start"``, ``"center"``, ``"flex-end"``, ``"stretch"``
flex                                                                                        positive number
flex_wrap                                                                                   ``"wrap"``, ``"nowrap"``
position                                                                                    ``"relative"``, ``"absolute"``
==========================================================================================  =======================================================================================

Quickstart
----------

In your virtualenv, install Colosseum::

    $ pip install colosseum

Colosseum provides a ``CSS`` class that allows you to define CSS
properties, and apply them can be applied to any DOM-like tree of
objects. There is no required base class; Colosseum will duck-type
any object providing the required API. The simplest possible DOM
node is the following:

    class MyDOMNode(object):
        def __init__(self, style, children=None, parent=None):
            self.parent = None
            self.children = []
            if children:
                for child in children:
                    self.children.append(child)
                    child.parent = self

            self.style = style.apply(self)

That is, a node must provide:

* a ``parent`` attribute, declaring the parent in the DOM tree; the root
  of the DOM tree has a ``parent`` of ``None``.

* a ``children`` attribute, containing the list of DOM child nodes.

* a ``style`` attribute, generated by calling ``apply()`` on a ``CSS``
  declaration.

With that a compliant DOM node definition, you can then and query the layout
that results::

    >>> from colosseum import CSS, ROW, COLUMN
    >>> node = MyDOMNode(style=CSS(width=1000, height=1000, flex_direction=ROW))
    >>> node.children.append(MyDOMNode(style=CSS(width=100, height=200)), parent=node)
    >>> node.children.appebd(MyDOMNode(style=CSS(width=300, height=150)), parent=node)
    >>> layout = node.style.layout
    >>> print(layout)
    <Layout (1000x1000 @ 0,0)>
    >>> layout.width
    1000
    >>> layout.height
    1000
    >>> layout.top
    0
    >>> layout.left
    0
    >>> for child in node.children:
    ...     print(child.style.layout)
    <Layout (100x200 @ 0,0)>
    <Layout (300x150 @ 100,0)>

Requesting the ``layout`` attribute of the style attribute forces the box
model to be evaluated. Once evaluated, the layout will be cached. Modifying
any CSS property on a node will mark the layout as dirty, and the layout will
be recomputed the next time the layout is accessed. For example, if we switch
the outer node to be a "column" flex box, rather than a "row" flex box, you'll
see the coordinates of the child boxes update to reflect a vertical, rather
than horizontal layout::

    >>> node.style.flex_direction = COLUMN
    >>> print(node.style.layout)
    <Layout (1000x1000 @ 0,0)>
    >>> for child in node.children:
    ...     print(child.style.layout)
    <Layout (100x200 @ 0,0)>
    <Layout (300x150 @ 0,200)>

Style attributes can also be set in bulk, using the ``set()`` method on
the style attribute::

    >>> node.style.set(width=1500, height=800)
    >>> print(node.style.layout)
    <Layout (1500x800 @ 0,0)>

Style attributes can also be removed by deleting the attribute on the
style attribute. The value of the property will revert to the default::

    >>> node.style.set(margin_top=10, margin_left=20)
    >>> print(node.style.layout)
    <Layout (1500x800 @ 20,10)>
    >>> del(node.style.margin_left)
    >>> print(node.style.margin_left)
    0
    >>> print(node.style.layout)
    <Layout (1500x800 @ 0,10)>

Community
---------

Colosseum is part of the `BeeWare suite`_. You can talk to the community through:

 * `@pybeeware on Twitter`_

 * The `BeeWare Users Mailing list`_, for questions about how to use the BeeWare suite.

 * The `BeeWare Developers Mailing list`_, for discussing the development of new features in the BeeWare suite, and ideas for new tools for the suite.

Contributing
------------

If you experience problems with Colosseum, `log them on GitHub`_. If you
want to contribute code, please `fork the code`_ and `submit a pull request`_.

.. _BeeWare suite: http://pybee.org
.. _Read The Docs: https://colosseum.readthedocs.io
.. _@pybeeware on Twitter: https://twitter.com/pybeeware
.. _BeeWare Users Mailing list: https://groups.google.com/forum/#!forum/beeware-users
.. _BeeWare Developers Mailing list: https://groups.google.com/forum/#!forum/beeware-developers
.. _log them on Github: https://github.com/pybee/colosseum/issues
.. _fork the code: https://github.com/pybee/colosseum
.. _submit a pull request: https://github.com/pybee/colosseum/pulls

Acknowledgements
----------------

The algorithm and test suite for this library is a language port of
`CSS-layout`_ project, open-sourced by Facebook.

.. _CSS-layout: https://github.com/facebook/css-layout


