The General Drawing Kit

Version 1.0 May 1996

by Peter Mattis

Copyright \begin{matrix}c \\ ◯ \end{matrix} 1996 Peter Mattis 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.

The General Drawing Kit 1

The General Drawing Kit

2 GDK

1 Copying

GDK is free; this means that everyone is free to use it and free to redestribute it on a free basis. GDK is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of GDK that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of GDK, that you receive source code or else can get it if you want it, that you can change GDK or use pieces of it in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of GDK, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

Also, for my own protection, we must make certain that everyone finds out that there is no warranty for GDK. If GDK is modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will no reflect on our reputation.

The precise conditions of the licenses for GDK are found in the General Public Licenses that accompanies it.

4 GDK

2 What is GDK?

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.

6 GDK

3 Initialization and exit

Initializing GDK is easy. Simply call gdk_init passing in the argc and argv parameters. Exit is similarly easy. Just call gdk_exit.

Function void gdk init (int *argc, char ***argv)

Initializes the GDK library. The arguments argc and argv are scanned and any arguments that GDK recognizes are handled and removed. The argc and argv parameters are the values passed to main upon program invocation.

Function void gdk exit (int errorcode)

Exit GDK and perform any necessary cleanup. gdk_exit will call the systems exit function passing errorcode as the parameter.

int
main (int argc, char *argv[])
{
  /* Initialize GDK. */
  gdk_init (&argc, &argv);
  /* Exit from GDK...this call will never return. */
  gdk_exit (0);
  /* Keep compiler from issuing a warning */
  return 0;
}

8 GDK

4 Event handling

Events are the means by which GDK lets the programmer know of user interaction. An event is normally a button or key press or some other indirect user action, such as a the mouse cursor entering or leaving a window.

There exist only a few functions for getting events and event information. These are

gdk_events_pending, gdk_event_get, gdk_events_record and gdk_events_playback.

The latter two functions are useful for automatic testing of a software package and should normally not be needed in a program.

Function gint gdk events pending (void)

Returns the number of events pending on the event queue.

Function gint gdk event get (GdkEvent *event)

Return the next available event in the event structure. gdk_event_get will return TRUE on success and FALSE on failure. Success and failure is determined by whether an event arrived before the timeout period expired.

Function void gdk events record (char *filename)

Turn on recording of events. User events and certain system events will be saved in the file named by the variable filename. This stream of events can later be played back and “should” produce the same results as when the original events were handled. However, the programmer does need to be careful in that the state of the program must be the

same when gdk_events_record is called and when gdk_events_playback is called.

For this reason, gdk_events_record is normally not called directly, but is instead invoked indirectly by specifying the “-record” command line option.

Function void gdk events playback (char *filename)

Start playback of events from a file. (See the above description of gdk_events_ record). Normally this function is not called directly but is invoked by the “- playback” command line option.

Function void gdk events stop (void)

Stop recording and playback of events.

void
handle_event ()
{
  GdkEvent event;
  if (gdk_event_get (&event))
    {
      switch (event.type)
       {
         ...
       }
    }
}

10 GDK Chapter 5: Understanding and using visuals 11

5 Understanding and using visuals

12 GDK Chapter 6: Creating and using windows 13

6 Creating and using windows

14 GDK Chapter 7: Creating and modifying GCs 15

7 Creating and modifying GCs

16 GDK Chapter 8: Creating pixmaps 17

8 Creating pixmaps

18 GDK Chapter 9: Creating images 19

9 Creating images

20 GDK Chapter 10: Specifying color 21

10 Specifying color

22 GDK Chapter 11: Creating Fonts 23

11 Creating Fonts

24 GDK Chapter 12: Drawing Commands 25

12 Drawing Commands

26 GDK Chapter 13: Using extended devices 27

13 Using extended devices

28 GDK Chapter 14: Other stuff 29

14 Other stuff

30 GDK Chapter 15: Using GDK 31

15 Using GDK

32 GDK Variable Index 33

Variable Index

G

gdk_event_get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 gdk_events_pending . . . . . . . . . . . . . . . . . . . . . . . . . . 9 gdk_events_playback . . . . . . . . . . . . . . . . . . . . . . . . . 9 gdk_events_record . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 gdk_events_stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 gdk_exit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 gdk_init. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

34 GDK Concept Index 35

Concept Index

C

Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Controlling extended devices. . . . . . . . . . . . . . . . . . 27

D

Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

E

Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

F

Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

G

GC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Graphics Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

I

Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

M

Miscellaneous. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

O

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 27

P

Pixmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

T

Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

U

Using extended device capabilities . . . . . . . . . . . . 27

V

Visuals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

W

Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

36 GDK

Short Contents

The General Drawing Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 Copying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2 What is GDK?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3 Initialization and exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4 Event handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5 Understanding and using visuals . . . . . . . . . . . . . . . . . . . . 11 6 Creating and using windows . . . . . . . . . . . . . . . . . . . . . . . 13 7 Creating and modifying GCs . . . . . . . . . . . . . . . . . . . . . . 15 8 Creating pixmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 9 Creating images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 10 Specifying color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 11 Creating Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 12 Drawing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 13 Using extended devices . . . . . . . . . . . . . . . . . . . . . . . . . . 27 14 Other stuff. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 15 Using GDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Variable Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Table of Contents

The General Drawing Kit . . . . . . . . . . . . . . . . . . . . . 1 1 Copying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2 What is GDK? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3 Initialization and exit . . . . . . . . . . . . . . . . . . . . . . 7 4 Event handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5 Understanding and using visuals . . . . . . . . . . . 11 6 Creating and using windows . . . . . . . . . . . . . . . 13 7 Creating and modifying GCs . . . . . . . . . . . . . . 15 8 Creating pixmaps . . . . . . . . . . . . . . . . . . . . . . . . . 17 9 Creating images . . . . . . . . . . . . . . . . . . . . . . . . . . 19 10 Specifying color . . . . . . . . . . . . . . . . . . . . . . . . . 21 11 Creating Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . 23 12 Drawing Commands . . . . . . . . . . . . . . . . . . . . . 25 13 Using extended devices . . . . . . . . . . . . . . . . . . 27 14 Other stuff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 15 Using GDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Variable Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35