original_mini-x.txt

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

			MINI-X TUTORIAL
			David I. Bell
			19 May 91

This is a simple tutorial on using the mini-X graphics system.  Much of this
is a lot easier to understand if you are familiar to X.  I am not going to
try to explain every concept in detail here, nor how to put it all together
to make really fancy programs.  Instead, I am only going to tell you just
enough to let you make some simple graphics programs which work.  Experience
with simple test programs will enable you to build much fancier graphics
programs much easier than trying to decipher what I could tell you.

I am assuming that you basically know what a screen, pixels, colors,
keyboards, mice, buttons, and windows are.  However, you probably don't
know exactly what the properties of windows in this system are.  Also, you
might not know two other concepts which are important here, which are
graphics contexts and events.  So these things will be explained in this
tutorial.


WINDOWS

Windows are rectangular areas which can be drawn into.  Windows have a
position, specified by the x and y coordinates of their upper left corners,
and also a size, specified by their width and height.  Windows are arranged
in a tree structure, with the parent windows controlling the child windows.
The top of the tree is known as the root window.  The root window is always
present, and represents the total screen area.

Each child window is clipped by its parent window.  This means that a window
can be very large, but the only part of the window that can ever be seen is
the part which shows through its parent window.  This applies recursively,
so that all of the parents of a window limit its visibility.  The position
of a window is specified relative to its parent, and not absolutely.  This
means that for example, when a window is moved, then all of its children will
move with it.  The position of a window can be negative.

Windows which have the same parent can clip each other.  That is, there is a
defined order among the children of a window as to which is more important.
If two sibling windows overlap, then the more important window will be visible
in preference to the less important window.  The precedence of visibility
of siblings can be dynamically adjusted.  Clipping can also occur on a window
by earlier siblings of any of the window's parents.

Windows can be mapped or unmapped.  Unmapped windows are not visible, and
cause no events.  They can be thought of as "in storage" or offscreen.
When a window is mapped, then it can become visible on the screen.  Children
of an unmapped window are implicitly also unmapped.  So a window is not
visible until it and all of its parents are mapped.  A newly created window
starts off unmapped.

Windows have a background color.  A newly mapped window is filled with its
background color.  Clearing the window later, or having obscured portions
of the window become visible again, will fill the region with the background.
The client program can then draw into the window to make it look correct.

Windows may have a border.  A border is a set of rectangles adjacent to the
four sides of the window which is drawn in a specified color, with a
specified width.  This makes pretty lines around the window, for example.
The border cannot be drawn in by the program.  Borders are optional, so
that a window with a border width of zero has no border at all.  Borders
are "around" the window, so that they do not affect the coordinates of the
window.  Whether or not a window has borders, its position determines the
location of the upper left corner which can be drawn into.

Windows can have a cursor associated with them.  The graphics server tracks
the location of the mouse, and maintains the position of a graphics cursor
on the screen.  This cursor can automatically change its shape and colors as
it moves between different windows.  The use of different cursors for different
windows can be used to provide a powerful clue to the user as to what will
happen if a mouse button is pressed in a window.  Newly created windows
inherit the same cursor as their parent.

There are two types of windows, input-output and input-only windows.
Input-output windows are normal windows which are visible and can be drawn
into.  Input-only windows are invisible, have no border, and cannot be
drawn into.  Their purpose is to catch events, and to enable the cursor
to be changed in different regions of a visible window.  The only children
of input-only windows are also input-only windows.

Windows are identified by integers called window ids.  The root window has
a constant window id value of GR_ROOT_WINDOW_ID.  The root window does not
need creating, and cannot be unmapped, moved, resized, or destroyed.
However, it can be drawn into and events can be delivered to it.  New windows
can be created from existing windows.  Their window ids are not constants,
but once created the window id remains until the window is destroyed.  Window
ids are not reused as windows are created and destroyed.


GRAPHICS CONTEXTS

When drawing objects such as lines, there are many parameters that can be
specified for the function call that affect the operation.  Besides the
minimum information needed for the function such as the endpoint coordinates,
there are extra parameters that are less important and less variable.
Examples of these extra parameters are color, width (thin or thick), style
(dashed, dotted), and drawing operation (setting, XORing).  Instead of
requiring the specifying of each of these extra parameters for every function
call, graphics contexts are used.  Graphics contexts are just a collection
of specific combinations of these extra parameters.  The many possible
extra parameters to each function are replaced by just one extra parameter,
which is the graphics context.

For example, instead of a function call like:
	drawline(window, x1, y1, x2, y2, color, width, style, operation);

you have instead
	drawline(window, gc, x1, y1, x2, y2),

where the graphics context contains within itself the parameters color, width,
style, and operation.

Graphics contexts are stored in the graphics server, and are identified by
unique numbers in a way similar to window ids.  Your program must allocate
graphic contexts, which then can be used in drawing functions.  A newly
allocated graphics context is supplied with default parameters, such as a
foreground color of white, drawing operation of setting, and width of 0.
You can modify the parameters associated with the graphics context one by
one, by for example, setting the foreground color to black.

A single graphics context could be used for every drawing operation by
constantly setting the parameters associated with it to the values needed
for each drawing call.  But this is inefficient.  The reason that multiple
graphics contexts can be allocated is so that you can minimize the setting of
their parameters.  By presetting the parameters of several graphics contexts
to commonly used values in your program, you can avoid changing them later.
For example, you can call one graphics context white_gc, and another graphics
context black_gc, and then use the correct graphics context in the drawing
functions to draw in either black or white.

The parameters contained within a graphics context are currently the
following:

Drawing mode.
Specifies the operation performed when drawing each pixel.  One of:
	GR_MODE_SET	draw pixels as given (default)
	GR_MODE_XOR	draw pixels using XOR
	GR_MODE_OR	draw pixels using OR
	GR_MODE_AND	draw pixels using AND

Text font.
A small integer identifying the font for drawing text.  The first few are
built-in to the device driver, others must be loaded by the graphics server.
The default font is 0.

Foreground color.
The color that is used to draw almost all objects with, such as lines,
points, ellipses, text, bitmaps, and filled areas.  Default is white.

Background color.
The color used for some functions in addition to the foreground color.
For bitmaps and text, this is the color used for the zero bits.  The
default background color is black.  The drawing of this color can be
disabled by the next parameter.

UseBackground flag.
This is a boolean value which indicates whether or not the background
color is actually to be drawn for bitmaps, text, and the GrArea8 function.
The default is GR_TRUE.


EVENTS

Events are the way in which the graphics system notifies your program
of asychronous changes in the state of the screen, mouse, or keyboard.
Whenever the state changes, your program is notified of this change and
can act on it.  The word "event" is used both for the actual change
that took place, and also for the data that is returned to your program
which describes the change.

Events are generated for various different types of changes that may be useful
for your program to know.  Events directly related to the hardware are the
keyboard and mouse events.  Keyboard events are generated for each key which
is pressed (and released, if possible).  The event contains the character
which caused the event.  Mouse events are generated when a button on the
mouse is pressed or released, or when the mouse position moves.  The event
contains the buttons which are pressed, and the current position of the mouse.
Other events are more subtle, and are based on non-physical changes, such
as having the mouse move into or out of specific windows.

Events are generally tied to individual windows.  Your program can enable
or disable which kinds of events it wants for each window.  Part of the data
associated with an event is the window associated with the event.  For
example, if a key is pressed on the keyboard, the event for that key will
indicate which window that key is for.  You program can then act differently
for different windows.  Events which you have not indicated an interest in
are simply discarded.

The keyboard and mouse events can propagate upwards through the window tree
and be delivered to some parent window.  This occurs if the window does
not select for the event, but one of the parent windows does.  Part of the
information returned about these events is the window that accepted the event,
and also the original window which caused the event.  Therefore, your program
can determine which child window an event was for without having to select
for the event for each child.  Events other than keyboard and mouse events
never propagate.

The window that keyboard events are delivered to depends on the current
mouse position or on the "input focus".  The input focus is a way of
specifying that keyboard events are to be delivered to a particular window,
no matter where the mouse is currently pointing.  Your program can change
the input focus as desired.  If the input focus is set to the root window,
then the keyboard events will be delivered to the window which contains
the mouse pointer (or one of its parents).

Events are returned to your program as a structure containing the information
about the event.  This information is the event type, the window id which
the event is associated with, and other event-specific data.  Events are
stored in a queue, and are delivered to your program one by one as requested.
The order of the events is preserved.  Your program can either simply ask
for the next available event (waiting for one if none are yet available),
or it can check to see if an event is available without waiting.  The
delivering of events only occurs when you request an event.  So even though
events themselves are asychronous, the reading of them is synchronous.
There are no "interrupts" for events, you must explicitly ask for them.

The important thing about programming with events is that your program
should be written to run "upside-down".  That is, you do not have a main
routine which checks that the mouse has been moved, or the keyboard has
been typed on, or which window the mouse is in.  Instead, your main routine
just waits for an event, and then dispatches on its type and which window
it is for.  Generally, you must keep some state information to remember
what is happening in your program.  For example, if the user wants to click
the button in a window to indicate where some text should be inserted, then
your program cannot simply detect the mouse click, and then wait for the
text to be typed.  Instead, when the mouse is clicked, it should just
remember the position of the mouse and set a flag to indicate that text
typing is allowed,  When the keyboard event arrives, this saved information
then enables you to draw the text at the correct location.  Your program
basically becomes one large state machine.

One obscure event is the exposure event.  This is sent to your program when
a window requires redrawing.  Due to lack of memory space, the graphics server
does not attempt to save the data from the parts of windows which are
covered by other windows.  Therefore, when the obscured parts of the window
are uncovered, your program must be told to redraw those parts.  The exposure
event contains a rectangular area which requires drawing (which may in fact
be larger than the area which was actually uncovered).  Your program can
either just redraw that area, or if more convenient, redraw the whole window.
The area to be redrawn has already been cleared to the window's background
color.  When a window is mapped, an exposure event is sent for the window.
Therefore, you should not explicitly draw into a window when it is first
created and mapped, but should instead just wait for the exposure event, and
then draw it.  In this way, the code to draw the window only resides in one
place in your program, and you prevent redundant drawing of the window.
If you are drawing the complete window on all exposure events, then it
might be useful to use GrPeekEvent to examine the next event too.  If it
is also an exposure event for the same window, then you can read it by using
GrGetNextEvent, and thereby prevent redundant redrawing.  Of course, to
be able to redraw the window, you may need to save extra data in order to
regenerate the drawing commands.  (Pixmaps are one way of doing this in
the future, but they are not currently implemented.)

The following is a description of the various types of events which are
available, and (in parenthesis) the typedef name for the structure that
returns the event.  Each event has a type field, which can be used to
distinguish between the various events.  For details on the other data
within the structures, refer to graphics.h.  The typedef GR_EVENT is a
union which contains all of the possible event structures.


GR_EVENT_TYPE_NONE	(GR_EVENT)
	This indicates that no event has occurred.

GR_EVENT_TYPE_EXPOSURE	(GR_EVENT_EXPOSURE)
	This is generated when a window needs redrawing because it is either
	newly mapped, or has been uncovered by another window.  This returns
	the window id, and the x, y, width, and height of the area within
	the window which needs redrawing.

GR_EVENT_TYPE_BUTTON_DOWN	(GR_EVENT_BUTTON)
	This is generated when a button is pressed down on the mouse.
	This returns the window id which generated the event, the window id
	which actually contains the mouse, the current position of the mouse,
	the buttons which are currently down on the mouse, the buttons
	which were just pressed down, and the current modifier flags.

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