original_mini-x.txt

开放源码实时操作系统源码.

GR_EVENT_TYPE_BUTTON_UP		(GR_EVENT_BUTTON)
	This is generated when a button is released on the mouse.  This
	returns data similarly to button down.

GR_EVENT_TYPE_MOUSE_ENTER	(GR_EVENT_GENERAL)
	This is generated when the mouse enters a window.  This returns the
	window id which generated the event.

GR_EVENT_TYPE_MOUSE_EXIT	(GR_EVENT_GENERAL)
	This is generated when the mouse leaves a window.  This returns
	the window id which generated the event.

GR_EVENT_TYPE_MOUSE_MOTION	(GR_EVENT_MOUSE)
	Mouse motion is generated for every motion of the mouse, and is
	used to	track the entire history of the mouse.  Mouse motion
	generates many events and causes lots of overhead.  This returns
	data similarly to mouse enter.

GR_EVENT_TYPE_MOUSE_POSITION	(GR_EVENT_MOUSE)
	Mouse position ignores the history of the motion, and only reports the
	latest position of the mouse by only queuing the latest such event for
	any single client (good for rubber-banding).  This returns data
	similarly to mouse enter.

GR_EVENT_TYPE_KEY_DOWN		(GR_EVENT_KEYSTROKE)
	This indicates that a key has been pressed on the keyboard.
	This returns the window id which generated the event, the window id
	which actually contains the pointer (if the pointer is outside of
	the event window, this will be the event window), the current position
	of the mouse, the current buttons on the mouse which are down, the
	current modifier flags, and the character which was typed.

GR_EVENT_TYPE_KEY_UP		(GR_EVENT_KEYSTROKE)
	This indicates that a key has been released on the keyboard.  This
	event is not necessarily available, and should not be depended on.
	This returns data similarly to key down.

GR_EVENT_TYPE_FOCUS_IN		(GR_EVENT_GENERAL)
	This indicates that the input focus has just changed to this window.
	This returns the window id which got focus.

GR_EVENT_TYPE_FOCUS_OUT		(GR_EVENT_GENERAL)
	This indicates that the input focus has just left this window.
	This returns the window id which lost focus.


To select for events, you use GrSelectEvents, and specify the window which
wants to receive the events, and also specify a mask indicating the events
you wish to receive.  The mask is the logical OR of individual bit values
representing the event types.  The mask names are the same as the event
names, except that the "_TYPE_" string is replaced by "_MASK_".  For
example, the mask associated with the event GR_EVENT_TYPE_FOCUS_IN is
GR_EVENT_MASK_FOCUS_IN.

If you select for both button down and button up events, then the mouse
will be implicitly "grabbed" when any button is pressed down in that window.
This means that the mouse position and button down and up events will be
delivered only to that window, and the cursor shape won't change, even if
the mouse leaves that window.  The implicit grabbing ends after the last
button is released.  While this grabbing occurs, the input focus is also
not changed as the mouse is moved.


MODIFIER AND MOUSE BUTTONS

Modifiers are the status of special keyboard shift-like keys.  The state
of these keys can be read as up or down, and don't generate any characters
by themselves.  These keys are for things like SHIFT, CTRL, and ALT.
They are returned as bit values OR'd together in various events.  Not all
of these modifiers may be implemented.  The GrGetScreenInfo function returns
the modifiers that are implemented.  The following modifiers are defined:

	GR_MODIFIER_SHIFT	shift key is down
	GR_MODIFIER_CTRL	ctrl key is down
	GR_MODIFIER_META	meta (or ALT) key is down
	GR_MODIFIER_ANY		any of the modifiers is down


The mouse button state are returned as bit values OR'd together in various
events.  Not all of these buttons may be implemented.  The GrGetScreenInfo
function returns the buttons that are implemented.  The following mouse
buttons are defined:

	GR_BUTTON_1		button 1 is down (left)
	GR_BUTTON_2		button 2 is down (middle)
	GR_BUTTON_3		button 3 is down (right)
	GR_BUTTON_ANY		any of the buttons is down


BITMAPS

Bitmaps are defined as an array of GR_BITMAP values, which are unsigned shorts.
Each word is 16 bits, which specify foreground and background values, with 1
being foreground and 0 being background.  Higher order bits in the word
represent pixels to the left of the lower order bits.  Bitmaps have a width
and a height, measured in pixels.  The width does not need to be a multiple
of 16.  In this case, remaining bits in the last word of a row are unused,
so that each row starts with a new bitmap word.  The GR_BITMAP_SIZE macro can
be used to allocate the proper number of bitmap words for a bitmap, as in:

	GR_BITMAP_SIZE(width, height).

The symbol GR_MAX_BITMAP_SIZE is the number of bitmap words required for
the maximum sized cursor.


ERROR CODES

Calls to the graphics libraries may produce errors.  Most errors that
occur are due to specifying a window or graphics context which does not
exist, or attempting an operation which is illegal.  Many things are allowed
even if pointless, such as drawing outside of the window boundaries, or
while a window is not mapped.  The things which return errors are those
which definitely indicate a program bug, attempts to exceed the system
limits, or a fatal device error.

In order to be as efficient as possible, error codes are not returned by
individual function calls.  Instead, if a function fails, an error event
is generated which will eventually be noticed by the program at a possibly
much later time.  This allows many drawing requests to be sent at one time
without having to worry about the status of each one.

Error events are detected when the program checks for events, such as
by calling GrGetNextEvent.  At this point, if an error had occurred, a
special error handler routine is called to notice the error.  If the program
had not set up its own error handler, a default one is called which will
disconnect from the server, print out an indication of the error, and exit
the program.

The following is a list of the possible errors:

GR_ERROR_BAD_WINDOW_ID		the specified window id is unknown
GR_ERROR_BAD_GC_ID		the specified graphics context id is unknown
GR_ERROR_BAD_CURSOR_SIZE	the specified cursor is too large
GR_ERROR_MALLOC_FAILED		no more memory is available in the server
GR_ERROR_BAD_WINDOW_SIZE	the specified window size is illegal
GR_ERROR_KEYBOARD_ERROR		an error occurred reading from the keyboard
GR_ERROR_MOUSE_ERROR		an error occurred reading from the mouse
GR_ERROR_INPUT_ONLY_WINDOW	drawing was attempted in an input-only window
GR_ERROR_ILLEGAL_ON_ROOT_WINDOW	an illegal operation was attempted on the root
GR_ERROR_TOO_MUCH_CLIPPING	complexity of windows exceeded clipping limits
GR_ERROR_SCREEN_ERROR		an error occurred talking to the screen driver
GR_ERROR_UNMAPPED_FOCUS_WINDOW	attempted to set focus to an unmapped window
GR_ERROR_BAD_DRAWING_MODE	illegal drawing mode specified for a GC


SCREEN PROPERTIES

You do not have to hard code the size of the screen or the number of colors
available in your program.  Instead, you can find this information out
dynamically after the connection is made to the graphics server, by using
the GrGetScreenInfo call.  This returns the above information, and in addition
returns the color values for black and white, the aspect ratio of pixels,
the number of built-in fonts available, and the modifiers and buttons which
are available.  The aspect ratio is useful for drawing objects which need
to be scaled correctly, such as circles.  The aspect ratio is the quotient
of xdpcm and ydpcm, which are integer values.


typedef struct {
	GR_SIZE		rows;		/* number of rows on screen */
	GR_SIZE		cols;		/* number of columns on screen */
	GR_SIZE		xdpcm;		/* dots/centimeter in x direction */
	GR_SIZE		ydpcm;		/* dots/centimeter in y direction */
	GR_COLOR	maxcolor;	/* maximum legal color value */
	GR_COLOR	black;		/* the color black */
	GR_COLOR	white;		/* the color white */
	GR_COUNT	fonts;		/* number of built-in fonts */
	GR_BUTTON	buttons;	/* buttons which are implemented */
	GR_MODIFIER	modifiers;	/* modifiers which are implemented */
} GR_SCREEN_INFO;


INCLUDE FILE AND GRAPHICS LIBRARY

To use the graphics server, your program must include "graphics.h".
This should be put into /usr/include, so that your program simply has
the following line at the top:
	#include <graphics.h>

Including this file gives you all of the definitions you need to use the
graphics library.  These are the typedefs, function declarations, event
structures, and various constants.

When loading your program, you need to load the graphics server into the
program by using the -lgraph option in the cc command.  For example, if
your program is called myprog, then you could build it using the following:
	cc -o myprog myprog.c -lgraph


TYPEDEFS

The following is a list of the typedefs in the include file, and a short
description of their purpose.  Refer to their definitions in graphics.h
to find out what their actual C base type is.  Most are shorts, unsigned
shorts, or longs.

GR_COORD	coordinate value (x, y locations, signed)
GR_SIZE		size value (widths, heights, signed)
GR_COUNT	number of items (signed)
GR_COLOR	full color value (32 bit value for full generality)
GR_COLOR8	eight bit color value (8 bit value for efficient storage)
GR_BITMAP	bitmap unit (single words of 16 bits for bitmaps)
GR_MODE		drawing mode (setting, xoring, anding, oring)
GR_CHAR		text character (normal chars)
GR_ID		resource ids (window, graphics context, pixmap)
GR_DRAW_ID	drawable id (window, pixmap)
GR_WINDOW_ID	window id (identifies individual window)
GR_PIXMAP_ID	pixmap id (identifies individual pixmaps, not yet used)
GR_GC_ID	graphics context id (identifies indiviual graphics contexts)
GR_FONT		font number (identifies individual fonts, first few built-in)
GR_BOOL		boolean value (GR_TRUE or GR_FALSE)
GR_FUNC		function codes (not for clients to use)
GR_ERROR	error value (reasons for graphics calls to fail)
GR_EVENT_TYPE	event types (identifies the type of event)
GR_BUTTON	button flags (which mouse buttons are depressed)
GR_MODIFIER	modifier flags (CTRL, SHIFT, etc)
GR_EVENT_MASK	event masks (mask values corresponding to event types)
GR_FUNC_NAME	function name (for error reporting)
GR_ERROR_FUNC	error function (for defining error handlers)


The following typedefs may be useful to your program.  None of the library
functions (currently) accept any of these structures as arguments, except
for the GrPoly and GrFillPoly routines, which use GR_POINT.


typedef struct {
	GR_COORD	x;		/* x coordinate */
	GR_COORD	y;		/* y coordinate */
} GR_POINT;

typedef struct {
	GR_COORD	x1;		/* x coordinate of first point */
	GR_COORD	y1;		/* y coordinate of first point */
	GR_COORD	x2;		/* x coordinate of second point */
	GR_COORD	y2;		/* y coordinate of second point */
} GR_LINE;

typedef struct {
	GR_COORD	x;		/* x coordinate of center */
	GR_COORD	y;		/* y coordinate of center */
	GR_SIZE		rx;		/* radius in x direction */
	GR_SIZE		ry;		/* radius in y direction */
} GR_ELLIPSE;

typedef struct {
	GR_COORD	x;		/* x coordinate of top left corner */
	GR_COORD	y;		/* y coordinate of top left corner */
	GR_SIZE		width;		/* width of rectangle */
	GR_SIZE		height;		/* height of rectangle */
} GR_RECT;


LIMITS

The coordinate system is limited to integers in the range GR_COORD_MIN
to GR_COORD_MAX.  This is -32768 to 32767, and fits in a short.

The maximum size of a cursor definition is GR_MAX_CURSOR_SIZE, which is
16 pixels by 16 pixels.

The complexity of overlapping windows is limited to GR_MAX_CLIPRECTS regions,
which is 200.  Each window which overlaps another requires another 1 to 4
regions depending on its position and size.


GRAPHICS CALLS


int
GrOpen()
Open a connection to the graphics server.  This must be the first graphics
function used by your program.  Currently, this sets the screen into
graphics mode.  Returns zero if successful, -1 on failure.