327 lines
10 KiB
Plaintext
327 lines
10 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename gdk.info
|
|
@settitle GDK
|
|
@setchapternewpage odd
|
|
@c %**end of header
|
|
|
|
@set edition 1.0
|
|
@set update-date 16 May 1996
|
|
@set update-month May 1996
|
|
|
|
@ifinfo
|
|
This file documents GDK, the General Drawing Kit
|
|
|
|
Copyright (C) 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
|
|
|
|
@ignore
|
|
Permission is granted to process this file throught TeX and print the
|
|
results, provided the printed document carries copying permission notice
|
|
identical to this one except for the removal of this paragraph (this
|
|
paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
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.
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@title The General Drawing Kit
|
|
@subtitle Version 1.0
|
|
@subtitle @value{update-month}
|
|
@author by Peter Mattis
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 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.
|
|
@end titlepage
|
|
|
|
@dircategory User Interface Toolkit
|
|
@direntry
|
|
* GDK: (gdk). The General Drawing Kit
|
|
@end direntry
|
|
|
|
@node Top, Copying, (dir), (dir)
|
|
@top The General Drawing Kit
|
|
@ifinfo
|
|
This is edition @value{edition} of the GDK documentation,
|
|
@w{@value{update-date}}.
|
|
@end ifinfo
|
|
|
|
@menu
|
|
* Copying:: Your rights.
|
|
* Overview:: What is GDK?
|
|
* Initialization:: Initialization and exit.
|
|
* Events:: Event handling.
|
|
* Visuals:: Understanding and using visuals.
|
|
* Windows:: Creating and using windows.
|
|
* Graphics Contexts:: Creating and modifying GCs.
|
|
* Pixmaps:: Creating pixmaps.
|
|
* Images:: Creating images.
|
|
* Color:: Specifying color.
|
|
* Fonts:: Creating fonts.
|
|
* Drawing:: Drawing commands.
|
|
* XInput Support:: Using extended devices.
|
|
* Miscellany:: Other stuff.
|
|
* Examples:: Using GDK.
|
|
* Function Index:: Index of functions
|
|
* Concept Index:: Index of concepts
|
|
@end menu
|
|
|
|
@node Copying, Overview, Top, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Copying
|
|
|
|
GDK is @dfn{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.
|
|
|
|
|
|
@node Overview, Initialization, Copying, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter What is GDK?
|
|
@cindex Overview
|
|
|
|
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.
|
|
|
|
@node Initialization, Events, Overview, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Initialization and exit
|
|
@cindex Initialization
|
|
@cindex Exit
|
|
|
|
Initializing GDK is easy. Simply call @code{gdk_init} passing in the
|
|
@var{argc} and @var{argv} parameters. Exit is similarly easy. Just
|
|
call @code{gdk_exit}.
|
|
|
|
@deftypefun void gdk_init (int *@var{argc}, char ***@var{argv})
|
|
Initializes the GDK library. The arguments @var{argc} and @var{argv}
|
|
are scanned and any arguments that GDK recognizes are handled and
|
|
removed. The @var{argc} and @var{argv} parameters are the values
|
|
passed to @code{main} upon program invocation.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gdk_exit (int @var{errorcode})
|
|
Exit GDK and perform any necessary cleanup. @code{gdk_exit} will call
|
|
the systems @code{exit} function passing @var{errorcode} as the
|
|
parameter.
|
|
@end deftypefun
|
|
|
|
@example
|
|
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;
|
|
@}
|
|
@end example
|
|
|
|
|
|
@node Events, Visuals, Initialization, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Event handling
|
|
@cindex Events
|
|
|
|
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 @code{gdk_events_pending},
|
|
@code{gdk_event_get}, @code{gdk_events_record} and
|
|
@code{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.
|
|
|
|
@deftypefun gint gdk_events_pending (void)
|
|
Returns the number of events pending on the event queue.
|
|
@end deftypefun
|
|
|
|
@deftypefun gint gdk_event_get (GdkEvent *@var{event})
|
|
Return the next available event in the @var{event}
|
|
structure. @code{gdk_event_get} will return @code{TRUE} on success and
|
|
@code{FALSE} on failure. Success and failure is determined by whether
|
|
an event arrived before the timeout period expired.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gdk_events_record (char *@var{filename})
|
|
Turn on recording of events. User events and certain system events will
|
|
be saved in the file named by the variable @var{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 @code{gdk_events_record} is called and when
|
|
@code{gdk_events_playback} is called. For this reason,
|
|
@code{gdk_events_record} is normally not called directly, but is instead
|
|
invoked indirectly by specifying the ``-record'' command line option.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gdk_events_playback (char *@var{filename})
|
|
Start playback of events from a file. (See the above description of
|
|
@code{gdk_events_record}). Normally this function is not called directly
|
|
but is invoked by the ``-playback'' command line option.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gdk_events_stop (void)
|
|
Stop recording and playback of events.
|
|
@end deftypefun
|
|
|
|
@example
|
|
void
|
|
handle_event ()
|
|
@{
|
|
GdkEvent event;
|
|
|
|
if (gdk_event_get (&event))
|
|
@{
|
|
switch (event.type)
|
|
@{
|
|
@dots{}
|
|
@}
|
|
@}
|
|
@}
|
|
@end example
|
|
|
|
|
|
@node Visuals, Windows, Events, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Understanding and using visuals
|
|
@cindex Visuals
|
|
|
|
@node Windows, Graphics Contexts, Visuals, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Creating and using windows
|
|
@cindex Windows
|
|
|
|
@node Graphics Contexts, Pixmaps, Windows, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Creating and modifying GCs
|
|
@cindex Graphics Contexts
|
|
@cindex GC
|
|
|
|
@node Pixmaps, Images, Graphics Contexts, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Creating pixmaps
|
|
@cindex Pixmaps
|
|
|
|
@node Images, Color, Pixmaps, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Creating images
|
|
@cindex Images
|
|
|
|
@node Color, Fonts, Images, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Specifying color
|
|
@cindex Color
|
|
|
|
@node Fonts, Drawing, Color, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Creating Fonts
|
|
@cindex Fonts
|
|
|
|
@node Drawing, XInput Support, Fonts, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Drawing Commands
|
|
@cindex Drawing
|
|
|
|
@node XInput Support, Miscellany, Drawing, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Using extended devices
|
|
@cindex Overview
|
|
@cindex Using extended device capabilities
|
|
@cindex Controlling extended devices
|
|
|
|
@node Miscellany, Examples, XInput Support, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Other stuff
|
|
@cindex Timers
|
|
@cindex Debugging
|
|
@cindex Miscellaneous
|
|
|
|
|
|
@node Examples, Function Index, Miscellany, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Using GDK
|
|
@cindex Examples
|
|
|
|
|
|
@node Function Index, Concept Index, Examples, Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Variable Index
|
|
|
|
@printindex fn
|
|
|
|
@node Concept Index, , Function Index, Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Concept Index
|
|
|
|
@printindex cp
|
|
|
|
@summarycontents
|
|
@contents
|
|
@bye
|