Skip to content

Commit 7f5a885

Browse files
tacaswelltacaswell
committed
DOC: re-order to put un-managed first
1 parent c60c60e commit 7f5a885

File tree

1 file changed

+85
-82
lines changed

1 file changed

+85
-82
lines changed

‎docs/source/index.rst‎

Lines changed: 85 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -46,38 +46,77 @@ If you want to be sure that this code does not secretly depend on pyplot run ::
4646
which will prevent pyplot from being imported!
4747

4848

49-
Globally Managed Figures
50-
========================
5149

50+
Selecting the GUI toolkit
51+
=========================
5252

53-
The `mpl_gui.global_figures` module provides a direct analogy to the
54-
`matplotlib.pyplot` behavior of having a global registry of figures. Thus, any
55-
figures created via the functions in `.global_figures` will remain alive until they
56-
have been cleared from the registry (and the user has dropped all other
57-
references). While it can be convenient, it carries with it the risk inherent
58-
in any use of global state.
53+
`mpl_gui` makes use of `Matplotlib backends
54+
<https://matplotlib.org/stable/users/explain/backends.html>`_ for actually
55+
providing the GUI bindings. Analagous to `matplotlib.use` and
56+
`matplotlib.pyplot.switch_backend` `mpl_gui` provides
57+
`mpl_gui.select_gui_toolkit` to select which GUI toolkit is used.
58+
`~mpl_gui.select_gui_toolkit` has the same fall-back behavior as
59+
`~matplotlib.pyplot` and stores its state in :rc:`backend`.
5960

60-
The `matplotlib.pyplot` API related to figure creation, showing, and closing is a drop-in replacement:
61+
`mpl_gui` will
62+
consistently co-exist with `matplotlib.pyplot` managed Figures in the same
63+
process.
6164

62-
::
6365

64-
import mpl_gui.global_figures as gfigs
6566

66-
fig = gfigs.figure()
67-
fig, ax = gfigs.subplots()
68-
fig, axd = gfigs.subplot_mosaic('AA\nCD')
67+
User Managed Figures
68+
====================
6969

70-
gfigs.show(block=True) # blocks until all figures are closed
71-
gfigs.show(block=True, timeout=1000) # blocks for up to 1s or all figures are closed
72-
gfigs.show(block=False) # does not block
73-
gfigs.show() # depends on if in "interacitve mode"
70+
There are cases where having such a registry may be too much implicit state.
71+
For such cases the underlying tools that `.FigureRegistry` are built on are
72+
explicitly available ::
7473

75-
gfigs.ion() # turn on interactive mode
76-
gfigs.ioff() # turn off interactive mode
77-
gfigs.is_interactive() # query interactive state
74+
import mpl_gui as mg
75+
from matplotlib.figure import Figure
7876

79-
gfigs.close('all') # close all open figures
80-
gfigs.close(fig) # close a particular figure
77+
fig1 = Figure(label='A Label!')
78+
79+
fig2 = Figure()
80+
81+
mg.display(fig1, fig2)
82+
83+
84+
which will show both figures and block until they are closed. As part of the
85+
"showing" process, the correct GUI objects will be created, put on the
86+
screen, and the event loop for the host GUI framework is run.
87+
88+
Similar to `plt.ion<matplotlib.pyplot.ion>` and
89+
`plt.ioff<matplotlib.pyplot.ioff>`, we provide `mg.ion()<mpl_gui.ion>` and
90+
`mg.ioff()<mpl_gui.ioff>` which have identical semantics. Thus ::
91+
92+
import mpl_gui as mg
93+
from matplotlib.figure import Figure
94+
95+
mg.ion()
96+
print(mg.is_interactive())
97+
fig = Figure()
98+
99+
mg.display([fig]) # will not block
100+
101+
mg.ioff()
102+
print(mg.is_interactive())
103+
mg.display(fig) # will block!
104+
105+
106+
As with `plt.show<matplotlib.pyplot.show>`, you can explicitly control the
107+
blocking behavior of `mg.display<mpl_gui.display>` via the *block* keyword argument ::
108+
109+
import mpl_gui as mg
110+
from matplotlib.figure import Figure
111+
112+
fig = Figure(label='control blocking')
113+
114+
mg.display(fig, block=False) # will never block
115+
mg.display(fig, block=True) # will always block
116+
117+
118+
The interactive state is shared Matplotlib and can also be controlled with
119+
`matplotlib.interactive` and queried via `matplotlib.is_interactive`.
81120

82121

83122

@@ -150,73 +189,37 @@ The `.global_figures` module is implemented by having a singleton `.FigureRegist
150189
at the module level.
151190

152191

153-
User Managed Figures
154-
====================
155-
156-
There are cases where having such a registry may be too much implicit state.
157-
For such cases the underlying tools that `.FigureRegistry` are built on are
158-
explicitly available ::
159-
160-
import mpl_gui as mg
161-
from matplotlib.figure import Figure
162-
163-
fig1 = Figure(label='A Label!')
164-
165-
fig2 = Figure()
166-
167-
mg.display(fig1, fig2)
168-
169-
170-
which will show both figures and block until they are closed. As part of the
171-
"showing" process, the correct GUI objects will be created, put on the
172-
screen, and the event loop for the host GUI framework is run.
173-
174-
Similar to `plt.ion<matplotlib.pyplot.ion>` and
175-
`plt.ioff<matplotlib.pyplot.ioff>`, we provide `mg.ion()<mpl_gui.ion>` and
176-
`mg.ioff()<mpl_gui.ioff>` which have identical semantics. Thus ::
177-
178-
import mpl_gui as mg
179-
from matplotlib.figure import Figure
180192

181-
mg.ion()
182-
print(mg.is_interactive())
183-
fig = Figure()
184193

185-
mg.display([fig]) # will not block
186-
187-
mg.ioff()
188-
print(mg.is_interactive())
189-
mg.display(fig) # will block!
190-
191-
192-
As with `plt.show<matplotlib.pyplot.show>`, you can explicitly control the
193-
blocking behavior of `mg.display<mpl_gui.display>` via the *block* keyword argument ::
194-
195-
import mpl_gui as mg
196-
from matplotlib.figure import Figure
194+
Globally Managed Figures
195+
========================
197196

198-
fig = Figure(label='control blocking')
199197

200-
mg.display(fig, block=False) # will never block
201-
mg.display(fig, block=True) # will always block
198+
The `mpl_gui.global_figures` module provides a direct analogy to the
199+
`matplotlib.pyplot` behavior of having a global registry of figures. Thus, any
200+
figures created via the functions in `.global_figures` will remain alive until they
201+
have been cleared from the registry (and the user has dropped all other
202+
references). While it can be convenient, it carries with it the risk inherent
203+
in any use of global state.
202204

205+
The `matplotlib.pyplot` API related to figure creation, showing, and closing is a drop-in replacement:
203206

204-
The interactive state is shared Matplotlib and can also be controlled with
205-
`matplotlib.interactive` and queried via `matplotlib.is_interactive`.
207+
::
206208

209+
import mpl_gui.global_figures as gfigs
207210

211+
fig = gfigs.figure()
212+
fig, ax = gfigs.subplots()
213+
fig, axd = gfigs.subplot_mosaic('AA\nCD')
208214

209-
Selecting the GUI toolkit
210-
=========================
215+
gfigs.show(block=True) # blocks until all figures are closed
216+
gfigs.show(block=True, timeout=1000) # blocks for up to 1s or all figures are closed
217+
gfigs.show(block=False) # does not block
218+
gfigs.show() # depends on if in "interacitve mode"
211219

212-
`mpl_gui` makes use of `Matplotlib backends
213-
<https://matplotlib.org/stable/users/explain/backends.html>`_ for actually
214-
providing the GUI bindings. Analagous to `matplotlib.use` and
215-
`matplotlib.pyplot.switch_backend` `mpl_gui` provides
216-
`mpl_gui.select_gui_toolkit` to select which GUI toolkit is used.
217-
`~mpl_gui.select_gui_toolkit` has the same fall-back behavior as
218-
`~matplotlib.pyplot` and stores its state in :rc:`backend`.
220+
gfigs.ion() # turn on interactive mode
221+
gfigs.ioff() # turn off interactive mode
222+
gfigs.is_interactive() # query interactive state
219223

220-
`mpl_gui` will
221-
consistently co-exist with `matplotlib.pyplot` managed Figures in the same
222-
process.
224+
gfigs.close('all') # close all open figures
225+
gfigs.close(fig) # close a particular figure

0 commit comments

Comments
 (0)