Skip to content

Commit 1cc1256

Browse files
tobias47n9eWeatherGod
tobias47n9e
authored and
WeatherGod
committed
user guide structure
1 parent ee98bcc commit 1cc1256

File tree

5 files changed

+374
-0
lines changed

5 files changed

+374
-0
lines changed

‎doc/users/developer.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ Advanced Guide
1919
transforms_tutorial.rst
2020
path_tutorial.rst
2121
recipes.rst
22+
index_user_interface.rst

‎doc/users/index_user_interface.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.. _index_user_interface:
2+
3+
**************************
4+
User interface integration
5+
**************************
6+
7+
.. toctree::
8+
9+
ui_introduction.rst
10+
ui_glade.rst
11+
ui_gtk.rst
12+

‎doc/users/ui_glade.rst‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
.. _ui_glade:
2+
3+
Glade user interface designer
4+
=============================
5+
6+
Glade is a rapid-application-development program (RAD) or graphical user-interface-builder, that allows the easy creation of Gtk-applications. The user interface is stored in an XML-file (file extension: *".glade"*), which is called by the main program. The older version of Glade, 3.8.x, targets Gtk+ 2.x applications, while the newer 3.16.x, targets Gtk+ 3.x.
7+
8+
.. _ui_glade_316_python3:
9+
10+
Glade 3.16 example using Python 3
11+
---------------------------------
12+
This example uses Glade 3.16.x and Python 3.x. In order to understand the code it is recommended to work through the Python-GtK3-Tutorial: http://python-gtk-3-tutorial.readthedocs.org/en/latest/.
13+
14+
The first step is to start Glade and open a new project. Drag a *GtkApplicationWindow* into the work area. In the bottom-right menu you can change the default name from *"applicationwindow1"* to *"window1"*. This is the designation that the window will have in the Python 3 code and in Glade for certain actions. In the *Signals* tab of the same menu open the *GtkWidget* tree and find the *destroy* entry. This is the widget that will allow you to connect the program with the close-button of the window. Enter the action *"on_window1_destroy"* (window1 being the name we gave this window).
15+
16+
In the next step we need to create a container to place the Matplotlib-widget. This tutorial uses a *GtkScrolledWindow*, which you can drag-and-drop on the *GtkApplicationWindow*. Now we are going to save the Glade file into directory with the name *"mpl_with_glade_316.glade"*. Note that there are many options in Glade you can additionally set like the default size of the window. These options are fairly easy to set.
17+
18+
.. figure:: ../_static/mpl_with_glade_1.png
19+
:width: 50 %
20+
:alt: Figure of the Glade interface, highlighting some steps in the interface.
21+
:align: left
22+
23+
**Figure 1:** First steps of designing a simple user interface in Glade. Allow the window to be closed (a). The GtkScrolledWindow button (b) has to be placed on the main window (c).
24+
25+
The code of the finished example will look something like this:
26+
27+
::
28+
29+
<?xml version="1.0" encoding="UTF-8"?>
30+
<!-- Generated with glade 3.16.1 -->
31+
<interface>
32+
<requires lib="gtk+" version="3.10"/>
33+
<object class="GtkApplicationWindow" id="window1">
34+
<property name="can_focus">False</property>
35+
<property name="title" translatable="yes">Matplotlib</property>
36+
<property name="default_width">800</property>
37+
<property name="default_height">600</property>
38+
<signal name="destroy" handler="on_window1_destroy" swapped="no"/>
39+
<child>
40+
<object class="GtkScrolledWindow" id="scrolledwindow1">
41+
<property name="visible">True</property>
42+
<property name="can_focus">True</property>
43+
<property name="border_width">10</property>
44+
<property name="shadow_type">in</property>
45+
<child>
46+
<placeholder/>
47+
</child>
48+
</object>
49+
</child>
50+
</object>
51+
</interface>
52+
53+
The Python 3 file that executes the program can look like this:
54+
55+
::
56+
57+
#!/usr/bin/env python3
58+
59+
from gi.repository import Gtk, Gio
60+
61+
from matplotlib.figure import Figure
62+
from matplotlib.axes import Subplot
63+
from numpy import arange, sin, pi
64+
from matplotlib.backends.backend_gtk3agg import FigureCanvasGTK3Agg as FigureCanvas
65+
66+
import sys
67+
68+
class Window1Signals:
69+
def on_window1_destroy(self, widget):
70+
Gtk.main_quit()
71+
72+
def main():
73+
builder = Gtk.Builder()
74+
builder.add_objects_from_file("mpl_with_glade_316.glade", ("window1", "") )
75+
builder.connect_signals(Window1Signals())
76+
window = builder.get_object("window1")
77+
sw = builder.get_object("scrolledwindow1")
78+
79+
#Start of Matplotlib specific code
80+
figure = Figure(figsize=(8,6), dpi=71)
81+
axis = figure.add_subplot(111)
82+
t = arange(0.0, 3.0, 0.01)
83+
s = sin(2*pi*t)
84+
axis.plot(t,s)
85+
86+
axis.set_xlabel('time [s]')
87+
axis.set_ylabel('voltage [V]')
88+
89+
canvas = FigureCanvas(figure) # a Gtk.DrawingArea
90+
canvas.set_size_request(800,600)
91+
sw.add_with_viewport(canvas)
92+
#End of Matplotlib specific code
93+
94+
window.show_all()
95+
Gtk.main()
96+
97+
if __name__ == "__main__":
98+
main()
99+
100+
Notice that we defined a function *"the on_window1_destroy"* that we named in Glade. This function ensures that closing the window will quit the Gtk-application. The *GtkScrolledWindow* is first connected through the *Gtk.Builder*, then the Matplotlib-plot is placed in a *FigureCanvas* and this canvas is then added to the *GtkScrolledWindow*.
101+
102+
You can also add the *Matplotlib-NavigationToolbar* to the example. This requires a division of the screen into two scrolled windows (See **Figure 2**).
103+
104+
.. figure:: ../_static/mpl_with_glade_2.png
105+
:width: 50 %
106+
:alt: Figure of the Glade interface, showing how to divide the window into 2 scrolled windows.
107+
:align: left
108+
109+
**Figure 2:** The interface for this example consists of a *GtkApplicationWindow* which is divided into 2 rows using a *GtkBox*. A *GtkScrolledWindow* is placed in both cells (See tree view in upper-right corner).
110+
111+
The new Glade-code:
112+
113+
::
114+
115+
<?xml version="1.0" encoding="UTF-8"?>
116+
<!-- Generated with glade 3.16.1 -->
117+
<interface>
118+
<requires lib="gtk+" version="3.10"/>
119+
<object class="GtkApplicationWindow" id="window1">
120+
<property name="can_focus">False</property>
121+
<property name="title" translatable="yes">Matplotlib</property>
122+
<property name="default_width">800</property>
123+
<property name="default_height">600</property>
124+
<signal name="destroy" handler="on_window1_destroy" swapped="no"/>
125+
<child>
126+
<object class="GtkBox" id="box2">
127+
<property name="visible">True</property>
128+
<property name="can_focus">False</property>
129+
<property name="orientation">vertical</property>
130+
<child>
131+
<object class="GtkScrolledWindow" id="scrolledwindow1">
132+
<property name="width_request">700</property>
133+
<property name="height_request">600</property>
134+
<property name="visible">True</property>
135+
<property name="can_focus">True</property>
136+
<property name="border_width">10</property>
137+
<property name="shadow_type">in</property>
138+
<child>
139+
<placeholder/>
140+
</child>
141+
</object>
142+
<packing>
143+
<property name="expand">False</property>
144+
<property name="fill">True</property>
145+
<property name="position">0</property>
146+
</packing>
147+
</child>
148+
<child>
149+
<object class="GtkScrolledWindow" id="scrolledwindow2">
150+
<property name="visible">True</property>
151+
<property name="can_focus">True</property>
152+
<property name="border_width">10</property>
153+
<property name="shadow_type">in</property>
154+
<child>
155+
<placeholder/>
156+
</child>
157+
</object>
158+
<packing>
159+
<property name="expand">False</property>
160+
<property name="fill">True</property>
161+
<property name="position">1</property>
162+
</packing>
163+
</child>
164+
</object>
165+
</child>
166+
</object>
167+
</interface>
168+
169+
The new Pyhton code:
170+
171+
::
172+
173+
#!/usr/bin/env python3
174+
175+
from gi.repository import Gtk, Gio
176+
177+
from matplotlib.figure import Figure
178+
from matplotlib.axes import Subplot
179+
from numpy import arange, sin, pi
180+
from matplotlib.backends.backend_gtk3agg import FigureCanvasGTK3Agg as FigureCanvas
181+
from matplotlib.backends.backend_gtk3 import NavigationToolbar2GTK3 as NavigationToolbar
182+
183+
import sys
184+
185+
class Window1Signals:
186+
def on_window1_destroy(self, widget):
187+
Gtk.main_quit()
188+
189+
def main():
190+
builder = Gtk.Builder()
191+
builder.add_objects_from_file("mpl_with_glade_316_navigationtoolbar.glade", ("window1", "") )
192+
builder.connect_signals(Window1Signals())
193+
window = builder.get_object("window1")
194+
sw1 = builder.get_object("scrolledwindow1")
195+
sw2 = builder.get_object("scrolledwindow2")
196+
197+
#Start of Matplotlib specific code
198+
figure = Figure(figsize=(4,3), dpi=71)
199+
axis = figure.add_subplot(111)
200+
t = arange(0.0, 3.0, 0.01)
201+
s = sin(2*pi*t)
202+
axis.plot(t,s)
203+
204+
axis.set_xlabel('time [s]')
205+
axis.set_ylabel('voltage [V]')
206+
207+
canvas = FigureCanvas(figure)
208+
sw1.add_with_viewport(canvas)
209+
210+
toolbar = NavigationToolbar(canvas, window)
211+
sw2.add_with_viewport(toolbar)
212+
#End of Matplotlib specific code
213+
214+
window.show_all()
215+
Gtk.main()
216+
217+
if __name__ == "__main__":
218+
main()
219+
220+
The finished second example is shown in **Figure 3**.
221+
222+
.. figure:: ../_static/mpl_with_glade_3.png
223+
:width: 50 %
224+
:alt: Figure of the Glade interface, showing how to divide the window into 2 scrolled windows.
225+
:align: left
226+
227+
**Figure 3:** The finished program (shown here in Ubuntu 14.04).

‎doc/users/ui_gtk.rst‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
.. _ui_Gtk:
2+
3+
Gtk+
4+
====
5+
Gtk+ or Gnome-toolkit is a graphical user interfaces toolkit with different language bindings. The resulting user interface is designed directly within the program code (as opposed to using a graphical-user-interface-designer like Glade). This works well for small applications with simple user interfaces.
6+
7+
.. _ui_gtk3_python3:
8+
9+
Gtk+ 3 example using Python 3
10+
---------------------------------
11+
This example uses the Python-3-bindings of Gtk. In order to understand the code it is recomended to work through the Python-GtK3-Tutorial: http://python-gtk-3-tutorial.readthedocs.org/en/latest/.
12+
13+
The code for a simple window with plot looks like this:
14+
15+
::
16+
17+
#!/usr/bin/env python
18+
"""
19+
demonstrate adding a FigureCanvasGTK3Agg widget to a Gtk.ScrolledWindow
20+
using GTK3 accessed via pygobject
21+
"""
22+
23+
from gi.repository import Gtk
24+
25+
from matplotlib.figure import Figure
26+
from numpy import arange, sin, pi
27+
from matplotlib.backends.backend_gtk3agg import FigureCanvasGTK3Agg as FigureCanvas
28+
29+
win = Gtk.Window()
30+
win.connect("delete-event", Gtk.main_quit )
31+
win.set_default_size(400,300)
32+
win.set_title("Embedding in GTK")
33+
34+
f = Figure(figsize=(5,4), dpi=100)
35+
a = f.add_subplot(111)
36+
t = arange(0.0,3.0,0.01)
37+
s = sin(2*pi*t)
38+
a.plot(t,s)
39+
40+
sw = Gtk.ScrolledWindow()
41+
win.add (sw)
42+
# A scrolled window border goes outside the scrollbars and viewport
43+
sw.set_border_width (10)
44+
45+
canvas = FigureCanvas(f) # a Gtk.DrawingArea
46+
canvas.set_size_request(800,600)
47+
sw.add_with_viewport (canvas)
48+
49+
win.show_all()
50+
Gtk.main()
51+
52+
The same example showing the Matplotlib-toolbar:
53+
54+
::
55+
56+
#!/usr/bin/env python
57+
"""
58+
demonstrate NavigationToolbar with GTK3 accessed via pygobject
59+
"""
60+
61+
from gi.repository import Gtk
62+
63+
from matplotlib.figure import Figure
64+
from numpy import arange, sin, pi
65+
from matplotlib.backends.backend_gtk3agg import FigureCanvasGTK3Agg as FigureCanvas
66+
from matplotlib.backends.backend_gtk3 import NavigationToolbar2GTK3 as NavigationToolbar
67+
68+
win = Gtk.Window()
69+
win.connect("delete-event", Gtk.main_quit )
70+
win.set_default_size(400,300)
71+
win.set_title("Embedding in GTK")
72+
73+
f = Figure(figsize=(5,4), dpi=100)
74+
a = f.add_subplot(1,1,1)
75+
t = arange(0.0,3.0,0.01)
76+
s = sin(2*pi*t)
77+
a.plot(t,s)
78+
79+
vbox = Gtk.VBox()
80+
win.add(vbox)
81+
82+
# Add canvas to vbox
83+
canvas = FigureCanvas(f) # a Gtk.DrawingArea
84+
vbox.pack_start(canvas, True, True, 0)
85+
86+
# Create toolbar
87+
toolbar = NavigationToolbar(canvas, win)
88+
vbox.pack_start(toolbar, False, False, 0)
89+
90+
win.show_all()
91+
Gtk.main()
92+
93+
94+
95+
96+

‎doc/users/ui_introduction.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. _ui_introduction:
2+
3+
Introduction
4+
============
5+
6+
Matplotlib can be placed as a widget into a variety of user-interface frameworks (or user-interface toolkits). This allows one to build custom applications that can display Matplotlib-plots.
7+
8+
.. figure:: ../_static/mpl_with_glade_3.png
9+
:width: 50 %
10+
:alt: Figure of the Glade interface, showing how to divide the window into 2 scrolled windows.
11+
:align: center
12+
13+
**Figure 1:** Example of Matplotlib embedded as a widget in a user-interface framework. This example shows the GTK+ 3.x framework under Ubuntu 14.04. *Note that the appearance of the window will depend on the operating system and can additonialy be customized.*
14+
15+
The different frameworks offer different features and programming-language bindings. Most offer graphical user-interface-builders (or rapid-application-development programs) that are useful for larger applications.
16+
17+
The following user-interface frameworks are supported (graphical builders in brackets):
18+
19+
- Gtk+
20+
21+
- Gtk+ 2.x (Glade 3.8.x)
22+
- Gtk+ 3.x (Glade 3.16.x)
23+
24+
- Qt (Qt-Creator)
25+
26+
- Qt4
27+
- Qt5
28+
- Tk
29+
- Wx
30+
31+
The different frameworks offer different features and programming-language bindings. The appearance of the user interface will be, by default, similar to the style of the operating system, but can be customized.
32+
33+
.. figure:: ../_static/mpl_with_glade_2.png
34+
:width: 50 %
35+
:alt: Glade window as an example for a graphical user-interface-builder or rapid-application development program.
36+
:align: center
37+
38+
**Figure 2:** Glade is just one of many programs that can be used to design more complex user interfaces using a graphical interface.

0 commit comments

Comments
 (0)