new format for GDK documentation. Eventually plan to remove gdk.texi, but

Tue Jul 28 00:15:28 CDT 1998 Shawn T. Amundson <amundson@gtk.org>

        * docs/gdk.sgml: new format for GDK documentation.  Eventually
	  plan to remove gdk.texi, but not quite yet.  Just getting
	  started.

8 files changed, 240 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 17ae293a0..c7f34a22d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Tue Jul 28 00:15:28 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* docs/gdk.sgml: new format for GDK documentation.  Eventually
+	  plan to remove gdk.texi, but not quite yet.  Just getting 
+	  started.
+
 Mon Jul 27 09:18:13 BST 1998  Tony Gale  <gale@gtk.org>
 
 	* docs/gtk_tut.sgml: GtkTree section from
diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0
index 17ae293a0..c7f34a22d 100644
--- a/ChangeLog.pre-2-0
+++ b/ChangeLog.pre-2-0
@@ -1,3 +1,9 @@
+Tue Jul 28 00:15:28 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* docs/gdk.sgml: new format for GDK documentation.  Eventually
+	  plan to remove gdk.texi, but not quite yet.  Just getting 
+	  started.
+
 Mon Jul 27 09:18:13 BST 1998  Tony Gale  <gale@gtk.org>
 
 	* docs/gtk_tut.sgml: GtkTree section from
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 17ae293a0..c7f34a22d 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,9 @@
+Tue Jul 28 00:15:28 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* docs/gdk.sgml: new format for GDK documentation.  Eventually
+	  plan to remove gdk.texi, but not quite yet.  Just getting 
+	  started.
+
 Mon Jul 27 09:18:13 BST 1998  Tony Gale  <gale@gtk.org>
 
 	* docs/gtk_tut.sgml: GtkTree section from
diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2
index 17ae293a0..c7f34a22d 100644
--- a/ChangeLog.pre-2-2
+++ b/ChangeLog.pre-2-2
@@ -1,3 +1,9 @@
+Tue Jul 28 00:15:28 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* docs/gdk.sgml: new format for GDK documentation.  Eventually
+	  plan to remove gdk.texi, but not quite yet.  Just getting 
+	  started.
+
 Mon Jul 27 09:18:13 BST 1998  Tony Gale  <gale@gtk.org>
 
 	* docs/gtk_tut.sgml: GtkTree section from
diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index 17ae293a0..c7f34a22d 100644
--- a/ChangeLog.pre-2-4
+++ b/ChangeLog.pre-2-4
@@ -1,3 +1,9 @@
+Tue Jul 28 00:15:28 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* docs/gdk.sgml: new format for GDK documentation.  Eventually
+	  plan to remove gdk.texi, but not quite yet.  Just getting 
+	  started.
+
 Mon Jul 27 09:18:13 BST 1998  Tony Gale  <gale@gtk.org>
 
 	* docs/gtk_tut.sgml: GtkTree section from
diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index 17ae293a0..c7f34a22d 100644
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,3 +1,9 @@
+Tue Jul 28 00:15:28 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* docs/gdk.sgml: new format for GDK documentation.  Eventually
+	  plan to remove gdk.texi, but not quite yet.  Just getting 
+	  started.
+
 Mon Jul 27 09:18:13 BST 1998  Tony Gale  <gale@gtk.org>
 
 	* docs/gtk_tut.sgml: GtkTree section from
diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index 17ae293a0..c7f34a22d 100644
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,3 +1,9 @@
+Tue Jul 28 00:15:28 CDT 1998 Shawn T. Amundson <amundson@gtk.org>
+
+	* docs/gdk.sgml: new format for GDK documentation.  Eventually
+	  plan to remove gdk.texi, but not quite yet.  Just getting 
+	  started.
+
 Mon Jul 27 09:18:13 BST 1998  Tony Gale  <gale@gtk.org>
 
 	* docs/gtk_tut.sgml: GtkTree section from
diff --git a/docs/gdk.sgml b/docs/gdk.sgml
new file mode 100644
index 000000000..0b660bbee
--- /dev/null
+++ b/docs/gdk.sgml
@@ -0,0 +1,198 @@
+<!doctype linuxdoc system>
+
+<article>
+
+<!-- Title information -->
+
+<title>The GTK+ Drawing Kit Programming Manual
+<author>Shawn T. Amundson, Peter Mattis
+<date>July 26, 1998
+
+<abstract>
+This document aims at teaching user how to effectively program in
+GDK, the GTK+ Drawing Kit, and to serve as a reference guide to 
+more experienced GTK+ programmers.  It is a work in progress.
+
+<!-- Table of contents -->
+<toc>
+
+<!-- Begin the document -->
+
+<!-- ***************************************************************** -->
+<sect>Introduction
+
+<p>
+GDK is designed as a wrapper library that lies on top of Xlib. It
+performs many common and desired operations for a programmer instead
+of the programmer having to explicitly ask for such functionality from
+Xlib directly. For example, GDK provides a common interface to both
+regular and shared memory XImage types. By doing so, an application
+can nearly transparently use the fastest image type available. GDK
+also provides routines for determining the best available color depth
+and the best available visual which is not always the default visual
+for a screen.
+
+GDK is distributed and developed with GTK+, and is licensed under the 
+GNU Library General Public Licence (LGPL).
+
+<sect>Getting Started
+
+<sect1>Initialization
+<p>
+Initialization of GDK is easy.  Simply call gdk_init() passing 
+in the argc and argv parameters.
+
+<tscreen><verb>
+int main (int argc, char *argv[])
+{
+    /* Initialize GDK. */
+    gdk_init (&amp;argc, &amp;argv);
+
+    /* Cleanup of GDK is done automatically when the program exits. */
+    return 0;
+}
+</verb></tscreen>
+
+Generally, GDK initialization is done by gtk_init() in GTK+.  This means 
+that when using GTK+, you do not need to directly call gdk_init().
+
+<sect1>An Example using GDK with GTK+ 
+<p>
+This example demonstrates drawing a line using the foreground
+color of the GtkDrawArea widget it is drawn inside.  The example 
+will end when you click inside the window, which is filled by the
+GtkDrawingArea widget.
+
+The line is drawn during the expose event so that when the window 
+drawing is done whenever it is needed.
+
+<tscreen><verb>
+#include <gtk/gtk.h>
+
+/* The expose callback does the drawing of the line */
+int
+expose_callback (GtkWidget *widget, GdkEventExpose *event, gpointer data)
+{
+    GdkGC *gc;
+
+    printf("expose...\n");
+
+
+    /* The GC is the Graphics Context.  Here it is borrowed from the widget */
+    gc = widget->style->fg_gc[GTK_STATE_NORMAL];
+
+    gdk_draw_line (widget->window,  /* GDK Window of GtkDrawingArea widget */
+                   gc,              /* Graphics Context */
+                   0,               /* x1, left */
+                   0,               /* y1, top */
+                   200,             /* x2, right */
+                   200);            /* y2, bottom */
+}
+
+/* This quits GTK+ */
+void destroy (GtkWidget *widget, gpointer data)
+{
+    gtk_main_quit ();
+}
+
+int main (int argc, char *argv[])
+{
+    GtkWidget *window;
+    GtkWidget *darea;
+    int events;
+
+    /* This initializes both GTK+ and GDK */
+    gtk_init (&amp;argc, &amp;argv);
+
+    /* Create a window */
+    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
+    gtk_signal_connect (GTK_OBJECT (window), "destroy",
+                        GTK_SIGNAL_FUNC (destroy), NULL);
+
+    /* Create a drawing area widget. This widget actually is just a 
+       simple widget which provides us an GDK window to draw on and 
+       takes care of all the toolkit integration, like providing the
+       ability to add it to the window with gtk_contianer_add() */
+    darea = gtk_drawing_area_new ();
+    gtk_container_add (GTK_CONTAINER (window), darea);
+
+    /* Set the width and height (arguments are in that order) */
+    gtk_drawing_area_size (GTK_DRAWING_AREA (darea), 200, 200);
+
+    /* Drawing in the expose event is important to keep the 
+       draw line always on the GDK window */
+    gtk_signal_connect (GTK_OBJECT (darea), "expose_event",
+                        GTK_SIGNAL_FUNC (expose_callback), NULL);
+
+    /* We get the events, then add in button press.  If we did not
+       do this, we would not be notified of button press events in
+       the GtkDrawingArea widget */
+    events = gtk_widget_get_events (darea);
+    gtk_widget_set_events (darea, events | GDK_BUTTON_PRESS_MASK);
+
+    /* If we click on the darea, the application will exit */
+    gtk_signal_connect_object (GTK_OBJECT (darea), "button_press_event",
+                               GTK_SIGNAL_FUNC (gtk_widget_destroy),
+                               GTK_OBJECT (window));
+
+    gtk_widget_show (darea);
+    gtk_widget_show (window);
+
+    /* The GTK+ main idle loop */
+    gtk_main();
+
+    /* Cleanup of GDK is done automatically when the program exits. */
+    return 0;
+}
+</verb></tscreen>
+
+<sect>The Graphics Context 
+<p>
+The Graphics Context, or GC, defines how things should be drawn, 
+including color, font, fill, tile, stipple, clipping mask, line 
+width, line style, and join style.
+
+<sect1>Color
+<p>
+Changing color is done by changing the forground or background color 
+of the GC.
+
+<sect>Drawing Commands
+<sect>Event Handling
+<sect>Understanding and Using Visuals
+<sect>Creating and Using New Windows
+<sect>Pixmaps
+<sect>Images
+<sect>Fonts
+<sect>
+
+<sect>About this Document
+<sect1>History
+<P>
+This document was originially written by Peter Mattis and entitled
+"The General Drawing Kit".  It was meant as a reference guide.
+
+This version of the document has been renamed and is meant as a general
+programming guide.
+
+<sect1>Copying
+<p>
+Copyright (c) 1996 Peter Mattis
+<p>
+Copyright (c) 1998 Shawn T. Amundson
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by Peter Mattis.
+
+</article>