Workbench docs and fonts extension (#258)

* docs: Add the workbench crash course to the dev guides.
* fonts: add support for font-stretch and remove size flexibility

docs/source/dev_guides/index.rst

@@ -14,11 +14,21 @@ the framework see the :ref:`arch_ref`.
     :hidden:
 
     stylesheets
+    workbenches
 
+.. This simply prevents the :doc: to create entries in the sidebar
+.. container::
 
-.. rubric::`stylesheets`
+    .. rubric:: :doc:`stylesheets`
 
     Styles sheets are a powerful feature which allow the developer to
     customize the visual appearance of a view independent from the
     view's structural definition. Inspired by CSS, but with all the
     dynamism provided by the Enaml language.
+
+    .. rubric:: :doc:`workbenches`
+
+    Enaml Workbenches provide a set of low-level components which can
+    be used to develop high-level plugin applications.  Workbenches 
+    enable the developer to write large UI applications which can be 
+    *safely extended at runtime* by other developers.

docs/source/dev_guides/workbenches.rst

@@ -0,0 +1,3 @@
+.. _workbenches:
+
+.. include:: ../../../examples/workbench/crash_course.rst

docs/source/examples/index.rst

@@ -157,3 +157,11 @@ Applib Examples
 .. toctree::
 
     ex_live_editor
+
+
+Workbench Examples
+--------------------------------------------------------------------------------
+
+.. toctree::
+
+    wb_sample

docs/source/examples/wb_sample.rst

@@ -0,0 +1,23 @@
+.. _wb_sample:
+
+Sample Workbench Example
+===============================================================================
+
+Here is the Python entry point for the example (:download:`download here
+<../../../examples/workbench/sample.py>`):
+
+.. literalinclude:: ../../../examples/workbench/sample.py
+    :language: python
+
+The resulting GUI looks like this (on Ubuntu):
+
+.. image:: images/wb_main.png
+
+There are three workspaces available in the dropdown menu, which are loaded 
+just prior to display.
+
+.. image:: images/wb_first.png
+
+.. image:: images/wb_second.png
+
+.. image:: images/wb_third.png

docs/source/get_started/index.rst

@@ -21,37 +21,39 @@ When you are comfortable with the topics here, have a look at the
     syntax
     layout
 
+.. This simply prevents the :doc: to create entries in the sidebar
+.. container::
 
-.. rubric::`introduction`
+    .. rubric:: :doc:`introduction`
 
     The introduction to Enaml explains the motivations behind the project
     and what it seeks to achieve in the context of the larger Python
     ecosystem. It presents the challenges inherent to UI development and
     how the declarative programming model is used to address them.
 
-.. rubric::`installation`
+    .. rubric:: :doc:`installation`
 
     The installation instructions present the steps needed to install
     Enaml and its dependencies.
 
-.. rubric::`anatomy`
+    .. rubric:: :doc:`anatomy`
 
     The building blocks of an Enaml application are presented in the
     form of a runnable example. The example shows how the various
     syntactic constructs and framework components combine to create a
     simple user interface application.
 
-.. rubric::`syntax`
+    .. rubric:: :doc:`syntax`
 
     Enaml defines a superset of Python that allows to define the UI in a 
     declarative way. One of the great features of Enaml is its ability to 
     automatically bind to data models through a rich set of operators. This 
     section describes the Enaml specific part of the syntax and how those 
-    operators are used to connect user defined data models to Enaml views and 
-    how they automatically keep the views up-to-date when the data in the 
-    models change at runtime.
+    operators are used to connect user defined data models to Enaml views 
+    and  how they automatically keep the views up-to-date when the data in 
+    the models change at runtime.
 
-.. rubric::`layout`
+    .. rubric:: :doc:`layout`
 
     The layout systems of typical user interface frameworks can quickly
     become tedious for all but the simplest of cases. Enaml sheds the

enaml/fonts.py

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2013, Nucleic Development Team.
+# Copyright (c) 2013-2018, Nucleic Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
@@ -11,7 +11,7 @@
 
 from atom.api import Coerced
 
-from .fontext import Font, FontStyle, FontCaps
+from .fontext import Font, FontStyle, FontCaps, FontStretch
 from enaml.compat import basestring
 
 
@@ -23,6 +23,20 @@
 }
 
 
+#: A mapping from CSS font strecth keyword to style enum
+_STRETCH = {
+    'ultra-condensed': FontStretch.UltraCondensed,
+    'extra-condensed': FontStretch.ExtraCondensed,
+    'condensed': FontStretch.Condensed,
+    'semi-condensed': FontStretch.SemiCondensed,
+    'normal': FontStretch.Unstretched,
+    'semi-expanded': FontStretch.SemiExpanded,
+    'expanded': FontStretch.Expanded,
+    'extra-expanded': FontStretch.ExtraExpanded,
+    'ultra-expanded': FontStretch.UltraExpanded,
+}
+
+
 #: A mapping from CSS font variant keyword to caps enum
 _VARIANTS = {
     'normal': FontCaps.MixedCase,
@@ -113,18 +127,15 @@ def parse_font(font):
     families = []
     optionals = []
     for token in tokens:
-        if token in _STYLES or token in _VARIANTS or token in _WEIGHTS:
-            if len(sizes) > 0 or len(families) > 0:
-                return None
+        if (token in _STYLES or token in _VARIANTS or
+                token in _WEIGHTS or token in _STRETCH):
             optionals.append(token)
         elif token in _SIZES or token[-2:] in _UNITS:
-            if len(families) > 0:
-                return None
             sizes.append(token)
         else:
             families.append(token)
 
-    if len(optionals) > 3:
+    if len(optionals) > 4:
         return None
     if len(sizes) != 1:
         return None
@@ -134,6 +145,7 @@ def parse_font(font):
     style = None
     variant = None
     weight = None
+    stretch = None
 
     for opt in optionals:
         if opt == 'normal':
@@ -150,6 +162,10 @@ def parse_font(font):
             if weight is not None:
                 return None
             weight = opt
+        elif opt in _STRETCH:
+            if stretch is not None:
+                return None
+            stretch = opt
         else:
             return None
 
@@ -168,8 +184,9 @@ def parse_font(font):
     weight = _WEIGHTS[weight] if weight else _WEIGHTS['normal']
     style = _STYLES[style] if style else _STYLES['normal']
     variant = _VARIANTS[variant] if variant else _VARIANTS['normal']
+    stretch = _STRETCH[stretch] if stretch else _STRETCH['normal']
 
-    return Font(family, size, weight, style, variant)
+    return Font(family, size, weight, style, variant, stretch)
 
 
 def coerce_font(font):
@@ -188,6 +205,10 @@ class FontMember(Coerced):
     the font will be None.  Font strings must be given in CSS grammar,
     e.g. 'bold 12pt arial', which is order dependant.
 
+    The order is the following:
+
+    style variant weight stretch size family
+
     """
     __slots__ = ()
 

enaml/qt/q_resource_helpers.py

@@ -1,16 +1,15 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2013-2017, Nucleic Development Team.
+# Copyright (c) 2013-2018, Nucleic Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #------------------------------------------------------------------------------
-from enaml.fontext import FontStyle, FontCaps
+from enaml.fontext import FontStyle, FontCaps, FontStretch
 
 from .QtCore import Qt, QSize
 from .QtGui import QColor, QFont, QImage, QIcon, QPixmap
 
-
 FONT_STYLES = {
     FontStyle.Normal: QFont.StyleNormal,
     FontStyle.Italic: QFont.StyleItalic,
@@ -27,6 +26,18 @@
 }
 
 
+FONT_STRETCH = {
+    FontStretch.UltraCondensed: QFont.UltraCondensed,
+    FontStretch.ExtraCondensed: QFont.ExtraCondensed,
+    FontStretch.Condensed: QFont.Condensed,
+    FontStretch.SemiCondensed: QFont.SemiCondensed,
+    FontStretch.Unstretched: QFont.Unstretched,
+    FontStretch.SemiExpanded: QFont.SemiExpanded,
+    FontStretch.Expanded: QFont.Expanded,
+    FontStretch.ExtraExpanded: QFont.ExtraExpanded,
+    FontStretch.UltraExpanded: QFont.UltraExpanded}
+
+
 ASPECT_RATIO_MODE = {
     'ignore': Qt.IgnoreAspectRatio,
     'keep': Qt.KeepAspectRatio,
@@ -209,6 +220,7 @@ def QFont_from_Font(font):
     qfont = QFont(font.family, font.pointsize, font.weight)
     qfont.setStyle(FONT_STYLES[font.style])
     qfont.setCapitalization(FONT_CAPS[font.caps])
+    qfont.setStretch(FONT_STRETCH[font.stretch])
     return qfont