MINI-X TUTORIAL
|
MINI-X TUTORIAL
|
David I. Bell
|
David I. Bell
|
19 May 91
|
19 May 91
|
|
|
This is a simple tutorial on using the mini-X graphics system. Much of this
|
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
|
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
|
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
|
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
|
enough to let you make some simple graphics programs which work. Experience
|
with simple test programs will enable you to build much fancier graphics
|
with simple test programs will enable you to build much fancier graphics
|
programs much easier than trying to decipher what I could tell you.
|
programs much easier than trying to decipher what I could tell you.
|
|
|
I am assuming that you basically know what a screen, pixels, colors,
|
I am assuming that you basically know what a screen, pixels, colors,
|
keyboards, mice, buttons, and windows are. However, you probably don't
|
keyboards, mice, buttons, and windows are. However, you probably don't
|
know exactly what the properties of windows in this system are. Also, you
|
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
|
might not know two other concepts which are important here, which are
|
graphics contexts and events. So these things will be explained in this
|
graphics contexts and events. So these things will be explained in this
|
tutorial.
|
tutorial.
|
|
|
|
|
WINDOWS
|
WINDOWS
|
|
|
Windows are rectangular areas which can be drawn into. Windows have a
|
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,
|
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
|
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.
|
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
|
The top of the tree is known as the root window. The root window is always
|
present, and represents the total screen area.
|
present, and represents the total screen area.
|
|
|
Each child window is clipped by its parent window. This means that a window
|
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
|
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,
|
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
|
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
|
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
|
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.
|
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
|
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.
|
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
|
If two sibling windows overlap, then the more important window will be visible
|
in preference to the less important window. The precedence of visibility
|
in preference to the less important window. The precedence of visibility
|
of siblings can be dynamically adjusted. Clipping can also occur on a window
|
of siblings can be dynamically adjusted. Clipping can also occur on a window
|
by earlier siblings of any of the window's parents.
|
by earlier siblings of any of the window's parents.
|
|
|
Windows can be mapped or unmapped. Unmapped windows are not visible, and
|
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.
|
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
|
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
|
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
|
visible until it and all of its parents are mapped. A newly created window
|
starts off unmapped.
|
starts off unmapped.
|
|
|
Windows have a background color. A newly mapped window is filled with its
|
Windows have a background color. A newly mapped window is filled with its
|
background color. Clearing the window later, or having obscured portions
|
background color. Clearing the window later, or having obscured portions
|
of the window become visible again, will fill the region with the background.
|
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.
|
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
|
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
|
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.
|
specified width. This makes pretty lines around the window, for example.
|
The border cannot be drawn in by the program. Borders are optional, so
|
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
|
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
|
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
|
window. Whether or not a window has borders, its position determines the
|
location of the upper left corner which can be drawn into.
|
location of the upper left corner which can be drawn into.
|
|
|
Windows can have a cursor associated with them. The graphics server tracks
|
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
|
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
|
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
|
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
|
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
|
happen if a mouse button is pressed in a window. Newly created windows
|
inherit the same cursor as their parent.
|
inherit the same cursor as their parent.
|
|
|
There are two types of windows, input-output and input-only windows.
|
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
|
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
|
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
|
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
|
to be changed in different regions of a visible window. The only children
|
of input-only windows are also input-only windows.
|
of input-only windows are also input-only windows.
|
|
|
Windows are identified by integers called window ids. The root window has
|
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
|
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.
|
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
|
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,
|
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
|
but once created the window id remains until the window is destroyed. Window
|
ids are not reused as windows are created and destroyed.
|
ids are not reused as windows are created and destroyed.
|
|
|
|
|
GRAPHICS CONTEXTS
|
GRAPHICS CONTEXTS
|
|
|
When drawing objects such as lines, there are many parameters that can be
|
When drawing objects such as lines, there are many parameters that can be
|
specified for the function call that affect the operation. Besides the
|
specified for the function call that affect the operation. Besides the
|
minimum information needed for the function such as the endpoint coordinates,
|
minimum information needed for the function such as the endpoint coordinates,
|
there are extra parameters that are less important and less variable.
|
there are extra parameters that are less important and less variable.
|
Examples of these extra parameters are color, width (thin or thick), style
|
Examples of these extra parameters are color, width (thin or thick), style
|
(dashed, dotted), and drawing operation (setting, XORing). Instead of
|
(dashed, dotted), and drawing operation (setting, XORing). Instead of
|
requiring the specifying of each of these extra parameters for every function
|
requiring the specifying of each of these extra parameters for every function
|
call, graphics contexts are used. Graphics contexts are just a collection
|
call, graphics contexts are used. Graphics contexts are just a collection
|
of specific combinations of these extra parameters. The many possible
|
of specific combinations of these extra parameters. The many possible
|
extra parameters to each function are replaced by just one extra parameter,
|
extra parameters to each function are replaced by just one extra parameter,
|
which is the graphics context.
|
which is the graphics context.
|
|
|
For example, instead of a function call like:
|
For example, instead of a function call like:
|
drawline(window, x1, y1, x2, y2, color, width, style, operation);
|
drawline(window, x1, y1, x2, y2, color, width, style, operation);
|
|
|
you have instead
|
you have instead
|
drawline(window, gc, x1, y1, x2, y2),
|
drawline(window, gc, x1, y1, x2, y2),
|
|
|
where the graphics context contains within itself the parameters color, width,
|
where the graphics context contains within itself the parameters color, width,
|
style, and operation.
|
style, and operation.
|
|
|
Graphics contexts are stored in the graphics server, and are identified by
|
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
|
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
|
graphic contexts, which then can be used in drawing functions. A newly
|
allocated graphics context is supplied with default parameters, such as a
|
allocated graphics context is supplied with default parameters, such as a
|
foreground color of white, drawing operation of setting, and width of 0.
|
foreground color of white, drawing operation of setting, and width of 0.
|
You can modify the parameters associated with the graphics context one by
|
You can modify the parameters associated with the graphics context one by
|
one, by for example, setting the foreground color to black.
|
one, by for example, setting the foreground color to black.
|
|
|
A single graphics context could be used for every drawing operation by
|
A single graphics context could be used for every drawing operation by
|
constantly setting the parameters associated with it to the values needed
|
constantly setting the parameters associated with it to the values needed
|
for each drawing call. But this is inefficient. The reason that multiple
|
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
|
graphics contexts can be allocated is so that you can minimize the setting of
|
their parameters. By presetting the parameters of several graphics contexts
|
their parameters. By presetting the parameters of several graphics contexts
|
to commonly used values in your program, you can avoid changing them later.
|
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
|
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
|
context black_gc, and then use the correct graphics context in the drawing
|
functions to draw in either black or white.
|
functions to draw in either black or white.
|
|
|
The parameters contained within a graphics context are currently the
|
The parameters contained within a graphics context are currently the
|
following:
|
following:
|
|
|
Drawing mode.
|
Drawing mode.
|
Specifies the operation performed when drawing each pixel. One of:
|
Specifies the operation performed when drawing each pixel. One of:
|
GR_MODE_SET draw pixels as given (default)
|
GR_MODE_SET draw pixels as given (default)
|
GR_MODE_XOR draw pixels using XOR
|
GR_MODE_XOR draw pixels using XOR
|
GR_MODE_OR draw pixels using OR
|
GR_MODE_OR draw pixels using OR
|
GR_MODE_AND draw pixels using AND
|
GR_MODE_AND draw pixels using AND
|
|
|
Text font.
|
Text font.
|
A small integer identifying the font for drawing text. The first few are
|
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.
|
built-in to the device driver, others must be loaded by the graphics server.
|
The default font is 0.
|
The default font is 0.
|
|
|
Foreground color.
|
Foreground color.
|
The color that is used to draw almost all objects with, such as lines,
|
The color that is used to draw almost all objects with, such as lines,
|
points, ellipses, text, bitmaps, and filled areas. Default is white.
|
points, ellipses, text, bitmaps, and filled areas. Default is white.
|
|
|
Background color.
|
Background color.
|
The color used for some functions in addition to the foreground 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
|
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
|
default background color is black. The drawing of this color can be
|
disabled by the next parameter.
|
disabled by the next parameter.
|
|
|
UseBackground flag.
|
UseBackground flag.
|
This is a boolean value which indicates whether or not the background
|
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.
|
color is actually to be drawn for bitmaps, text, and the GrArea8 function.
|
The default is GR_TRUE.
|
The default is GR_TRUE.
|
|
|
|
|
EVENTS
|
EVENTS
|
|
|
Events are the way in which the graphics system notifies your program
|
Events are the way in which the graphics system notifies your program
|
of asychronous changes in the state of the screen, mouse, or keyboard.
|
of asychronous changes in the state of the screen, mouse, or keyboard.
|
Whenever the state changes, your program is notified of this change and
|
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
|
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
|
that took place, and also for the data that is returned to your program
|
which describes the change.
|
which describes the change.
|
|
|
Events are generated for various different types of changes that may be useful
|
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
|
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
|
keyboard and mouse events. Keyboard events are generated for each key which
|
is pressed (and released, if possible). The event contains the character
|
is pressed (and released, if possible). The event contains the character
|
which caused the event. Mouse events are generated when a button on the
|
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
|
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.
|
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
|
Other events are more subtle, and are based on non-physical changes, such
|
as having the mouse move into or out of specific windows.
|
as having the mouse move into or out of specific windows.
|
|
|
Events are generally tied to individual windows. Your program can enable
|
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
|
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
|
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
|
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
|
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
|
for different windows. Events which you have not indicated an interest in
|
are simply discarded.
|
are simply discarded.
|
|
|
The keyboard and mouse events can propagate upwards through the window tree
|
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
|
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
|
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,
|
information returned about these events is the window that accepted the event,
|
and also the original window which caused the event. Therefore, your program
|
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
|
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
|
for the event for each child. Events other than keyboard and mouse events
|
never propagate.
|
never propagate.
|
|
|
The window that keyboard events are delivered to depends on the current
|
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
|
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,
|
specifying that keyboard events are to be delivered to a particular window,
|
no matter where the mouse is currently pointing. Your program can change
|
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,
|
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
|
then the keyboard events will be delivered to the window which contains
|
the mouse pointer (or one of its parents).
|
the mouse pointer (or one of its parents).
|
|
|
Events are returned to your program as a structure containing the information
|
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
|
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
|
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.
|
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
|
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),
|
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
|
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
|
delivering of events only occurs when you request an event. So even though
|
events themselves are asychronous, the reading of them is synchronous.
|
events themselves are asychronous, the reading of them is synchronous.
|
There are no "interrupts" for events, you must explicitly ask for them.
|
There are no "interrupts" for events, you must explicitly ask for them.
|
|
|
The important thing about programming with events is that your program
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
typing is allowed, When the keyboard event arrives, this saved information
|
then enables you to draw the text at the correct location. Your program
|
then enables you to draw the text at the correct location. Your program
|
basically becomes one large state machine.
|
basically becomes one large state machine.
|
|
|
One obscure event is the exposure event. This is sent to your program when
|
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
|
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
|
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
|
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
|
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
|
event contains a rectangular area which requires drawing (which may in fact
|
be larger than the area which was actually uncovered). Your program can
|
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.
|
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
|
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.
|
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
|
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
|
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
|
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.
|
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
|
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
|
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
|
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
|
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
|
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
|
regenerate the drawing commands. (Pixmaps are one way of doing this in
|
the future, but they are not currently implemented.)
|
the future, but they are not currently implemented.)
|
|
|
The following is a description of the various types of events which are
|
The following is a description of the various types of events which are
|
available, and (in parenthesis) the typedef name for the structure that
|
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
|
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
|
distinguish between the various events. For details on the other data
|
within the structures, refer to graphics.h. The typedef GR_EVENT is a
|
within the structures, refer to graphics.h. The typedef GR_EVENT is a
|
union which contains all of the possible event structures.
|
union which contains all of the possible event structures.
|
|
|
|
|
GR_EVENT_TYPE_NONE (GR_EVENT)
|
GR_EVENT_TYPE_NONE (GR_EVENT)
|
This indicates that no event has occurred.
|
This indicates that no event has occurred.
|
|
|
GR_EVENT_TYPE_EXPOSURE (GR_EVENT_EXPOSURE)
|
GR_EVENT_TYPE_EXPOSURE (GR_EVENT_EXPOSURE)
|
This is generated when a window needs redrawing because it is either
|
This is generated when a window needs redrawing because it is either
|
newly mapped, or has been uncovered by another window. This returns
|
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 id, and the x, y, width, and height of the area within
|
the window which needs redrawing.
|
the window which needs redrawing.
|
|
|
GR_EVENT_TYPE_BUTTON_DOWN (GR_EVENT_BUTTON)
|
GR_EVENT_TYPE_BUTTON_DOWN (GR_EVENT_BUTTON)
|
This is generated when a button is pressed down on the mouse.
|
This is generated when a button is pressed down on the mouse.
|
This returns the window id which generated the event, the window id
|
This returns the window id which generated the event, the window id
|
which actually contains the mouse, the current position of the mouse,
|
which actually contains the mouse, the current position of the mouse,
|
the buttons which are currently down on the mouse, the buttons
|
the buttons which are currently down on the mouse, the buttons
|
which were just pressed down, and the current modifier flags.
|
which were just pressed down, and the current modifier flags.
|
|
|
GR_EVENT_TYPE_BUTTON_UP (GR_EVENT_BUTTON)
|
GR_EVENT_TYPE_BUTTON_UP (GR_EVENT_BUTTON)
|
This is generated when a button is released on the mouse. This
|
This is generated when a button is released on the mouse. This
|
returns data similarly to button down.
|
returns data similarly to button down.
|
|
|
GR_EVENT_TYPE_MOUSE_ENTER (GR_EVENT_GENERAL)
|
GR_EVENT_TYPE_MOUSE_ENTER (GR_EVENT_GENERAL)
|
This is generated when the mouse enters a window. This returns the
|
This is generated when the mouse enters a window. This returns the
|
window id which generated the event.
|
window id which generated the event.
|
|
|
GR_EVENT_TYPE_MOUSE_EXIT (GR_EVENT_GENERAL)
|
GR_EVENT_TYPE_MOUSE_EXIT (GR_EVENT_GENERAL)
|
This is generated when the mouse leaves a window. This returns
|
This is generated when the mouse leaves a window. This returns
|
the window id which generated the event.
|
the window id which generated the event.
|
|
|
GR_EVENT_TYPE_MOUSE_MOTION (GR_EVENT_MOUSE)
|
GR_EVENT_TYPE_MOUSE_MOTION (GR_EVENT_MOUSE)
|
Mouse motion is generated for every motion of the mouse, and is
|
Mouse motion is generated for every motion of the mouse, and is
|
used to track the entire history of the mouse. Mouse motion
|
used to track the entire history of the mouse. Mouse motion
|
generates many events and causes lots of overhead. This returns
|
generates many events and causes lots of overhead. This returns
|
data similarly to mouse enter.
|
data similarly to mouse enter.
|
|
|
GR_EVENT_TYPE_MOUSE_POSITION (GR_EVENT_MOUSE)
|
GR_EVENT_TYPE_MOUSE_POSITION (GR_EVENT_MOUSE)
|
Mouse position ignores the history of the motion, and only reports the
|
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
|
latest position of the mouse by only queuing the latest such event for
|
any single client (good for rubber-banding). This returns data
|
any single client (good for rubber-banding). This returns data
|
similarly to mouse enter.
|
similarly to mouse enter.
|
|
|
GR_EVENT_TYPE_KEY_DOWN (GR_EVENT_KEYSTROKE)
|
GR_EVENT_TYPE_KEY_DOWN (GR_EVENT_KEYSTROKE)
|
This indicates that a key has been pressed on the keyboard.
|
This indicates that a key has been pressed on the keyboard.
|
This returns the window id which generated the event, the window id
|
This returns the window id which generated the event, the window id
|
which actually contains the pointer (if the pointer is outside of
|
which actually contains the pointer (if the pointer is outside of
|
the event window, this will be the event window), the current position
|
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
|
of the mouse, the current buttons on the mouse which are down, the
|
current modifier flags, and the character which was typed.
|
current modifier flags, and the character which was typed.
|
|
|
GR_EVENT_TYPE_KEY_UP (GR_EVENT_KEYSTROKE)
|
GR_EVENT_TYPE_KEY_UP (GR_EVENT_KEYSTROKE)
|
This indicates that a key has been released on the keyboard. This
|
This indicates that a key has been released on the keyboard. This
|
event is not necessarily available, and should not be depended on.
|
event is not necessarily available, and should not be depended on.
|
This returns data similarly to key down.
|
This returns data similarly to key down.
|
|
|
GR_EVENT_TYPE_FOCUS_IN (GR_EVENT_GENERAL)
|
GR_EVENT_TYPE_FOCUS_IN (GR_EVENT_GENERAL)
|
This indicates that the input focus has just changed to this window.
|
This indicates that the input focus has just changed to this window.
|
This returns the window id which got focus.
|
This returns the window id which got focus.
|
|
|
GR_EVENT_TYPE_FOCUS_OUT (GR_EVENT_GENERAL)
|
GR_EVENT_TYPE_FOCUS_OUT (GR_EVENT_GENERAL)
|
This indicates that the input focus has just left this window.
|
This indicates that the input focus has just left this window.
|
This returns the window id which lost focus.
|
This returns the window id which lost focus.
|
|
|
|
|
To select for events, you use GrSelectEvents, and specify the window which
|
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
|
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
|
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
|
representing the event types. The mask names are the same as the event
|
names, except that the "_TYPE_" string is replaced by "_MASK_". For
|
names, except that the "_TYPE_" string is replaced by "_MASK_". For
|
example, the mask associated with the event GR_EVENT_TYPE_FOCUS_IN is
|
example, the mask associated with the event GR_EVENT_TYPE_FOCUS_IN is
|
GR_EVENT_MASK_FOCUS_IN.
|
GR_EVENT_MASK_FOCUS_IN.
|
|
|
If you select for both button down and button up events, then the mouse
|
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.
|
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
|
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
|
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
|
the mouse leaves that window. The implicit grabbing ends after the last
|
button is released. While this grabbing occurs, the input focus is also
|
button is released. While this grabbing occurs, the input focus is also
|
not changed as the mouse is moved.
|
not changed as the mouse is moved.
|
|
|
|
|
MODIFIER AND MOUSE BUTTONS
|
MODIFIER AND MOUSE BUTTONS
|
|
|
Modifiers are the status of special keyboard shift-like keys. The state
|
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
|
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.
|
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
|
They are returned as bit values OR'd together in various events. Not all
|
of these modifiers may be implemented. The GrGetScreenInfo function returns
|
of these modifiers may be implemented. The GrGetScreenInfo function returns
|
the modifiers that are implemented. The following modifiers are defined:
|
the modifiers that are implemented. The following modifiers are defined:
|
|
|
GR_MODIFIER_SHIFT shift key is down
|
GR_MODIFIER_SHIFT shift key is down
|
GR_MODIFIER_CTRL ctrl key is down
|
GR_MODIFIER_CTRL ctrl key is down
|
GR_MODIFIER_META meta (or ALT) key is down
|
GR_MODIFIER_META meta (or ALT) key is down
|
GR_MODIFIER_ANY any of the modifiers 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
|
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
|
events. Not all of these buttons may be implemented. The GrGetScreenInfo
|
function returns the buttons that are implemented. The following mouse
|
function returns the buttons that are implemented. The following mouse
|
buttons are defined:
|
buttons are defined:
|
|
|
GR_BUTTON_1 button 1 is down (left)
|
GR_BUTTON_1 button 1 is down (left)
|
GR_BUTTON_2 button 2 is down (middle)
|
GR_BUTTON_2 button 2 is down (middle)
|
GR_BUTTON_3 button 3 is down (right)
|
GR_BUTTON_3 button 3 is down (right)
|
GR_BUTTON_ANY any of the buttons is down
|
GR_BUTTON_ANY any of the buttons is down
|
|
|
|
|
BITMAPS
|
BITMAPS
|
|
|
Bitmaps are defined as an array of GR_BITMAP values, which are unsigned shorts.
|
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
|
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
|
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
|
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
|
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,
|
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
|
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:
|
be used to allocate the proper number of bitmap words for a bitmap, as in:
|
|
|
GR_BITMAP_SIZE(width, height).
|
GR_BITMAP_SIZE(width, height).
|
|
|
The symbol GR_MAX_BITMAP_SIZE is the number of bitmap words required for
|
The symbol GR_MAX_BITMAP_SIZE is the number of bitmap words required for
|
the maximum sized cursor.
|
the maximum sized cursor.
|
|
|
|
|
ERROR CODES
|
ERROR CODES
|
|
|
Calls to the graphics libraries may produce errors. Most errors that
|
Calls to the graphics libraries may produce errors. Most errors that
|
occur are due to specifying a window or graphics context which does not
|
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
|
exist, or attempting an operation which is illegal. Many things are allowed
|
even if pointless, such as drawing outside of the window boundaries, or
|
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
|
while a window is not mapped. The things which return errors are those
|
which definitely indicate a program bug, attempts to exceed the system
|
which definitely indicate a program bug, attempts to exceed the system
|
limits, or a fatal device error.
|
limits, or a fatal device error.
|
|
|
In order to be as efficient as possible, error codes are not returned by
|
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
|
individual function calls. Instead, if a function fails, an error event
|
is generated which will eventually be noticed by the program at a possibly
|
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
|
much later time. This allows many drawing requests to be sent at one time
|
without having to worry about the status of each one.
|
without having to worry about the status of each one.
|
|
|
Error events are detected when the program checks for events, such as
|
Error events are detected when the program checks for events, such as
|
by calling GrGetNextEvent. At this point, if an error had occurred, a
|
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
|
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
|
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
|
disconnect from the server, print out an indication of the error, and exit
|
the program.
|
the program.
|
|
|
The following is a list of the possible errors:
|
The following is a list of the possible errors:
|
|
|
GR_ERROR_BAD_WINDOW_ID the specified window id is unknown
|
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_GC_ID the specified graphics context id is unknown
|
GR_ERROR_BAD_CURSOR_SIZE the specified cursor is too large
|
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_MALLOC_FAILED no more memory is available in the server
|
GR_ERROR_BAD_WINDOW_SIZE the specified window size is illegal
|
GR_ERROR_BAD_WINDOW_SIZE the specified window size is illegal
|
GR_ERROR_KEYBOARD_ERROR an error occurred reading from the keyboard
|
GR_ERROR_KEYBOARD_ERROR an error occurred reading from the keyboard
|
GR_ERROR_MOUSE_ERROR an error occurred reading from the mouse
|
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_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_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_TOO_MUCH_CLIPPING complexity of windows exceeded clipping limits
|
GR_ERROR_SCREEN_ERROR an error occurred talking to the screen driver
|
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_UNMAPPED_FOCUS_WINDOW attempted to set focus to an unmapped window
|
GR_ERROR_BAD_DRAWING_MODE illegal drawing mode specified for a GC
|
GR_ERROR_BAD_DRAWING_MODE illegal drawing mode specified for a GC
|
|
|
|
|
SCREEN PROPERTIES
|
SCREEN PROPERTIES
|
|
|
You do not have to hard code the size of the screen or the number of colors
|
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
|
available in your program. Instead, you can find this information out
|
dynamically after the connection is made to the graphics server, by using
|
dynamically after the connection is made to the graphics server, by using
|
the GrGetScreenInfo call. This returns the above information, and in addition
|
the GrGetScreenInfo call. This returns the above information, and in addition
|
returns the color values for black and white, the aspect ratio of pixels,
|
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
|
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
|
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
|
to be scaled correctly, such as circles. The aspect ratio is the quotient
|
of xdpcm and ydpcm, which are integer values.
|
of xdpcm and ydpcm, which are integer values.
|
|
|
|
|
typedef struct {
|
typedef struct {
|
GR_SIZE rows; /* number of rows on screen */
|
GR_SIZE rows; /* number of rows on screen */
|
GR_SIZE cols; /* number of columns on screen */
|
GR_SIZE cols; /* number of columns on screen */
|
GR_SIZE xdpcm; /* dots/centimeter in x direction */
|
GR_SIZE xdpcm; /* dots/centimeter in x direction */
|
GR_SIZE ydpcm; /* dots/centimeter in y direction */
|
GR_SIZE ydpcm; /* dots/centimeter in y direction */
|
GR_COLOR maxcolor; /* maximum legal color value */
|
GR_COLOR maxcolor; /* maximum legal color value */
|
GR_COLOR black; /* the color black */
|
GR_COLOR black; /* the color black */
|
GR_COLOR white; /* the color white */
|
GR_COLOR white; /* the color white */
|
GR_COUNT fonts; /* number of built-in fonts */
|
GR_COUNT fonts; /* number of built-in fonts */
|
GR_BUTTON buttons; /* buttons which are implemented */
|
GR_BUTTON buttons; /* buttons which are implemented */
|
GR_MODIFIER modifiers; /* modifiers which are implemented */
|
GR_MODIFIER modifiers; /* modifiers which are implemented */
|
} GR_SCREEN_INFO;
|
} GR_SCREEN_INFO;
|
|
|
|
|
INCLUDE FILE AND GRAPHICS LIBRARY
|
INCLUDE FILE AND GRAPHICS LIBRARY
|
|
|
To use the graphics server, your program must include "graphics.h".
|
To use the graphics server, your program must include "graphics.h".
|
This should be put into /usr/include, so that your program simply has
|
This should be put into /usr/include, so that your program simply has
|
the following line at the top:
|
the following line at the top:
|
#include
|
#include
|
|
|
Including this file gives you all of the definitions you need to use the
|
Including this file gives you all of the definitions you need to use the
|
graphics library. These are the typedefs, function declarations, event
|
graphics library. These are the typedefs, function declarations, event
|
structures, and various constants.
|
structures, and various constants.
|
|
|
When loading your program, you need to load the graphics server into the
|
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
|
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:
|
your program is called myprog, then you could build it using the following:
|
cc -o myprog myprog.c -lgraph
|
cc -o myprog myprog.c -lgraph
|
|
|
|
|
TYPEDEFS
|
TYPEDEFS
|
|
|
The following is a list of the typedefs in the include file, and a short
|
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
|
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
|
to find out what their actual C base type is. Most are shorts, unsigned
|
shorts, or longs.
|
shorts, or longs.
|
|
|
GR_COORD coordinate value (x, y locations, signed)
|
GR_COORD coordinate value (x, y locations, signed)
|
GR_SIZE size value (widths, heights, signed)
|
GR_SIZE size value (widths, heights, signed)
|
GR_COUNT number of items (signed)
|
GR_COUNT number of items (signed)
|
GR_COLOR full color value (32 bit value for full generality)
|
GR_COLOR full color value (32 bit value for full generality)
|
GR_COLOR8 eight bit color value (8 bit value for efficient storage)
|
GR_COLOR8 eight bit color value (8 bit value for efficient storage)
|
GR_BITMAP bitmap unit (single words of 16 bits for bitmaps)
|
GR_BITMAP bitmap unit (single words of 16 bits for bitmaps)
|
GR_MODE drawing mode (setting, xoring, anding, oring)
|
GR_MODE drawing mode (setting, xoring, anding, oring)
|
GR_CHAR text character (normal chars)
|
GR_CHAR text character (normal chars)
|
GR_ID resource ids (window, graphics context, pixmap)
|
GR_ID resource ids (window, graphics context, pixmap)
|
GR_DRAW_ID drawable id (window, pixmap)
|
GR_DRAW_ID drawable id (window, pixmap)
|
GR_WINDOW_ID window id (identifies individual window)
|
GR_WINDOW_ID window id (identifies individual window)
|
GR_PIXMAP_ID pixmap id (identifies individual pixmaps, not yet used)
|
GR_PIXMAP_ID pixmap id (identifies individual pixmaps, not yet used)
|
GR_GC_ID graphics context id (identifies indiviual graphics contexts)
|
GR_GC_ID graphics context id (identifies indiviual graphics contexts)
|
GR_FONT font number (identifies individual fonts, first few built-in)
|
GR_FONT font number (identifies individual fonts, first few built-in)
|
GR_BOOL boolean value (GR_TRUE or GR_FALSE)
|
GR_BOOL boolean value (GR_TRUE or GR_FALSE)
|
GR_FUNC function codes (not for clients to use)
|
GR_FUNC function codes (not for clients to use)
|
GR_ERROR error value (reasons for graphics calls to fail)
|
GR_ERROR error value (reasons for graphics calls to fail)
|
GR_EVENT_TYPE event types (identifies the type of event)
|
GR_EVENT_TYPE event types (identifies the type of event)
|
GR_BUTTON button flags (which mouse buttons are depressed)
|
GR_BUTTON button flags (which mouse buttons are depressed)
|
GR_MODIFIER modifier flags (CTRL, SHIFT, etc)
|
GR_MODIFIER modifier flags (CTRL, SHIFT, etc)
|
GR_EVENT_MASK event masks (mask values corresponding to event types)
|
GR_EVENT_MASK event masks (mask values corresponding to event types)
|
GR_FUNC_NAME function name (for error reporting)
|
GR_FUNC_NAME function name (for error reporting)
|
GR_ERROR_FUNC error function (for defining error handlers)
|
GR_ERROR_FUNC error function (for defining error handlers)
|
|
|
|
|
The following typedefs may be useful to your program. None of the library
|
The following typedefs may be useful to your program. None of the library
|
functions (currently) accept any of these structures as arguments, except
|
functions (currently) accept any of these structures as arguments, except
|
for the GrPoly and GrFillPoly routines, which use GR_POINT.
|
for the GrPoly and GrFillPoly routines, which use GR_POINT.
|
|
|
|
|
typedef struct {
|
typedef struct {
|
GR_COORD x; /* x coordinate */
|
GR_COORD x; /* x coordinate */
|
GR_COORD y; /* y coordinate */
|
GR_COORD y; /* y coordinate */
|
} GR_POINT;
|
} GR_POINT;
|
|
|
typedef struct {
|
typedef struct {
|
GR_COORD x1; /* x coordinate of first point */
|
GR_COORD x1; /* x coordinate of first point */
|
GR_COORD y1; /* y coordinate of first point */
|
GR_COORD y1; /* y coordinate of first point */
|
GR_COORD x2; /* x coordinate of second point */
|
GR_COORD x2; /* x coordinate of second point */
|
GR_COORD y2; /* y coordinate of second point */
|
GR_COORD y2; /* y coordinate of second point */
|
} GR_LINE;
|
} GR_LINE;
|
|
|
typedef struct {
|
typedef struct {
|
GR_COORD x; /* x coordinate of center */
|
GR_COORD x; /* x coordinate of center */
|
GR_COORD y; /* y coordinate of center */
|
GR_COORD y; /* y coordinate of center */
|
GR_SIZE rx; /* radius in x direction */
|
GR_SIZE rx; /* radius in x direction */
|
GR_SIZE ry; /* radius in y direction */
|
GR_SIZE ry; /* radius in y direction */
|
} GR_ELLIPSE;
|
} GR_ELLIPSE;
|
|
|
typedef struct {
|
typedef struct {
|
GR_COORD x; /* x coordinate of top left corner */
|
GR_COORD x; /* x coordinate of top left corner */
|
GR_COORD y; /* y coordinate of top left corner */
|
GR_COORD y; /* y coordinate of top left corner */
|
GR_SIZE width; /* width of rectangle */
|
GR_SIZE width; /* width of rectangle */
|
GR_SIZE height; /* height of rectangle */
|
GR_SIZE height; /* height of rectangle */
|
} GR_RECT;
|
} GR_RECT;
|
|
|
|
|
LIMITS
|
LIMITS
|
|
|
The coordinate system is limited to integers in the range GR_COORD_MIN
|
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.
|
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
|
The maximum size of a cursor definition is GR_MAX_CURSOR_SIZE, which is
|
16 pixels by 16 pixels.
|
16 pixels by 16 pixels.
|
|
|
The complexity of overlapping windows is limited to GR_MAX_CLIPRECTS regions,
|
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
|
which is 200. Each window which overlaps another requires another 1 to 4
|
regions depending on its position and size.
|
regions depending on its position and size.
|
|
|
|
|
GRAPHICS CALLS
|
GRAPHICS CALLS
|
|
|
|
|
int
|
int
|
GrOpen()
|
GrOpen()
|
Open a connection to the graphics server. This must be the first graphics
|
Open a connection to the graphics server. This must be the first graphics
|
function used by your program. Currently, this sets the screen into
|
function used by your program. Currently, this sets the screen into
|
graphics mode. Returns zero if successful, -1 on failure.
|
graphics mode. Returns zero if successful, -1 on failure.
|
|
|
|
|
void
|
void
|
GrClose()
|
GrClose()
|
Close the connection to the graphics server, first flushing any graphics
|
Close the connection to the graphics server, first flushing any graphics
|
calls that have been buffered. Currently, this sets the screen back into
|
calls that have been buffered. Currently, this sets the screen back into
|
text mode. This (currently) should be called before your program exits,
|
text mode. This (currently) should be called before your program exits,
|
otherwise the screen will be left in graphics mode. If this occurs, you
|
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.
|
can run the 'tm' program to reset the terminal to text mode.
|
|
|
|
|
GR_ERROR_FUNC
|
GR_ERROR_FUNC
|
GrSetErrorHandler(func)
|
GrSetErrorHandler(func)
|
GR_ERROR_FUNC func; /* function to handle errors */
|
GR_ERROR_FUNC func; /* function to handle errors */
|
Set an error handling routine, which will be called on any errors from
|
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,
|
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.
|
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,
|
Returns the previous error handler (0 if none). When an error occurs,
|
the error handling function is called with the following parameters:
|
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
|
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).
|
of the function which failed, and a resource id (0 if not meaningful).
|
The error routine can return if desired, but without corrective action
|
The error routine can return if desired, but without corrective action
|
new errors will probably occur soon.
|
new errors will probably occur soon.
|
|
|
|
|
void
|
void
|
GrGetScreenInfo(sip)
|
GrGetScreenInfo(sip)
|
GR_SCREEN_INFO *sip; /* location to return info into */
|
GR_SCREEN_INFO *sip; /* location to return info into */
|
Return useful information about the screen. This information returned
|
Return useful information about the screen. This information returned
|
has been documented above.
|
has been documented above.
|
|
|
|
|
void
|
void
|
GrGetFontInfo(font, fip)
|
GrGetFontInfo(font, fip)
|
GR_FONT font; /* font number */
|
GR_FONT font; /* font number */
|
GR_FONT_INFO *fip; /* address of font info */
|
GR_FONT_INFO *fip; /* address of font info */
|
Return useful information about the specified font number. This information
|
Return useful information about the specified font number. This information
|
is the font number, the height of the font, the maximum width of any
|
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
|
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
|
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
|
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
|
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.
|
graphics.h for a definition of the fields of GR_FONT_INFO.
|
|
|
|
|
void
|
void
|
GrGetGCInfo(gc, gcip)
|
GrGetGCInfo(gc, gcip)
|
GR_GC_ID gc; /* graphics context */
|
GR_GC_ID gc; /* graphics context */
|
GR_GC_INFO *gcip; /* address of graphics context info */
|
GR_GC_INFO *gcip; /* address of graphics context info */
|
Return useful information about the specified graphics context. This
|
Return useful information about the specified graphics context. This
|
information is the graphics context id, the current font, the foreground
|
information is the graphics context id, the current font, the foreground
|
and background colors, and so on. If the graphics context is unknown,
|
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
|
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.
|
graphics.h for a definition of the fields of GR_GC_INFO.
|
|
|
|
|
void
|
void
|
GrGetGCTextSize(gc, cp, len, retwidth, retheight, retbase)
|
GrGetGCTextSize(gc, cp, len, retwidth, retheight, retbase)
|
GR_GC_ID gc; /* graphics context containing font */
|
GR_GC_ID gc; /* graphics context containing font */
|
GR_CHAR *cp; /* address of text string */
|
GR_CHAR *cp; /* address of text string */
|
GR_SIZE len; /* length of text string */
|
GR_SIZE len; /* length of text string */
|
GR_SIZE *retwidth; /* returned width of string */
|
GR_SIZE *retwidth; /* returned width of string */
|
GR_SIZE *retheight; /* returned height of string */
|
GR_SIZE *retheight; /* returned height of string */
|
GR_SIZE *retbase; /* returned height of baseline */
|
GR_SIZE *retbase; /* returned height of baseline */
|
Return the size of a text string for the font in a graphics context.
|
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
|
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
|
above the bottom of the font of the baseline for the font. The returned
|
sizes are in pixels.
|
sizes are in pixels.
|
|
|
|
|
void
|
void
|
GrGetNextEvent(ep)
|
GrGetNextEvent(ep)
|
GR_EVENT *ep; /* address where event is returned */
|
GR_EVENT *ep; /* address where event is returned */
|
Return the next event from the event queue, waiting for it if necessary.
|
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
|
If a graphics error had occurred, the error handler will be called at this
|
point. This routine first flushes any buffered graphics commands. The
|
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
|
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
|
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.
|
element of the union can be used to access that particular event type's data.
|
|
|
|
|
void
|
void
|
GrCheckNextEvent(ep)
|
GrCheckNextEvent(ep)
|
GR_EVENT *ep; /* address where event is returned */
|
GR_EVENT *ep; /* address where event is returned */
|
Return the next event from the event queue if one is ready.
|
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.
|
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
|
Therefore, this routine never blocks. This routine first flushes any
|
buffered graphics commands.
|
buffered graphics commands.
|
|
|
|
|
void
|
void
|
GrPeekEvent(ep)
|
GrPeekEvent(ep)
|
GR_EVENT *ep; /* address where event is returned */
|
GR_EVENT *ep; /* address where event is returned */
|
Return the next event from the event queue if one is ready, without removing
|
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
|
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
|
is returned. This routine never blocks. This routine first flushes any
|
buffered graphics commands.
|
buffered graphics commands.
|
|
|
|
|
void
|
void
|
GrSelectEvents(wid, eventmask)
|
GrSelectEvents(wid, eventmask)
|
GR_WINDOW_ID wid; /* window id */
|
GR_WINDOW_ID wid; /* window id */
|
GR_EVENT_MASK eventmask; /* mask of events wanted */
|
GR_EVENT_MASK eventmask; /* mask of events wanted */
|
Select events for a window for this client. The events are a bitmask
|
Select events for a window for this client. The events are a bitmask
|
specifying the events desired for this window. This totally replaces
|
specifying the events desired for this window. This totally replaces
|
any previously selected event mask for the window.
|
any previously selected event mask for the window.
|
|
|
|
|
GR_WINDOW_ID
|
GR_WINDOW_ID
|
GrNewWindow(parent, x, y, width, height, bordersize, background, bordercolor)
|
GrNewWindow(parent, x, y, width, height, bordersize, background, bordercolor)
|
GR_WINDOW_ID parent; /* parent id */
|
GR_WINDOW_ID parent; /* parent id */
|
GR_COORD x; /* x position relative to parent */
|
GR_COORD x; /* x position relative to parent */
|
GR_COORD y; /* y position relative to parent */
|
GR_COORD y; /* y position relative to parent */
|
GR_SIZE width; /* width */
|
GR_SIZE width; /* width */
|
GR_SIZE height; /* height */
|
GR_SIZE height; /* height */
|
GR_SIZE bordersize; /* size of border */
|
GR_SIZE bordersize; /* size of border */
|
GR_COLOR background; /* background color */
|
GR_COLOR background; /* background color */
|
GR_COLOR bordercolor; /* border color */
|
GR_COLOR bordercolor; /* border color */
|
Allocate a new input-output window which is a child of the specified window.
|
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.
|
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 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
|
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
|
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
|
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.
|
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
|
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
|
set to select no events. This routine returns the window id of the window
|
which can be used in other calls.
|
which can be used in other calls.
|
|
|
|
|
GR_WINDOW_ID
|
GR_WINDOW_ID
|
GrNewInputWindow(parent, x, y, width, height)
|
GrNewInputWindow(parent, x, y, width, height)
|
GR_WINDOW_ID parent; /* parent id */
|
GR_WINDOW_ID parent; /* parent id */
|
GR_COORD x; /* x position relative to parent */
|
GR_COORD x; /* x position relative to parent */
|
GR_COORD y; /* y position relative to parent */
|
GR_COORD y; /* y position relative to parent */
|
GR_SIZE width; /* width */
|
GR_SIZE width; /* width */
|
GR_SIZE height; /* height */
|
GR_SIZE height; /* height */
|
Allocate a new input-only window which is a child of the specified window.
|
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
|
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
|
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.
|
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
|
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
|
set to select no events. This routine returns the window id of the window
|
which can be used in other calls.
|
which can be used in other calls.
|
|
|
|
|
void
|
void
|
GrDestroyWindow(wid)
|
GrDestroyWindow(wid)
|
GR_WINDOW_ID wid; /* window to destroy */
|
GR_WINDOW_ID wid; /* window to destroy */
|
This unmaps and then destroys the specified window, and all of its children.
|
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
|
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
|
careful about handling events which refer to the dead window, but which have
|
not been read yet.
|
not been read yet.
|
|
|
|
|
void
|
void
|
GrGetWindowInfo(wid, wip)
|
GrGetWindowInfo(wid, wip)
|
GR_WINDOW_ID wid; /* window id to find out about */
|
GR_WINDOW_ID wid; /* window id to find out about */
|
GR_WINDOW_INFO *wip; /* location to return info into */
|
GR_WINDOW_INFO *wip; /* location to return info into */
|
Return useful information about the specified window. Refer to the
|
Return useful information about the specified window. Refer to the
|
graphics.h include file for the definition of GR_WINDOW_INFO to see
|
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
|
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
|
generated. Instead, the wid value in the returned structure is set to
|
zero, and the other fields are not defined.
|
zero, and the other fields are not defined.
|
|
|
|
|
GR_GC_ID
|
GR_GC_ID
|
GrNewGC()
|
GrNewGC()
|
Allocate a new graphics context with default parameters. These defaults are:
|
Allocate a new graphics context with default parameters. These defaults are:
|
background of black, foreground of white, font as font 0, and drawing mode
|
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
|
as setting. This routine returns the id for the graphics context which can
|
be used in other calls.
|
be used in other calls.
|
|
|
|
|
GR_GC_ID
|
GR_GC_ID
|
GrCopyGC(gc)
|
GrCopyGC(gc)
|
GR_GC_ID gc; /* graphics context to copy */
|
GR_GC_ID gc; /* graphics context to copy */
|
Allocate a new graphics context which is a copy of another one. The new
|
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
|
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
|
independent. This routine returns the id for the graphics context which
|
can be used in other calls.
|
can be used in other calls.
|
|
|
|
|
void
|
void
|
GrDestroyGC(gc)
|
GrDestroyGC(gc)
|
GR_GC_ID gc; /* graphics context to destroy */
|
GR_GC_ID gc; /* graphics context to destroy */
|
Destroy an existing graphics context.
|
Destroy an existing graphics context.
|
|
|
|
|
void
|
void
|
GrMapWindow(wid)
|
GrMapWindow(wid)
|
GR_WINDOW_ID wid; /* window to be mapped */
|
GR_WINDOW_ID wid; /* window to be mapped */
|
Map the window to make it (and possibly its children) visible on the screen.
|
Map the window to make it (and possibly its children) visible on the screen.
|
This paints the border and background of the window, and creates an
|
This paints the border and background of the window, and creates an
|
exposure event to tell the client to draw into it.
|
exposure event to tell the client to draw into it.
|
|
|
|
|
void
|
void
|
GrUnmapWindow(wid)
|
GrUnmapWindow(wid)
|
GR_WINDOW_ID wid; /* window to be unmapped */
|
GR_WINDOW_ID wid; /* window to be unmapped */
|
Unmap the window to make it and its children invisible on the screen.
|
Unmap the window to make it and its children invisible on the screen.
|
|
|
|
|
void
|
void
|
GrRaiseWindow(wid)
|
GrRaiseWindow(wid)
|
GR_WINDOW_ID wid; /* window to be raised */
|
GR_WINDOW_ID wid; /* window to be raised */
|
Raise the window to the highest level among its siblings. This means that
|
Raise the window to the highest level among its siblings. This means that
|
this window will be visible in preference to those siblings. Siblings are
|
this window will be visible in preference to those siblings. Siblings are
|
windows which have the same parent as this window.
|
windows which have the same parent as this window.
|
|
|
|
|
void
|
void
|
GrLowerWindow(wid)
|
GrLowerWindow(wid)
|
GR_WINDOW_ID wid; /* window to be lowered */
|
GR_WINDOW_ID wid; /* window to be lowered */
|
Lower the window to the lowest level among its siblings. This means that
|
Lower the window to the lowest level among its siblings. This means that
|
this window will be covered by any siblings which overlap it.
|
this window will be covered by any siblings which overlap it.
|
|
|
|
|
void
|
void
|
GrMoveWindow(wid, x, y)
|
GrMoveWindow(wid, x, y)
|
GR_WINDOW_ID wid; /* window to be lowered */
|
GR_WINDOW_ID wid; /* window to be lowered */
|
GR_COORD x; /* new relative x position */
|
GR_COORD x; /* new relative x position */
|
GR_COORD y; /* new relative y position */
|
GR_COORD y; /* new relative y position */
|
Move the window to the specified position relative to its parent.
|
Move the window to the specified position relative to its parent.
|
|
|
|
|
void
|
void
|
GrResizeWindow(wid, width, height)
|
GrResizeWindow(wid, width, height)
|
GR_WINDOW_ID wid; /* window to be lowered */
|
GR_WINDOW_ID wid; /* window to be lowered */
|
GR_SIZE width; /* new width of window */
|
GR_SIZE width; /* new width of window */
|
GR_SIZE height; /* new height of window */
|
GR_SIZE height; /* new height of window */
|
Resize the window to be the specified size. Resizing of a window can
|
Resize the window to be the specified size. Resizing of a window can
|
generate exposure events.
|
generate exposure events.
|
|
|
|
|
void
|
void
|
GrClearWindow(wid, exposeflag)
|
GrClearWindow(wid, exposeflag)
|
GR_WINDOW_ID wid; /* window id */
|
GR_WINDOW_ID wid; /* window id */
|
GR_BOOL exposeflag; /* nonzero to cause an exposure */
|
GR_BOOL exposeflag; /* nonzero to cause an exposure */
|
Clear the specified window by setting it to its background color.
|
Clear the specified window by setting it to its background color.
|
If the exposeflag is nonzero, then this also creates an exposure
|
If the exposeflag is nonzero, then this also creates an exposure
|
event for the window.
|
event for the window.
|
|
|
|
|
void
|
void
|
GrSetFocus(wid)
|
GrSetFocus(wid)
|
GR_WINDOW_ID wid; /* window id */
|
GR_WINDOW_ID wid; /* window id */
|
Set the focus to a particular window. This makes keyboard events only
|
Set the focus to a particular window. This makes keyboard events only
|
visible to that window or children of it, depending on the pointer location.
|
visible to that window or children of it, depending on the pointer location.
|
Setting the focus window to the root window makes the input focus track
|
Setting the focus window to the root window makes the input focus track
|
the pointer (which is the default).
|
the pointer (which is the default).
|
|
|
|
|
void
|
void
|
GrSetBorderColor(wid, color)
|
GrSetBorderColor(wid, color)
|
GR_WINDOW_ID wid; /* window id */
|
GR_WINDOW_ID wid; /* window id */
|
GR_COLOR color; /* color for border */
|
GR_COLOR color; /* color for border */
|
Set the border of a window to the specified color.
|
Set the border of a window to the specified color.
|
|
|
|
|
void
|
void
|
GrSetCursor(wid, width, height, hotx, hoty, foreground, background,
|
GrSetCursor(wid, width, height, hotx, hoty, foreground, background,
|
fgbitmap, bgbitmap)
|
fgbitmap, bgbitmap)
|
|
|
GR_WINDOW_ID wid; /* window id to set cursor for */
|
GR_WINDOW_ID wid; /* window id to set cursor for */
|
GR_SIZE width; /* width of cursor */
|
GR_SIZE width; /* width of cursor */
|
GR_SIZE height; /* height of cursor */
|
GR_SIZE height; /* height of cursor */
|
GR_COORD hotx; /* relative x position of hot spot */
|
GR_COORD hotx; /* relative x position of hot spot */
|
GR_COORD hoty; /* relative y position of hot spot */
|
GR_COORD hoty; /* relative y position of hot spot */
|
GR_COLOR foreground; /* foreground color of cursor */
|
GR_COLOR foreground; /* foreground color of cursor */
|
GR_COLOR background; /* background color of cursor */
|
GR_COLOR background; /* background color of cursor */
|
GR_BITMAP *fgbitmap; /* foreground bitmap */
|
GR_BITMAP *fgbitmap; /* foreground bitmap */
|
GR_BITMAP *bgbitmap; /* background bitmap */
|
GR_BITMAP *bgbitmap; /* background bitmap */
|
Specify a new cursor for a window. This cursor will only be used within
|
Specify a new cursor for a window. This cursor will only be used within
|
that window, and by default for its new children. The cursor is defined
|
that window, and by default for its new children. The cursor is defined
|
by giving its width and height, its foreground and background colors, its
|
by giving its width and height, its foreground and background colors, its
|
foreground and background bitmaps, and its "hot spot" position. If a pixel
|
foreground and background bitmaps, and its "hot spot" position. If a pixel
|
is specified for both the foreground and background bitmaps, then the
|
is specified for both the foreground and background bitmaps, then the
|
foreground has precedence. The hot spot is an offset from the upper left
|
foreground has precedence. The hot spot is an offset from the upper left
|
corner of the bitmap, and is the location in the cursor which is important.
|
corner of the bitmap, and is the location in the cursor which is important.
|
|
|
|
|
void
|
void
|
GrMoveCursor(x, y)
|
GrMoveCursor(x, y)
|
GR_COORD x; /* new x position of cursor */
|
GR_COORD x; /* new x position of cursor */
|
GR_COORD y; /* new y position of cursor */
|
GR_COORD y; /* new y position of cursor */
|
Move the cursor to the specified absolute screen coordinates.
|
Move the cursor to the specified absolute screen coordinates.
|
The coordinates are that of the defined hot spot of the cursor.
|
The coordinates are that of the defined hot spot of the cursor.
|
The cursor's appearance is changed to that defined for the window
|
The cursor's appearance is changed to that defined for the window
|
in which the cursor is moved to.
|
in which the cursor is moved to.
|
|
|
|
|
void
|
void
|
GrFlush()
|
GrFlush()
|
Flush the graphics buffer so that all previous requests will be executed.
|
Flush the graphics buffer so that all previous requests will be executed.
|
This is only needed if you do not check events quickly and want to see the
|
This is only needed if you do not check events quickly and want to see the
|
results on the screen soon, since checking for events does an automatic flush.
|
results on the screen soon, since checking for events does an automatic flush.
|
|
|
|
|
void
|
void
|
GrSetGCForeground(gc, foreground)
|
GrSetGCForeground(gc, foreground)
|
GR_GC_ID gc; /* graphics context id */
|
GR_GC_ID gc; /* graphics context id */
|
GR_COLOR foreground; /* foreground color */
|
GR_COLOR foreground; /* foreground color */
|
Set the foreground color in a graphics context. The default is white.
|
Set the foreground color in a graphics context. The default is white.
|
|
|
|
|
void
|
void
|
GrSetGCBackground(gc, background)
|
GrSetGCBackground(gc, background)
|
GR_GC_ID gc; /* graphics context id */
|
GR_GC_ID gc; /* graphics context id */
|
GR_COLOR background; /* background color */
|
GR_COLOR background; /* background color */
|
Set the background color in a graphics context. The default is black.
|
Set the background color in a graphics context. The default is black.
|
|
|
|
|
void
|
void
|
GrSetGCUseBackground(gc, flag)
|
GrSetGCUseBackground(gc, flag)
|
GR_GC_ID gc; /* graphics context id */
|
GR_GC_ID gc; /* graphics context id */
|
GR_BOOL flag; /* TRUE if background is drawn */
|
GR_BOOL flag; /* TRUE if background is drawn */
|
Set whether or not the background color is drawn in bitmaps and text.
|
Set whether or not the background color is drawn in bitmaps and text.
|
This affects GrBitmap, GrArea8, and GrText. The default is GR_TRUE.
|
This affects GrBitmap, GrArea8, and GrText. The default is GR_TRUE.
|
|
|
|
|
void
|
void
|
GrSetGCMode(gc, mode)
|
GrSetGCMode(gc, mode)
|
GR_GC_ID gc; /* graphics context id */
|
GR_GC_ID gc; /* graphics context id */
|
GR_MODE mode; /* drawing mode */
|
GR_MODE mode; /* drawing mode */
|
Set the drawing mode in a graphics context. The drawing mode is one of
|
Set the drawing mode in a graphics context. The drawing mode is one of
|
GR_MODE_SET, GR_MODE_XOR, GR_MODE_AND, or GR_MODE_OR. The default is
|
GR_MODE_SET, GR_MODE_XOR, GR_MODE_AND, or GR_MODE_OR. The default is
|
GR_MODE_SET.
|
GR_MODE_SET.
|
|
|
|
|
void
|
void
|
GrSetGCFont(gc, font)
|
GrSetGCFont(gc, font)
|
GR_GC_ID gc; /* graphics context id */
|
GR_GC_ID gc; /* graphics context id */
|
GR_FONT font; /* text font */
|
GR_FONT font; /* text font */
|
Set the font used for text drawing in a graphics context.
|
Set the font used for text drawing in a graphics context.
|
The font is a number identifying one of several fonts.
|
The font is a number identifying one of several fonts.
|
Font number 0 is always available, and is the default font.
|
Font number 0 is always available, and is the default font.
|
|
|
|
|
void
|
void
|
GrLine(id, gc, x1, y1, x2, y2)
|
GrLine(id, gc, x1, y1, x2, y2)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COORD x1;
|
GR_COORD x1;
|
GR_COORD y1;
|
GR_COORD y1;
|
GR_COORD x2;
|
GR_COORD x2;
|
GR_COORD y2;
|
GR_COORD y2;
|
Draw a line in the specified drawable using the specified graphics context.
|
Draw a line in the specified drawable using the specified graphics context.
|
|
|
|
|
void
|
void
|
GrRect(id, gc, x, y, width, height)
|
GrRect(id, gc, x, y, width, height)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COORD x;
|
GR_COORD x;
|
GR_COORD y;
|
GR_COORD y;
|
GR_SIZE width;
|
GR_SIZE width;
|
GR_SIZE height;
|
GR_SIZE height;
|
Draw the boundary of a rectangle in the specified drawable using the
|
Draw the boundary of a rectangle in the specified drawable using the
|
specified graphics context.
|
specified graphics context.
|
|
|
|
|
void
|
void
|
GrFillRect(id, gc, x, y, width, height)
|
GrFillRect(id, gc, x, y, width, height)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COORD x;
|
GR_COORD x;
|
GR_COORD y;
|
GR_COORD y;
|
GR_SIZE width;
|
GR_SIZE width;
|
GR_SIZE height;
|
GR_SIZE height;
|
Fill a rectangle in the specified drawable using the specified graphics
|
Fill a rectangle in the specified drawable using the specified graphics
|
context. The boundary of this rectangle is identical to that drawn by
|
context. The boundary of this rectangle is identical to that drawn by
|
the GrRect function.
|
the GrRect function.
|
|
|
|
|
void
|
void
|
GrEllipse(id, gc, x, y, rx, ry)
|
GrEllipse(id, gc, x, y, rx, ry)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COORD x;
|
GR_COORD x;
|
GR_COORD y;
|
GR_COORD y;
|
GR_SIZE rx;
|
GR_SIZE rx;
|
GR_SIZE ry;
|
GR_SIZE ry;
|
Draw the boundary of an ellipse in the specified drawable with
|
Draw the boundary of an ellipse in the specified drawable with
|
the specified graphics context.
|
the specified graphics context.
|
|
|
|
|
void
|
void
|
GrFillEllipse(id, gc, x, y, rx, ry)
|
GrFillEllipse(id, gc, x, y, rx, ry)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COORD x;
|
GR_COORD x;
|
GR_COORD y;
|
GR_COORD y;
|
GR_SIZE rx;
|
GR_SIZE rx;
|
GR_SIZE ry;
|
GR_SIZE ry;
|
Fill an ellipse in the specified drawable using the specified
|
Fill an ellipse in the specified drawable using the specified
|
graphics context.
|
graphics context.
|
|
|
|
|
void
|
void
|
GrBitmap(id, gc, x, y, width, height, bitmaptable)
|
GrBitmap(id, gc, x, y, width, height, bitmaptable)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COORD x;
|
GR_COORD x;
|
GR_COORD y;
|
GR_COORD y;
|
GR_SIZE width;
|
GR_SIZE width;
|
GR_SIZE height;
|
GR_SIZE height;
|
GR_BITMAP *bitmaptable;
|
GR_BITMAP *bitmaptable;
|
Draw a rectangular area in the specified drawable using the specified
|
Draw a rectangular area in the specified drawable using the specified
|
graphics context, as determined by the specified bit map. This differs
|
graphics context, as determined by the specified bit map. This differs
|
from rectangle drawing in that the rectangle is drawn using the foreground
|
from rectangle drawing in that the rectangle is drawn using the foreground
|
color and possibly the background color as determined by the bit map.
|
color and possibly the background color as determined by the bit map.
|
Bits which are 1 are the foreground, and bits which are 0 are the background.
|
Bits which are 1 are the foreground, and bits which are 0 are the background.
|
Each row of bits is aligned to the next bitmap word boundary (so there can
|
Each row of bits is aligned to the next bitmap word boundary (so there can
|
be padding at the end of each row). The background bit values are only
|
be padding at the end of each row). The background bit values are only
|
written if the usebackground flag is set in the GC.
|
written if the usebackground flag is set in the GC.
|
|
|
|
|
void
|
void
|
GrArea8(id, gc, x, y, width, height, colortable)
|
GrArea8(id, gc, x, y, width, height, colortable)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COORD x;
|
GR_COORD x;
|
GR_COORD y;
|
GR_COORD y;
|
GR_SIZE width;
|
GR_SIZE width;
|
GR_SIZE height;
|
GR_SIZE height;
|
GR_COLOR8 *colortable;
|
GR_COLOR8 *colortable;
|
Draw a rectangular area in the specified drawable using the specified
|
Draw a rectangular area in the specified drawable using the specified
|
graphics context. This differs from rectangle drawing in that the
|
graphics context. This differs from rectangle drawing in that the
|
color values for each pixel in the rectangle are specified. The color
|
color values for each pixel in the rectangle are specified. The color
|
values are estricted to 8 bit values. The color table is indexed row by
|
values are estricted to 8 bit values. The color table is indexed row by
|
row from left to right. Table values whose color matches the background
|
row from left to right. Table values whose color matches the background
|
color are only written if the usebackground flag is set in the GC.
|
color are only written if the usebackground flag is set in the GC.
|
|
|
|
|
void
|
void
|
GrReadArea8(id, x, y, width, height, colortable)
|
GrReadArea8(id, x, y, width, height, colortable)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_COORD x;
|
GR_COORD x;
|
GR_COORD y;
|
GR_COORD y;
|
GR_SIZE width;
|
GR_SIZE width;
|
GR_SIZE height;
|
GR_SIZE height;
|
GR_COLOR8 *colortable;
|
GR_COLOR8 *colortable;
|
Read the color values from the specified rectangular area of the specified
|
Read the color values from the specified rectangular area of the specified
|
drawable into a supplied buffer. If the drawable is a window which is
|
drawable into a supplied buffer. If the drawable is a window which is
|
obscured by other windows, then the returned values will include the values
|
obscured by other windows, then the returned values will include the values
|
from the covering windows. Regions outside of the screen boundaries, or
|
from the covering windows. Regions outside of the screen boundaries, or
|
from unmapped windows will return black.
|
from unmapped windows will return black.
|
|
|
|
|
void
|
void
|
GrPoint(id, gc, x, y)
|
GrPoint(id, gc, x, y)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COORD x;
|
GR_COORD x;
|
GR_COORD y;
|
GR_COORD y;
|
Draw a point in the specified drawable using the specified graphics context.
|
Draw a point in the specified drawable using the specified graphics context.
|
|
|
|
|
void
|
void
|
GrPoly(id, gc, count, pointtable)
|
GrPoly(id, gc, count, pointtable)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COUNT count;
|
GR_COUNT count;
|
GR_POINT *pointtable;
|
GR_POINT *pointtable;
|
Draw a polygon in the specified drawable using the specified graphics
|
Draw a polygon in the specified drawable using the specified graphics
|
context. The polygon is only complete if the first point is repeated at
|
context. The polygon is only complete if the first point is repeated at
|
the end. Note: currently if the polygon crosses itself, and the drawing
|
the end. Note: currently if the polygon crosses itself, and the drawing
|
mode is set to XOR, then the individual line segments will affect each
|
mode is set to XOR, then the individual line segments will affect each
|
other. The endpoints of the lines are correct, however.
|
other. The endpoints of the lines are correct, however.
|
|
|
|
|
void
|
void
|
GrFillPoly(id, gc, count, pointtable)
|
GrFillPoly(id, gc, count, pointtable)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COUNT count;
|
GR_COUNT count;
|
GR_POINT *pointtable;
|
GR_POINT *pointtable;
|
Draw a filled polygon in the specified drawable using the specified
|
Draw a filled polygon in the specified drawable using the specified
|
graphics context. The last point may be a duplicate of the first point,
|
graphics context. The last point may be a duplicate of the first point,
|
but this is not required. Note: currently only convex polygons are
|
but this is not required. Note: currently only convex polygons are
|
filled properly.
|
filled properly.
|
|
|
|
|
void
|
void
|
GrText(id, gc, x, y, str, count)
|
GrText(id, gc, x, y, str, count)
|
GR_DRAW_ID id;
|
GR_DRAW_ID id;
|
GR_GC_ID gc;
|
GR_GC_ID gc;
|
GR_COORD x;
|
GR_COORD x;
|
GR_COORD y;
|
GR_COORD y;
|
GR_CHAR *str;
|
GR_CHAR *str;
|
GR_COUNT count;
|
GR_COUNT count;
|
Draw a text string at the specified location in the specified drawable
|
Draw a text string at the specified location in the specified drawable
|
using the specified graphics context. The background of the characters
|
using the specified graphics context. The background of the characters
|
are only drawn if the usebackground flag in the GC is set.
|
are only drawn if the usebackground flag in the GC is set.
|
|
|
|
|
EXAMPLE PROGRAM
|
EXAMPLE PROGRAM
|
|
|
The following simple program opens the graphics, creates a window, prints
|
The following simple program opens the graphics, creates a window, prints
|
some text in it, waits for the mouse to be clicked in the window, then exits.
|
some text in it, waits for the mouse to be clicked in the window, then exits.
|
|
|
|
|
#include
|
#include
|
#include
|
#include
|
|
|
#define MARGIN 50 /* margin around window */
|
#define MARGIN 50 /* margin around window */
|
|
|
|
|
main()
|
main()
|
{
|
{
|
GR_WINDOW_ID wid; /* window id */
|
GR_WINDOW_ID wid; /* window id */
|
GR_GC_ID gc; /* graphics context id */
|
GR_GC_ID gc; /* graphics context id */
|
GR_EVENT event; /* current event */
|
GR_EVENT event; /* current event */
|
GR_SCREEN_INFO si; /* screen information */
|
GR_SCREEN_INFO si; /* screen information */
|
|
|
if (GrOpen() < 0) {
|
if (GrOpen() < 0) {
|
fprintf(stderr, "Cannot open graphics\n");
|
fprintf(stderr, "Cannot open graphics\n");
|
exit(1);
|
exit(1);
|
}
|
}
|
|
|
GrGetScreenInfo(&si);
|
GrGetScreenInfo(&si);
|
|
|
wid = GrNewWindow(GR_ROOT_WINDOW_ID, MARGIN, MARGIN,
|
wid = GrNewWindow(GR_ROOT_WINDOW_ID, MARGIN, MARGIN,
|
si.cols - MARGIN * 2, si.rows - MARGIN * 2,
|
si.cols - MARGIN * 2, si.rows - MARGIN * 2,
|
1, si.black, si.white);
|
1, si.black, si.white);
|
|
|
GrSelectEvents(wid, GR_EVENT_MASK_BUTTON_DOWN | GR_EVENT_MASK_EXPOSURE);
|
GrSelectEvents(wid, GR_EVENT_MASK_BUTTON_DOWN | GR_EVENT_MASK_EXPOSURE);
|
GrMapWindow(wid);
|
GrMapWindow(wid);
|
gc = GrNewGC();
|
gc = GrNewGC();
|
|
|
while (1) {
|
while (1) {
|
GrGetNextEvent(&event);
|
GrGetNextEvent(&event);
|
switch (event.type) {
|
switch (event.type) {
|
case GR_EVENT_TYPE_BUTTON_DOWN:
|
case GR_EVENT_TYPE_BUTTON_DOWN:
|
if (event.button.wid != wid)
|
if (event.button.wid != wid)
|
break;
|
break;
|
GrClose();
|
GrClose();
|
exit(0);
|
exit(0);
|
|
|
case GR_EVENT_TYPE_EXPOSURE:
|
case GR_EVENT_TYPE_EXPOSURE:
|
if (event.exposure.wid == wid)
|
if (event.exposure.wid == wid)
|
GrText(wid, gc, 50, 50, "EXIT", 4);
|
GrText(wid, gc, 50, 50, "EXIT", 4);
|
break;
|
break;
|
}
|
}
|
}
|
}
|
}
|
}
|
|
|
|
|
For a more complete demonstration program, see the file "demo.c" in the
|
For a more complete demonstration program, see the file "demo.c" in the
|
/usr/src/graphics/clients directory.
|
/usr/src/graphics/clients directory.
|
|
|
