original_mini-x.txt

Nano-x的设计架及相关文档----这是网上下载的中文翻译版本, E文的可以在其网站上下载.

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.


void
GrClose()
Close the connection to the graphics server, first flushing any graphics
calls that have been buffered.  Currently, this sets the screen back into
text mode.  This (currently) should be called before your program exits,
otherwise the screen will be left in graphics mode.  If this occurs, you
can run the 'tm' program to reset the terminal to text mode.


GR_ERROR_FUNC
GrSetErrorHandler(func)
	GR_ERROR_FUNC	func;		/* function to handle errors */
Set an error handling routine, which will be called on any errors from
the server (when events are asked for by the client).  If zero is given,
then a default routine will be used which will describe the error and exit.
Returns the previous error handler (0 if none).  When an error occurs,
the error handling function is called with the following parameters:
GR_ERROR, GR_FUNC_NAME, and GR_ID.  These are the error code, the name
of the function which failed, and a resource id (0 if not meaningful).
The error routine can return if desired, but without corrective action
new errors will probably occur soon.


void
GrGetScreenInfo(sip)
	GR_SCREEN_INFO	*sip;		/* location to return info into */
Return useful information about the screen.  This information returned
has been documented above.


void
GrGetFontInfo(font, fip)
	GR_FONT		font;		/* font number */
	GR_FONT_INFO	*fip;		/* address of font info */
Return useful information about the specified font number.  This information
is the font number, the height of the font, the maximum width of any
character in the font, the height of the baseline, a flag indicating whether
or not the font is fixed-width, and a table of the individual widths of each
character in the font.  If the font is unknown, the returned font number is
set to zero and the remainder of the information is undefined.  Refer to
graphics.h for a definition of the fields of GR_FONT_INFO.


void
GrGetGCInfo(gc, gcip)
	GR_GC_ID	gc;		/* graphics context */
	GR_GC_INFO	*gcip;		/* address of graphics context info */
Return useful information about the specified graphics context.  This
information is the graphics context id, the current font, the foreground
and background colors, and so on.  If the graphics context is unknown,
the returned id is 0, and the other information is undefined.  Refer to
graphics.h for a definition of the fields of GR_GC_INFO.


void
GrGetGCTextSize(gc, cp, len, retwidth, retheight, retbase)
	GR_GC_ID	gc;		/* graphics context containing font */
	GR_CHAR		*cp;		/* address of text string */
	GR_SIZE		len;		/* length of text string */
	GR_SIZE		*retwidth;	/* returned width of string */
	GR_SIZE		*retheight;	/* returned height of string */
	GR_SIZE		*retbase;	/* returned height of baseline */
Return the size of a text string for the font in a graphics context.
This is the width of the string, the height of the string, and the height
above the bottom of the font of the baseline for the font.  The returned
sizes are in pixels.


void
GrGetNextEvent(ep)
	GR_EVENT	*ep;		/* address where event is returned */
Return the next event from the event queue, waiting for it if necessary.
If a graphics error had occurred, the error handler will be called at this
point.  This routine first flushes any buffered graphics commands.  The
GR_EVENT is a union of all the possible events.  The type field of the union
indicates which of the possible events took place, and then the correct
element of the union can be used to access that particular event type's data.


void
GrCheckNextEvent(ep)
	GR_EVENT	*ep;		/* address where event is returned */
Return the next event from the event queue if one is ready.
If one is not ready, then the event type GR_EVENT_TYPE_NONE is returned.
Therefore, this routine never blocks.  This routine first flushes any
buffered graphics commands.


void
GrPeekEvent(ep)
	GR_EVENT	*ep;		/* address where event is returned */
Return the next event from the event queue if one is ready, without removing
it from the queue.  If one is not ready, then the type GR_EVENT_TYPE_NONE
is returned.  This routine never blocks.  This routine first flushes any
buffered graphics commands.


void
GrSelectEvents(wid, eventmask)
	GR_WINDOW_ID	wid;		/* window id */
	GR_EVENT_MASK	eventmask;	/* mask of events wanted */
Select events for a window for this client.  The events are a bitmask
specifying the events desired for this window.  This totally replaces
any previously selected event mask for the window.


GR_WINDOW_ID
GrNewWindow(parent, x, y, width, height, bordersize, background, bordercolor)
	GR_WINDOW_ID	parent;		/* parent id */
	GR_COORD	x;		/* x position relative to parent */
	GR_COORD	y;		/* y position relative to parent */
	GR_SIZE		width;		/* width */
	GR_SIZE		height;		/* height */
	GR_SIZE		bordersize;	/* size of border */
	GR_COLOR	background;	/* background color */
	GR_COLOR	bordercolor;	/* border color */
Allocate a new input-output window which is a child of the specified window.
A new top-level window is made by specifying a parent of GR_ROOT_WINDOW_ID.
The x and y position is the upper left corner of the window, relative to
the parent's upper left corner.  These corners are only for the drawable
area of the windows, so that the border does not affect the position.  An
input-output window cannot be made as a child of an input-only window.  The
new window starts off unmapped, and must be mapped before it can be seen.
The new window inherits the cursor of the parent window, and initially is
set to select no events.  This routine returns the window id of the window
which can be used in other calls.


GR_WINDOW_ID
GrNewInputWindow(parent, x, y, width, height)
	GR_WINDOW_ID	parent;		/* parent id */
	GR_COORD	x;		/* x position relative to parent */
	GR_COORD	y;		/* y position relative to parent */
	GR_SIZE		width;		/* width */
	GR_SIZE		height;		/* height */
Allocate a new input-only window which is a child of the specified window.
An input-only window is invisible, and cannot be drawn into.  It's only
purposes are that it can select events, and can have it's own cursor.  The
new window starts off unmapped, and must be mapped before it is effective.
The new window inherits the cursor of the parent window, and initially is
set to select no events.  This routine returns the window id of the window
which can be used in other calls.


void
GrDestroyWindow(wid)
	GR_WINDOW_ID	wid;		/* window to destroy */
This unmaps and then destroys the specified window, and all of its children.
The root window cannot be destroyed.  After destroying a window, you must be
careful about handling events which refer to the dead window, but which have
not been read yet.


void
GrGetWindowInfo(wid, wip)
	GR_WINDOW_ID	wid;		/* window id to find out about */
	GR_WINDOW_INFO	*wip;		/* location to return info into */
Return useful information about the specified window.  Refer to the
graphics.h include file for the definition of GR_WINDOW_INFO to see
what data is returned.  If the window id is not valid, an error is NOT
generated.  Instead, the wid value in the returned structure is set to
zero, and the other fields are not defined.


GR_GC_ID
GrNewGC()
Allocate a new graphics context with default parameters.  These defaults are:
background of black, foreground of white, font as font 0, and drawing mode
as setting.  This routine returns the id for the graphics context which can
be used in other calls.


GR_GC_ID
GrCopyGC(gc)
	GR_GC_ID	gc;		/* graphics context to copy */
Allocate a new graphics context which is a copy of another one.  The new
graphics context has the same parameter values as the old one, but is then
independent.  This routine returns the id for the graphics context which
can be used in other calls.


void