80
>Chapter 12. Constructing Graphical Interfaces with PLplot</H1
82
>This chapter presents some ideas on how to use PLplot in conjunction
83
with Tcl, Tk, and [incr Tcl] to construct graphical interfaces to
80
>Chapter 13. Embedding Plots in Graphical User Interfaces</H1
82
>This chapter describes how to embed plots in graphical user interfaces.
90
>The PlplotCanvas Widget for Gnome/GTK Applications</A
93
> Plots can be embedded into Gnome/GTK applications by using the
94
PlplotCanvas widget. Information on the GTK toolkit is provided
95
at http://www.gtk.org/. PlplotCanvas is a subclass of the GnomeCanvas
96
(see http://developer.gnome.org/doc/API/2.0/libgnomecanvas/index.html),
97
and so includes all of its functionality. The specialized C API for
98
PlplotCanvas is described in
100
HREF="gui.html#plplotcanvas-api"
101
>the Section called <I
104
>, and bindings to other languages
105
are described in *** NEEDS DOCUMENTATION ***.
112
NAME="plplotcanvas-basics"
113
>PlplotCanvas Basics</A
116
> The method declarations and data structures are defined in
120
>. Programs using the PlplotCanvas
121
widget must be linked against the
124
>libplplotgnome2d</TT
129
>. This is most easily
130
accomplished using pkg-config; i.e.,
137
CLASS="programlisting"
138
> gcc plplotcanvas_demo.c -o plplotcanvas_demo `pkg-config --cflags --libs plplotd-gnome2`
145
You may need to remind pkg-config where to look for the
148
>plplotd-gnome2.pc</TT
149
> file installed by PLplot; e.g.,
156
CLASS="programlisting"
157
> gcc plplotcanvas_demo.c -o plplotcanvas_demo `PKG_CONFIG_PATH=/usr/local/lib/pkgconfig pkg-config --cflags --libs plplotd-gnome2`
165
> A specialized API is provided for PlplotCanvas and is described in
167
HREF="gui.html#plplotcanvas-api"
168
>the Section called <I
171
>. The API provides methods
172
to create and manipulate PlplotCanvas widgets, in addition to
173
object-oriented analogues for each of the PLplot functions.
176
> Example programs are provided that demonstrate the use of the
177
PlplotCanvas widget in <A
178
HREF="gui.html#plplotcanvas-examples"
179
>the Section called <I
180
>PlplotCanvas Examples</I
190
NAME="plplotcanvas-api"
194
> The PlplotCanvas methods are as follows. Because PlplotCanvas is a
195
GTK widget, GLib types (gint, gdouble, gboolean, etc) are sometimes
196
used rather than PLplot types (PLINT, PLFLT, etc). See
197
http://developer.gnome.org/doc/API/2.0/glib/index.html for more
198
information on GLib and GLib types.
205
NAME="plplot_canvas_new"
208
>plplot_canvas_new</CODE
209
>: Creates a new PlplotCanvas.</A
220
CLASS="funcprototype"
225
> PlplotCanvas* plplot_canvas_new
236
> Returns a pointer to a new PlplotCanvas widget. Methods that
237
apply to a PlplotCanvas are given next.
251
> There are no arguments for this method.
264
NAME="plplot_canvas_plfunc"
267
>plplot_canvas_plfunc</CODE
268
>: PLplot function analogues.</A
279
CLASS="funcprototype"
284
>void plplot_canvas_plfunc</CODE
294
> The PLplot functions have analogue methods named like
297
>plplot_canvas_plfunc</CODE
308
>plplot_canvas_plline</CODE
312
>plplot_canvas_plfunc</CODE
314
should be used rather than the standard PLplot API when the
315
PlplotCanvas is used.
318
> Lines drawn to the canvas are not shown until the page is
321
>plplot_canvas_pladv</CODE
323
plot will remain on the canvas until the next page advance.
338
> functions are not used with
339
PlplotCanvas because the <CODE
341
>plplot_canvas_new</CODE
343
function does the necessary initialization and returns an
344
object with a unique stream number.
362
>The canvas on which to operate.</P
371
> The list of arguments from the PLplot function analogue. The
372
same types used in the PLplot function are used here.
385
NAME="plplot_canvas_dispose"
388
>plplot_canvas_dispose</CODE
389
>: Disposes the canvas.</A
400
CLASS="funcprototype"
405
>void plplot_canvas_dispose</CODE
415
> Disposes the Canvas.
433
>The canvas to dispose.</P
445
NAME="plplot_canvas_set_size"
448
>plplot_canvas_set_size</CODE
449
>: Sets the canvas size.</A
460
CLASS="funcprototype"
465
> void plplot_canvas_set_size
467
>(canvas, width, height);</TD
476
> Sets the PlplotCanvas widget width and height.
494
>The PlplotCanvas to size.</P
506
>The width, in pixels.</P
518
>The height, in pixels.</P
530
NAME="plplot_canvas_use_text"
533
>plplot_canvas_use_text</CODE
534
>: Sets text handling.</A
545
CLASS="funcprototype"
550
>void plplot_canvas_use_text</CODE
551
>(canvas, use_text);</TD
560
> Sets whether TrueType text or Hershey fonts are used by the
579
>The PlplotCanvas to set.</P
592
> TRUE for TrueType fonts (default), FALSE for Hershey fonts.
605
NAME="plplot_canvas_use_pixmap"
608
>plplot_canvas_use_pixmap</CODE
609
>: Sets pixmap usage.</A
620
CLASS="funcprototype"
625
>void plplot_canvas_use_pixmap</CODE
626
>(canvas, use_pixmap);</TD
635
> Sets whether lines and shades are drawn to a pixmap,
636
or instead as vector graphics.
639
> Lines and shade drawn to the pixmap are not anti-aliased, and so may
640
appear pixelated. Vector graphics are fully anti-aliased, but are
641
rendered at a slower speed.
659
>The PlplotCanvas to set.</P
672
> TRUE to use pixmap (default), FALSE for vector graphics instead.
685
NAME="plplot_canvas_use_persistence"
688
>plplot_canvas_use_persistence</CODE
690
of subsequent drawing operations.</A
701
CLASS="funcprototype"
706
> void plplot_canvas_use_persistence
708
>(canvas, use_persistence);</TD
717
> Sets whether the subsequent drawing commands are persistent,
718
or refreshed when the PLplot page is advanced. This feature
719
is useful for plot animations, because the axes can be persistent
720
rather than redrawn for each frame.
723
> Note that lines that are persistent are always anti-aliased and
742
>The PlplotCanvas to set.</P
747
>use_persistence</CODE
755
> TRUE for persistence, FALSE for erasing at new page (default).
768
NAME="plplot_canvas_get_stream_number"
771
>plplot_canvas_get_stream_number</CODE
773
PLplot stream number.</A
784
CLASS="funcprototype"
789
> PLINT plplot_canvas_get_stream_number
800
> Returns the stream number for the given Canvas. Although the
801
concept of streams that exists in the standard PLplot API is not
802
used here, the stream number provides a unique ID number for
803
the given PlplotCanvas widget.
821
> The canvas to retrieve the stream number from.
835
NAME="plplotcanvas-examples"
836
>PlplotCanvas Examples</A
840
Two example programs are provided that demonstrate the use of the
841
PlplotCanvas widget. They are:
848
> plplotcanvas_demo: Demonstrates the basic usage of the
849
PlplotCanvas to embed a plot in a Gnome application.
854
> plplotcanvas_animation: Demonstrates advanced multi-threaded
855
dual-stream usage of the PlplotCanvas.
862
> The code from plplotcanvas_demo.c is given below, and is explained
870
CLASS="programlisting"
872
#include <plplotcanvas.h>
873
#include <gtk/gtk.h>
875
/* The width and height of the plplot canvas widget */
876
#define WIDTH 1000 /* 500 */
877
#define HEIGHT 600 /* 300 */
879
/* Delete event callback */
880
gint delete_event( GtkWidget *widget,GdkEvent *event,gpointer data ) {
884
/* Destroy event calback */
885
void destroy(GtkWidget *widget,gpointer data) {
890
int main(int argc,char *argv[] )
893
PlplotCanvas* canvas;
896
/* Parse the options */
897
plparseopts(&argc, argv, PL_PARSE_FULL);
899
/* The data to plot */
900
double x[11] = {0,1,2,3,4,5,6,7,8,9,10};
901
double y[11] = {0,0.1,0.4,0.9,1.6,2.6,3.6,4.9,6.4,8.1,10};
903
/* Initialize gtk and the glib type system */
904
gtk_init(&argc, &argv);
907
/* Create the canvas and set its size; during the creation process,
908
* the gcw driver is loaded into plplot, and plinit() is invoked.
910
canvas=plplot_canvas_new(TRUE);
911
plplot_canvas_set_size(canvas,WIDTH,HEIGHT);
913
/* Create a new window and stuff the canvas into it */
914
window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
915
gtk_container_set_border_width(GTK_CONTAINER(window),10);
916
gtk_container_add(GTK_CONTAINER(window),GTK_WIDGET(canvas));
918
/* Connect the signal handlers to the window decorations */
919
g_signal_connect(G_OBJECT(window),"delete_event",
920
G_CALLBACK(delete_event),NULL);
921
g_signal_connect(G_OBJECT(window),"destroy",G_CALLBACK(destroy),NULL);
923
/* Display everything */
924
gtk_widget_show_all(window);
926
/* Draw on the canvas with Plplot */
927
plplot_canvas_pladv(canvas,0); /* Advance to first page */
928
plplot_canvas_plcol0(canvas,15); /* Set color to black */
929
plplot_canvas_plwid(canvas,2); /* Set the pen width */
930
plplot_canvas_plvsta(canvas); /* Set the viewport */
931
plplot_canvas_plwind(canvas,0.,10.,0.,10.); /* Set the window */
932
plplot_canvas_plbox(canvas,"bcnst",0.,0,"bcnstv",0.,0); /* Set the box */
933
plplot_canvas_pllab(canvas,"x-axis","y-axis","A Simple Plot"); /* Draw some labels */
936
plplot_canvas_plcol0(canvas,1); /* Set the pen color */
937
plplot_canvas_plline(canvas,11,x,y);
939
/* Advancing the page finalizes this plot */
940
plplot_canvas_pladv(canvas,0);
942
/* Start the gtk main loop */
950
> So, what's going on here? After the preliminaries, the GTK and the
951
GLib type system are initialized by calls to
959
A PlplotCanvas is created using
962
>plplot_canvas_new</CODE
963
>, and it's size is set using
966
>plplot_canvas_set_size</CODE
970
> Next, a window is created (<CODE
972
>gtk_window_new</CODE
974
the border is set (<CODE
976
>gtk_set_border_width</CODE
978
and the canvas is stuffed into the window
981
>gtk_container_add</CODE
985
> Callback functions are installed using
988
>g_signal_connect</CODE
990
decorations respond. The window is set to display everything using
993
>gtk_widget_show_all</CODE
997
> Now come the PLplot analogue commands. First, the page using is
1000
>plplot_canvas_pladv</CODE
1002
color and width are set with <CODE
1004
>plplot_canvas_plcol0</CODE
1008
>plplot_canvas_plwid</CODE
1009
>,respectively. The PLplot
1010
viewport, window, box and labels are created using
1013
>plplot_canvas_plvpor</CODE
1017
>plplot_canvas_plwind</CODE
1021
>plplot_canvas_plbox</CODE
1025
>plplot_canvas_pllab</CODE
1026
>, respectively. A line is
1027
drawn on the canvas using <CODE
1029
>plplot_canvas_plline</CODE
1031
the page is advanced with <CODE
1033
>plplot_canvas_pladv</CODE
1037
> Finally, the GTK main loop is entered using
1041
>, where it resides until the program
90
1048
CLASS="NAVFOOTER"
added
removed
doc/docbook/src/gui.html
