microwindows_architecture.html

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

moving over.  If desired, the 7applications programmer can "capture" the
mouse and receive all mouse move messages by calling SetCapture.  ReleaseCapture
returns the processing to normal.  In addition, the GetCapture function will return
the window with capture, if any.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 3.5.3&nbsp;&nbsp;&nbsp; Rectangle and
Region management</h3>

<p>There are a number of functions that are used for rectangles and regions.&nbsp;
Following is the group:</p>

<p>&nbsp;&nbsp;&nbsp;
SetRect&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Define a rectangle structure<br>
&nbsp;&nbsp;&nbsp;
SetRectEmpty&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Define an empty rectangle<br>
&nbsp;&nbsp;&nbsp;
CopyRect&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Copy a rectangle<br>
&nbsp;&nbsp;&nbsp;
IsRectEmpty&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Return TRUE if empty rectangle<br>
&nbsp;&nbsp;&nbsp;
InflateRect&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Enlarge a rectangle<br>
&nbsp;&nbsp;&nbsp;
OffsetRect&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Move a rectangle<br>
&nbsp;&nbsp;&nbsp;
PtInRect&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Determine if a point is in a rectangle<br>
&nbsp;&nbsp; </p>

<p>A large number of region management routines are defined and declared in the winrgn.c
file. </p>

<p>&nbsp;</p>

<h3>4. Nano-X API</h3>

<p>The Nano-X API was originally designed by David Bell, with his mini-x package for the
MINIX operating system.&nbsp; Nano-X is now running on top of the core graphics engine
routines discussed in section 2.&nbsp; Nano-X was designed for a client/server
environment, as no pointers to structures are passed to the API routines, instead a call
is made to the server to get an ID, which is passed to the API functions and is used to
reference the data on the server.&nbsp; In addition, Nano-X is not message-oriented,
instead modeled after the X protocol which was designed for speed on systems where the
client and server machines were different.</p>

<h3>&nbsp;&nbsp;&nbsp; 4.1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Client/Server model</h3>

<p>In Nano-X, there are two linking mechanisms that can be used for applications
programs.&nbsp; In the client/server model, the application program is linked with a
client library that forms a UNIX socket connection with the Nano-X server, a separate
process.&nbsp; Each application then communicates all parameters over the UNIX
socket.&nbsp; For speed and debugging, it is sometimes desirable to link the application
directly with the server.&nbsp; In this case, a stub library is provided that just passes
the client routines parameters to the server function.</p>

<p>The Nano-X naming convention uses GrXXX to designate client side callable routines,
with a marshalling layer implemented in the files nanox/client.c, nanox/nxproto.c, and
nanox/srvnet.c. &nbsp; The client/server network layer currently uses a fast approach to
marshalling the data from the Gr routine into a buffer, and sent all at once to the
receiving stubs in nanox/srvnet.c, before calling the server drawing routines in
nanox/srvfunc.c.&nbsp; In the linked application scenario, the Nano-X client links
directly with the functions in nanox/srvfunc.c, and the nanox/client.c and nanox/srvnet.c
files are not required.</p>

<p>A Nano-X application must call GrOpen before calling any other Nano-X function, and
call GrClose before exiting.&nbsp; These functions establish a connection with the server
when running the client/server model, and return an error status if the server can't be
found or isn't currently running.</p>

<p>The main loop in a Nano-X application is to create some windows, define the events you
want with GrSelectEvents, and then wait for an event with GrGetNextEvent.&nbsp; If it is
desired to merely check for an event, but not wait if there isn't one, GrCheckNextEvent
can be used.&nbsp; GrPeekEvent can be used to examine the next event without removing it
from the queue.</p>

<p>When running Nano-X programs in the client/server model, it's currently necessary to
run the server first in a shell script, then wait a second, then run the
application.&nbsp; Some rewriting is needed to fire up the server when an application
requires it, I believe.</p>

<h3>&nbsp;4.2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Events</h3>

<p>Nano-X applications specify which events they would like to see on a per-window basis
using GrSelectEvents.&nbsp; Then, in the main loop, the application calls GrGetNextEvent
and waits for one of the event types selected for in any of the windows.&nbsp; Typically,
a switch statement is used to determine what to do after receiving the event.&nbsp; This
is similar to the Microwindows's API GetMessage/DispatchMessage loop, except that in
Microwindows API, DispatchMessage is used to send the event to the window's handling
procedure, typically located with the window object.&nbsp; In Nano-X, all the event
handling code for each of the windows must be placed together in the main event loop,
there is no automatic dispatching.&nbsp; Of course, widget sets serve to provide
object-orientation, but this is in addition to the Nano-X API.</p>

<p>Following are the event types that Nano-X programs can recieve:</p>

<p>&nbsp;&nbsp;&nbsp; GR_EVENT_TYPE_NONE, ERROR, EXPOSURE, BUTTON_DOWN, BUTTON_UP,
MOUSE_ENTER, MOUSE_EXIT, MOUSE_MOTION, MOUSE_POSITION, KEY_UP, KEY_DOWN, FOCUS_IN,
FOCUS_OUT, FDINPUT</p>

<p>Note that Nano-X API provides mouse enter and exit events whereas Microwindows API does
not.&nbsp; Also, the exposure events are calculated and sent immediately by the server,
and not combined and possibly delayed for better paint throughput as in the Microwindows
API.</p>

<h3>&nbsp;4.3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Window creation and destruction</h3>

<p>Windows are created in Nano-X with the GrNewWindow function.&nbsp; Windows can be
specified to be input-only, in which case the GrNewInputWindow function is used.&nbsp; The
window border and color is specified in these calls, but will have to be rewritten when
fancier window dressings are required.&nbsp; The return value from these functions is an
ID that can be used in later calls to get a graphics context or perform window
manipulation.</p>

<h3>&nbsp;&nbsp;&nbsp; 4.4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Window showing,
hiding and moving</h3>

<p>Windows are shown by calling the GrMapWindow function, and hidden using
GrUnmapWindow.&nbsp; Mapping a window is required for all ancestors of a window in order
for it to be visible.&nbsp; The GrRaiseWindow call is used to raise the Z order of a
window, while GrLowerWindow is used to lower the Z order.&nbsp; GrMoveWindow is used to
change the position of a window, and GrResizeWindow is used to resize a window.</p>

<h3>&nbsp;&nbsp;&nbsp; 4.5&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Drawing to a window</h3>

<p>Nano-X requires both a window ID and a graphics context ID in order to draw to a
window.&nbsp; Nano-X sends expose events to the application when a window needs to be
redrawn.&nbsp; Unlike the Microwindows API, Nano-X clients are typically required to
create their drawing graphics contexts early on and keep them for the duration of the
application.&nbsp; Like Microwindows though, the graphics contexts record information like
the current background and foreground colors so they don't have to be specified in every
graphics API call.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 4.5.1&nbsp;&nbsp;&nbsp; Graphics contexts</h3>

<p>To allocate a graphics context for a window, call GrNewGC.&nbsp; On termination, call
GrDestroyGC.&nbsp; GrCopyGC can be used to copy on GC to another.&nbsp; GrGetGCInfo is
used to retrieve the settings contained in a GC.&nbsp; After creating a graphics context,
the server returns a graphics context ID.&nbsp; This is then used as a parameter in all
the graphics drawing API functions.&nbsp; In Nano-X programs, the current clipping region
and window coordinate system aren't stored with the GC, as they are in Microwindows'
DCs.&nbsp; This is because, first, Nano-X doesn't support dual coordinate systems for
drawing to the &quot;window dressing&quot; area versus the &quot;user&quot; area of the
window (window and client coordinates in Microwindows).&nbsp; User programs can't draw the
border area of the window, only a single color and width can be specified.&nbsp; Although
resembling X, this will have to change, so that widget sets can specify the look and feel
of all aspects of the windows they maintain.&nbsp; Since the clipping region isn't
maintained with the graphics context, but instead with the window data structure, Nano-X
applications must specify both a window ID and a graphics context ID when calling any
graphics API function.&nbsp; Because of this, many Nano-X applications allocate all
graphics contexts in the beginning of the program, and hold them throughout execution,
since the graphics contexts hold only things like foreground color, etc, and no window
information.&nbsp; This cannot be done with Microwindows API because the DC's contain
window clipping information and must be released before processing the next message.</p>

<h3>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 4.5.2&nbsp;&nbsp;&nbsp; Graphics drawing
API</h3>

<p>Following are the graphics drawing functions available with Nano-X.&nbsp; Like
Microwindows API, these all match up eventually to the graphics engine GdXXX routines.</p>

<p>&nbsp;&nbsp;&nbsp;
GrGetGCTextSize&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Return text width and height information<br>
&nbsp;&nbsp;&nbsp;
GrClearWindow&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Clear a window to it's background color<br>
&nbsp;&nbsp;&nbsp;
GrSetGCForeground&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Set the foreground color in a graphics context<br>
&nbsp;&nbsp;&nbsp;
GrSetGCBackground&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Set the background color in a graphics context<br>
&nbsp;&nbsp;&nbsp; GrSetGCUseBackground&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Set the &quot;use background color&quot; in a graphics context<br>
&nbsp;&nbsp;&nbsp;
GrSetGCMode&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Set the drawing mode<br>
&nbsp;&nbsp;&nbsp;
GrSetGCFont&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Set the font<br>
&nbsp;&nbsp;&nbsp;
GrPoint&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Draw a point in the passed gc's foreground color<br>
&nbsp;&nbsp;&nbsp;
GrLine&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Draw a line in the passed gc's foreground color<br>
&nbsp;&nbsp;&nbsp;
GrRect&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Draw a rectangle in passed gc's foreground color<br>
&nbsp;&nbsp;&nbsp;
GrFillRect&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Fill a rectangle with the passed gc's foreground color<br>
&nbsp;&nbsp;&nbsp;
GrEllipse&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nb