<divid="unreleased-message"> You are reading an old version of the documentation (v3.3.3). For the latest version see <ahref="https://matplotlib.org/stable/devel/MEP/MEP23.html">https://matplotlib.org/stable/devel/MEP/MEP23.html</a></div>
<h1>MEP23: Multiple Figures per GUI window<aclass="headerlink" href="#mep23-multiple-figures-per-gui-window" title="Permalink to this headline">¶</a></h1>
<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>
<h2><aclass="toc-backref" href="#id4">Detailed description</a><aclass="headerlink" href="#detailed-description" title="Permalink to this headline">¶</a></h2>
<p>Under the current structure, every canvas has its own window.</p>
<p>This is and may continue to be the desired method of operation for
most use cases.</p>
<p>Sometimes when there are too many figures open at the same time, it is
desirable to be able to group these under the same window
<p>The proposed solution modifies <aclass="reference internal" href="../../api/backend_bases_api.html#matplotlib.backend_bases.FigureManagerBase" title="matplotlib.backend_bases.FigureManagerBase"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManagerBase</span></code></a> to contain and manage more
than one <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">canvas</span></code>. The settings parameter <codeclass="docutils literal notranslate"><aclass="reference external" href="../../tutorials/introductory/customizing.html?highlight=backend.multifigure#a-sample-matplotlibrc-file"><spanclass="pre">rcParams["backend.multifigure"]</span></a></code> control
when the <strong>MultiFigure</strong> behaviour is desired.</p>
<p><strong>Note</strong></p>
<p>It is important to note, that the proposed solution, assumes that the
[MEP22](<aclass="reference external" href="https://github.com/matplotlib/matplotlib/wiki/Mep22">https://github.com/matplotlib/matplotlib/wiki/Mep22</a>) is
already in place. This is simply because the actual implementation of
the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Toolbar</span></code> makes it pretty hard to switch between canvases.</p>
</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>The first implementation will be done in GTK3 using a Notebook as
canvas container.</p>
<divclass="section" id="figuremanagerbase">
<h3><aclass="toc-backref" href="#id6"><aclass="reference internal" href="../../api/backend_bases_api.html#matplotlib.backend_bases.FigureManagerBase" title="matplotlib.backend_bases.FigureManagerBase"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManagerBase</span></code></a></a><aclass="headerlink" href="#figuremanagerbase" title="Permalink to this headline">¶</a></h3>
<p>will add the following new methods</p>
<ulclass="simple">
<li><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">add_canvas</span></code>: To add a canvas to an existing <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManager</span></code> object</li>
<li><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">remove_canvas</span></code>: To remove a canvas from a <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManager</span></code> object,
if it is the last one, it will be destroyed</li>
<li><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">move_canvas</span></code>: To move a canvas from one <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManager</span></code> to another.</li>
<li><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">set_canvas_title</span></code>: To change the title associated with a specific
canvas container</li>
<li><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">get_canvas_title</span></code>: To get the title associated with a specific
canvas container</li>
<li><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">get_active_canvas</span></code>: To get the canvas that is in the foreground and
is subject to the gui events. There is no <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">set_active_canvas</span></code>
because the active canvas, is defined when <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">show</span></code> is called on a
<h3><aclass="toc-backref" href="#id7"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">new_figure_manager</span></code></a><aclass="headerlink" href="#new-figure-manager" title="Permalink to this headline">¶</a></h3>
<p>To control which <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManager</span></code> will contain the new figures, an
extra optional parameter <em>figuremanager</em> will be added, this parameter
value will be passed to <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">new_figure_manager_given_figure</span></code></p>
<h3><aclass="toc-backref" href="#id8"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">new_figure_manager_given_figure</span></code></a><aclass="headerlink" href="#new-figure-manager-given-figure" title="Permalink to this headline">¶</a></h3>
<ulclass="simple">
<li>If <em>figuremanager</em> parameter is given, this <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManager</span></code> object
will be used instead of creating a new one.</li>
<li>If <codeclass="docutils literal notranslate"><spanclass="pre">rcParams['backend.multifigure']</span></code> is True: The last
<codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManager</span></code> object will be used instead of creating a new one.</li>
</ul>
</div>
<divclass="section" id="navigationbase">
<h3><aclass="toc-backref" href="#id9"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">NavigationBase</span></code></a><aclass="headerlink" href="#navigationbase" title="Permalink to this headline">¶</a></h3>
<p>Modifies the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">NavigationBase</span></code> to keep a list of canvases, directing
the actions to the active one</p>
</div>
</div>
<divclass="section" id="backward-compatibility">
<h2><aclass="toc-backref" href="#id10">Backward compatibility</a><aclass="headerlink" href="#backward-compatibility" title="Permalink to this headline">¶</a></h2>
<p>For the <strong>MultiFigure</strong> properties to be visible, the user has to
activate them directly setting <codeclass="docutils literal notranslate"><spanclass="pre">rcParams['backend.multifigure']</span><spanclass="pre">=</span>
<spanclass="pre">True</span></code></p>
<p>It should be backwards compatible for backends that adhere to the
current <aclass="reference internal" href="../../api/backend_bases_api.html#matplotlib.backend_bases.FigureManagerBase" title="matplotlib.backend_bases.FigureManagerBase"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManagerBase</span></code></a> structure even if they have not
implemented the <strong>MultiFigure</strong> magic yet.</p>
</div>
<divclass="section" id="alternatives">
<h2><aclass="toc-backref" href="#id11">Alternatives</a><aclass="headerlink" href="#alternatives" title="Permalink to this headline">¶</a></h2>
<p>Instead of modifying the <aclass="reference internal" href="../../api/backend_bases_api.html#matplotlib.backend_bases.FigureManagerBase" title="matplotlib.backend_bases.FigureManagerBase"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">FigureManagerBase</span></code></a> it could be possible to add
a parallel class, that handles the cases where
<codeclass="docutils literal notranslate"><spanclass="pre">rcParams['backend.multifigure']</span><spanclass="pre">=</span><spanclass="pre">True</span></code>. This will warranty that
there won't be any problems with custom made backends, but also makes