<divid="unreleased-message"> You are reading an old version of the documentation (v3.2.2). For the latest version see <ahref="https://matplotlib.org/stable/devel/MEP/MEP26.html">https://matplotlib.org/stable/devel/MEP/MEP26.html</a></div>
<h2><aclass="toc-backref" href="#id2">Branches and Pull requests</a><aclass="headerlink" href="#branches-and-pull-requests" title="Permalink to this headline">¶</a></h2>
</div>
<divclass="section" id="abstract">
<h2><aclass="toc-backref" href="#id3">Abstract</a><aclass="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
<p>This MEP proposes a new stylesheet implementation to allow more
comprehensive and dynamic styling of artists.</p>
<p>The current version of matplotlib (1.4.0) allows stylesheets based on
the rcParams syntax to be applied before creation of a plot. The
methodology below proposes a new syntax, based on CSS, which would
allow styling of individual artists and properties, which can be
applied dynamically to existing objects.</p>
<p>This is related to (and makes steps toward) the overall goal of moving
to a DOM/tree-like architecture.</p>
</div>
<divclass="section" id="detailed-description">
<h2><aclass="toc-backref" href="#id4">Detailed description</a><aclass="headerlink" href="#detailed-description" title="Permalink to this headline">¶</a></h2>
<p>Currently, the look and appearance of existing artist objects (figure,
axes, Line2D etc...) can only be updated via <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">set_</span></code> and <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">get_</span></code> methods
on the artist object, which is quite laborious, especially if no
reference to the artist(s) has been stored. The new style sheets
introduced in 1.4 allow styling before a plot is created, but do not
offer any means to dynamically update plots or distinguish between
artists of the same type (i.e. to specify the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">line</span><spanclass="pre">color</span></code> and <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">line</span>
<p>The initial development should concentrate on allowing styling of
artist primitives (those <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">artists</span></code> that do not contain other
<codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">artists</span></code>), and further development could expand the CSS syntax rules
and parser to allow more complex styling. See the appendix for a list
of primitives.</p>
<p>The new methodology would require development of a number of steps:</p>
<ulclass="simple">
<li>A new stylesheet syntax (likely based on CSS) to allow selection of
artists by type, class, id etc...</li>
<li>A mechanism by which to parse a stylesheet into a tree</li>
<li>A mechanism by which to translate the parse-tree into something
which can be used to update the properties of relevant
artists. Ideally this would implement a method by which to traverse
the artists in a tree-like structure.</li>
<li>A mechanism by which to generate a stylesheet from existing artist
properties. This would be useful to allow a user to export a
stylesheet from an existing figure (where the appearance may have
been set using the matplotlib API)...</li>
</ul>
</div>
<divclass="section" id="implementation">
<h2><aclass="toc-backref" href="#id5">Implementation</a><aclass="headerlink" href="#implementation" title="Permalink to this headline">¶</a></h2>
<p>It will be easiest to allow a '3rd party' to modify/set the style of
an artist if the 'style' is created as a separate class and store
against the artist as a property. The <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">GraphicsContext</span></code> class already
provides a the basis of a <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Style</span></code> class and an artists <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">draw</span></code> method can
be refactored to use the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Style</span></code> class rather than setting up it's own
<codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">GraphicsContext</span></code> and transferring it's style-related properties to
it. A minimal example of how this could be implemented is shown here:
<p>Each rule can have any number of <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">attribute</span></code>: <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">value</span></code> pairs, and a
stylesheet can have any number of rules.</p>
<p>The initial syntax is designed only for <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">artist</span></code> primitives. It does
not address the question of how to set properties on <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">container</span></code> types
(whose properties may themselves be <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">artists</span></code> with settable
properties), however, a future solution to this could simply be nested
<p>The regex for matching the artist type selector (<codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">ArtistIdent</span></code> in the BNF grammar) would be:</p>
<p>A <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">gid</span></code> can be any string, so the regex could be as follows:</p>
<h4><aclass="toc-backref" href="#id10">Attributes and values</a><aclass="headerlink" href="#attributes-and-values" title="Permalink to this headline">¶</a></h4>
<ulclass="simple">
<li><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Attributes</span></code> are any valid (settable) property for the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">artist</span></code> in question.</li>
<li><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Values</span></code> are any valid value for the property (Usually a string, or number).</li>
</ul>
</div>
</div>
<divclass="section" id="parsing">
<h3><aclass="toc-backref" href="#id11">Parsing</a><aclass="headerlink" href="#parsing" title="Permalink to this headline">¶</a></h3>
<p>Parsing would consist of breaking the stylesheet into tokens (the
python cookbook gives a nice tokenizing recipe on page 66), applying
the syntax rules and constructing a <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Tree</span></code>. This requires defining the
grammar of the stylesheet (again, we can borrow from CSS) and writing
a parser. Happily, there is a recipe for this in the python cookbook
<h3><aclass="toc-backref" href="#id12">Visitor pattern for matplotlib figure</a><aclass="headerlink" href="#visitor-pattern-for-matplotlib-figure" title="Permalink to this headline">¶</a></h3>
<p>In order to apply the stylesheet rules to the relevant artists, we
need to 'visit' each artist in a figure and apply the relevant rule.
Here is a visitor class (again, thanks to python cookbook), where each
<codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">node</span></code> would be an artist in the figure. A <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">visit_</span></code> method would need
to be implemented for each mpl artist, to handle the different
<p>An <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">evaluator</span></code> class would then take the stylesheet rules and
implement the visitor on each one of them.</p>
</div>
</div>
<divclass="section" id="backward-compatibility">
<h2><aclass="toc-backref" href="#id13">Backward compatibility</a><aclass="headerlink" href="#backward-compatibility" title="Permalink to this headline">¶</a></h2>
<p>Implementing a separate <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Style</span></code> class would break backward
compatibility as many get/set methods on an artist would become
redundant. While it would be possible to alter these methods to hook
into the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Style</span></code> class (stored as a property against the artist), I
would be in favor of simply removing them to both neaten/simplify the
codebase and to provide a simple, uncluttered API...</p>
</div>
<divclass="section" id="alternatives">
<h2><aclass="toc-backref" href="#id14">Alternatives</a><aclass="headerlink" href="#alternatives" title="Permalink to this headline">¶</a></h2>
<p>No alternatives, but some of the ground covered here overlaps with
MEP25, which may assist in this development</p>
</div>
<divclass="section" id="appendix">
<h2><aclass="toc-backref" href="#id15">Appendix</a><aclass="headerlink" href="#appendix" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="matplotlib-primitives">
<h3><aclass="toc-backref" href="#id16">Matplotlib primitives</a><aclass="headerlink" href="#matplotlib-primitives" title="Permalink to this headline">¶</a></h3>
<p>This will form the initial selectors which stylesheets can use.</p>