home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
warptlk3.zip
/
TOOLKIT
/
BOOK
/
GPI4.INF
(
.txt
)
< prev
next >
Wrap
OS/2 Help File
|
1995-10-23
|
1MB
|
15,236 lines
ΓòÉΓòÉΓòÉ 1. Correlation ΓòÉΓòÉΓòÉ
Correlation is the process of determining which primitives, if any, are
contained in an area of interest. The process for nonretained graphics is very
different from the process for retained graphics. The following topics are
related to the information in this chapter:
Presentation spaces
Coordinate spaces and transformations
Editing retained graphics and graphics segments
ΓòÉΓòÉΓòÉ 1.1. About Correlation ΓòÉΓòÉΓòÉ
When you want to select an area of interest on the screen, you usually move the
pointer to the applicable point and signal (by clicking a mouse, for example)
that this is the object you want. This selection process most commonly is used
for graphic applications. For example, your application could permit a user to
select an object, then change its color. Correlation, however, can also be used
in nongraphic applications. For example, your application could model the
operation of a calculator and permit a user to select numbers for mathematical
operations.
The area of interest is defined by the operating system as a small rectangle,
centered on the (x,y) coordinate position, that has been sent to the
application. The virtual rectangle the application generates is known as the
pick aperture. The following figure shows an example of a pick aperture.
The Pick Aperture
The process of determining what lies in the pick aperture differs between
nonretained and retained graphics. For nonretained graphics, the presentation
space must be put in a state that supports correlation before the primitives
are drawn. Then correlation is performed while the primitives are being drawn.
For retained graphics, the segments that contain the graphics can be replayed,
permitting correlation after the primitives are drawn.
Note: The necessity to correlate graphics can usually be predicted. Therefore
you can plan for it when designing applications. However, this does not mean
that you have to create retained (rather than nonretained) graphic segments.
The decision to retain graphics is dependent on several considerations of which
correlation is only one.
ΓòÉΓòÉΓòÉ 1.1.1. Correlating Nonretained Graphics ΓòÉΓòÉΓòÉ
For the purposes of correlation, nonretained graphics are those graphics that
are being correlated during the drawing process. Nonretained graphics can exist
in nonretained graphic segments or completely outside any segment structure.
Primitives outside segments are detectable when the applicable draw control is
set.
Nonretained graphics, inside a segment bracket, can be created in either draw
or draw-and-retain modes. If created in draw-and-retain mode, a segment, at
first, is considered nonretained while the primitives in the segment are being
drawn; then it is considered retained. To be correlated, nonretained segments
must have unique, nonzero identifiers, and must be defined as detectable. The
primitives within these segments can be tagged just as primitives in retained
segments are. However, the tags do not influence the correlation process for
nonretained graphics.
To get correlation data from the drawing of nonretained graphics, three steps
must be performed- after creation of the presentation space but before drawing
the primitives:
1. Call GpiSetDrawControl to switch on the correlation flag (DCTL_CORRELATE,
DCTL_ON).
2. Call GpiSetPickApertureSize, if necessary, to change the size of the pick
aperture.
3. Call GpiSetPickAperturePosition, if necessary, to explicitly position the
aperture. As input to this function, you provide the coordinate position
on which the pick aperture is to be centered, using presentation page
coordinates.
Correlation is performed for the following functions:
Individual primitive-drawing requests, for example, GpiBox
GpiPutData
GpiElement
GpiPlayMetaFile
Correlation is never performed for GpiErase
You detect correlation hits by examining the returned values from the GPI
functions. If GpiLine, for example, draws a line that intersects the pick
aperture, it returns a value of GPI_HITS to indicate a correlation hit. If the
line does not intersect the pick aperture, GpiLine returns a value of GPI_OK,
to indicate the successful drawing of a line without a correlation hit.
GpiLine returns a value of GPI_ERROR if an error is detected.
If the line intersects the pick aperture, a correlation hit is returned even
if the line style is LINETYPE_INVISIBLE. For other primitives, if the object
is drawn in outline mode, a correlation hit is returned only if the pick
aperture intersects the boundary. If the object is in fill mode, a correlation
hit is returned if the pick aperture intersects or lies within the boundary.
The following figure is an example of primitives intersecting the pick
aperture.
Correlating Nonretained Graphics
Each GPI function whose output intersects the pick aperture returns a hit
(GPI_HIT). GpiBox, whose output does not intersect the pick aperture, returns
GPI_OK.
ΓòÉΓòÉΓòÉ 1.1.2. Correlating Retained Graphics ΓòÉΓòÉΓòÉ
The information in a retained graphic segment can be redrawn; therefore,
setting up an environment for correlation is not necessary. Correlation on
retained segments is processed through segment IDs and tags throughout the
segments.
For any retained segment to be a candidate for correlation, the following must
be done:
1. Call GpiOpenSegment with a unique, nonzero identifier.
2. Call GpiSetSegmentAttrs with the following settings:
a. ATTR_DETECTABLE switched ON
b. ATTR_DYNAMIC left OFF (default),
unless the segment is unchained and, therefore, drawn
non-dynamically
c. ATTR_PROP_DETECTABLE left ON (default),
in any segment that calls the candidate segment
3. Call GpiSetTag at appropriate locations within the segment.
Note: The preceding is the recommended method. However, an application still
can receive correlation data about invisible segments.
ΓòÉΓòÉΓòÉ 1.1.2.1. Tagging Primitives within a Segment ΓòÉΓòÉΓòÉ
GpiSetTag inserts a long integer value, called a tag, at the current element
pointer position. The tag becomes a segment element, which serves as an
identifier for the primitives that follow until the next tag is issued. Tags
also are called pick tags or pick identifiers. Typically, applications assign
tags only to elements that correspond to primitives. You can determine the
value of the last tag assigned to an element using GpiQueryTag.
Note: Tags are used only in correlation. They are not used in the chaining or
calling of segments, nor do they cause or modify output.
The long integer value of the tag is 0 by default. However, a 0 value makes the
subsequent primitives undetectable. An application can use this effect to make
some parts of a segment detectable and other parts of it non-detectable. If you
know that this capability is unnecessary, you can change the default tag value
using GpiSetDefTag.
The tag you specify becomes the current tag, and it applies to all subsequent
primitives until you next call GpiSetTag. The tag can be considered one of the
attributes of the primitive and therefore affected by the current attribute
mode. In AM_PRESERVE mode, it is stored on the LIFO stack and can be recalled
with GpiPop. Tags cannot be inserted between a GpiBeginArea and GpiEndArea area
bracket. All primitives within an area have the same tag.
A tag value greater than 0 enables correlation on the subsequent primitives,
but only if the segment ID is greater than 0 as well. The data returned from
each correlation consists of a set of segment-tag pairs. The reason for this
pairing is that a single segment can draw objects in several locations. By
adding identifiers within the segment, an application has a more exact
description of what has intersected the pick aperture.
For simple chained segments, each unique segment-tag pair within the pick
aperture is known as a hit. If two or more primitives in the pick aperture have
the same tag, they are considered a single hit. Hits for called segments differ
slightly and are described in The lMaxDepth Input Parameter.
ΓòÉΓòÉΓòÉ 1.1.2.2. Correlation Functions for Retained Graphics ΓòÉΓòÉΓòÉ
The PM has three different functions that enable you to correlate a uniquely
identified retained segment.
Function Description
GpiCorrelateSegment Permits correlation on a single segment.
GpiCorrelateFrom Permits correlation on a range of segments from a
segment chain.
GpiCorrelateChain Permits correlation on the entire segment chain.
For nonretained graphics, the correlation hits are returned by the actual
drawing commands. For retained graphics, the correlation hits are returned by
the three correlation functions listed above.
The size of the pick aperture is set using GpiSetPickApertureSize, just as
with nonretained graphics. However, the coordinate position on which the pick
aperture is centered usually is obtained from operator input, for example,
from a WM_BUTTON1DOWN message, instead of from GpiSetPickAperturePosition.
After the graphics orders that create pictures are stored in retained
segments, the pictures can be re-created by your application with the various
GpiDraw... functions. Then the user can view the pictures, if the output is
directed to a screen for example. After the user selects an area of interest,
a GpiCorrelate... function redraws the picture internally to determine just
what intersects the pick aperture. The user does not see the re-creation. A
standard order of functions within your application would be:
GpiDraw...
GpiSetPickApertureSize
GpiCorrelate...
ΓòÉΓòÉΓòÉ 1.1.2.3. The Correlation Input Parameters ΓòÉΓòÉΓòÉ
There is only one segment chain per presentation space. Therefore
GpiCorrelateChain needs the presentation space handle as input. The segment
correlation functions need both the presentation space handle and the segment
IDs.
All three correlation functions require the following as input:
Correlation attribute type
Maximum number of hits
Number of segment-tag pairs to be returned for a single hit, called the
pair depth
ΓòÉΓòÉΓòÉ 1.1.2.3.1. The lType Input Parameter ΓòÉΓòÉΓòÉ
The two classifications of segments upon which you can request correlation are
the following:
Segments that have been defined as both detectable and visible
All nonzero segments, regardless of their detectability and visibility
attributes
ΓòÉΓòÉΓòÉ 1.1.2.3.2. The lMaxHits Input Parameter ΓòÉΓòÉΓòÉ
The correlation functions return the number of hits made on the retained
segments. The following figure is an example of a line intersecting the pick
aperture.
Retained Segment Correlation with One Hit
The intersection of a unique segment-identified and -tagged primitive with the
pick aperture (pa) produces one hit. If the pick aperture size were increased,
there still would be only 1 hit. The triangle produces no hit because its tag
is 0.
The following figure is an example of multiple primitives intersecting the pick
aperture.
Retained Segment Correlation with Multiple Hits
Four separate primitives intersect the pick aperture; however, since two
primitives share the same tag, and one primitive has a segment ID of 0, there
are only two hits.
Your application can set a limit on the number of hits to return from a
correlation function. The maximum-number-of-hits parameter influences the size
of the array created to handle the segment-tag pair returned for each hit. By
comparing the maximum number desired to the actual number of hits, your
application can determine whether all hits are accounted for. The following
figure shows an example of the alSegTag data structure that contains the
segment-tag pairs for the previous figure.
alSegTag Data Structure
As shown in the previous figure, the The identifier-tag pairs are returned to
the application in the reverse order of their occurrence on the segment chain.
That is, the highest priority segment is returned first. Therefore, the
application can identify the topmost segment, which is the segment most likely
to have been picked.
ΓòÉΓòÉΓòÉ 1.1.2.3.3. The lMaxDepth Input Parameter ΓòÉΓòÉΓòÉ
When a called segment is picked, correlation data is returned also for all
segments above it in the hierarchy, up to and including the root segment. The
following figure is an example of a picture drawn from a complex segment chain
with called segments.
Multiple Hits from a Called Segment
Two separate items, called from different portions of the segment chain,
intersect the pick aperture. Each has a unique segment identifier and tag, so
there are two hits.
For called segments, the group of segment-tag pairs constitutes a single hit.
You can limit the number of segment and tag pairs returned for each hit using
the maximum depth parameter, just as you can limit the total number of hits
returned to you using the maximum number of hits parameter. The following
figure shows two examples of the alSegTag data structure from the previous
figure, for two different lMaxDepth values.
ΓöîΓöÇ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöÇΓöÇΓöÉ
Γöé Γöéid = 300Γöé 0Γöé Γöé Γöéid = 300Γöé 0Γöé
Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
Γöé Γöétag = 12Γöé 1Γöé Γöé Γöétag = 12Γöé 1Γöé
ΓöîΓöÇ ΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
Γöé Γöé Γöéid = 100Γöé 2Γöé Γöé Γöéid = 100Γöé 2Γöé
Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
Γöé Γöé Γöétag = 1 Γöé 3Γöé 2 actual Γöé Γöétag = 1 Γöé 3Γöé
Γöé Γò₧ΓòÉ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇ hits ΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ ΓöÇΓöÉ
Γöé Γöé Γöéid = 222Γöé 4Γöé returned Γöé Γöé 0 Γöé 4Γöé Γöé
Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
IMax Γöé Γöétag = 6 Γöé 5Γöé Γöé Γöé 0 Γöé 5Γöé Γöé
hitsΓöÇ ΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
= 3 Γöé Γöéid = 220Γöé 6Γöé Γöé Γöé 0 Γöé 6Γöé Γöé
Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé Γöé Γöétag = 4 Γöé 7Γöé Γöé Γöé 0 Γöé 7Γöé Γöé
Γöé Γò₧ΓòÉ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓòÉΓòÉΓòí Γöé ΓöîΓöÇ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓòÉΓòÉΓòí Γöé
Γöé Γöé Γöé ? Γöé 8Γöé Γöé Γöé Γöéid = 222Γöé 8Γöé Γöé
Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé Γöé Γöé ? Γöé 9Γöé IMax Γöé Γöé Γöétag = 6 Γöé 9Γöé Γöé
ΓööΓöÇ ΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ Depth Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé Γöé ? Γöé 10Γöé = 2 Γöé Γöé Γöéid = 220Γöé 10Γöé Γöé
Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé Γöé ? Γöé 11Γöé IMax Γöé Γöé Γöétag = 4 Γöé 11Γöé IMax
ΓööΓöÇ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓöÇΓöÇΓöÿ DepthΓöéΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ hits
= 4 Γöé Γöé Γöéid = 200Γöé 12Γöé = 3
Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé Γöé Γöétag = 2 Γöé 13Γöé Γöé
Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé Γöé Γöéid = 100Γöé 14Γöé Γöé
Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé Γöé Γöétag = 1 Γöé 15Γöé Γöé
ΓööΓöÇΓööΓöÇ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓòÉΓòÉΓòí Γöé
Γöé ? Γöé 16Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé ? Γöé 17Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé ? Γöé 18Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé
Γöé ? Γöé 19Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ ΓöÇΓöÿ
Γöé ? Γöé 20Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
Γöé ? Γöé 21Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
Γöé ? Γöé 22Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé
Γöé ? Γöé 23Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓöÇΓöÇΓöÿ
alSegTag Data Structure for Different lMaxDepth Values
Unused segment-tag pairs for actual hits are set to 0 in the alSegTag array.
There are two major reasons for the PM to provide this capacity. The first is
the consideration of application storage. If your application is a graphics
package, for example, providing extensive design capabilities to an end user,
the user's drawing may be very complex with 10 or more levels of segment
calling. The data returned from a single hit could require an alSegTag array so
large the data overruns the application storage you had reserved. By setting a
maximum calling depth, your application can reserve the correct amount of
storage.
The second consideration is the knowledge that your application's user is
interested only in a certain level of calling depth. Many users will be
interested only in the topmost called segment, because it usually is the
segment containing the functions that performs the actual drawing.
ΓòÉΓòÉΓòÉ 1.1.3. Pick Aperture ΓòÉΓòÉΓòÉ
Your application determines the size of the pick aperture using
GpiQueryPickApertureSize, and determines the page space coordinates of the
center of the aperture with GpiQueryPickAperturePosition.
Because your objective is to retrieve a single detectable object for each
correlation operation, you have to obtain a balance between the number of
detectable objects in a picture and the size of the pick aperture. The more
detectable objects you define, the smaller the pick aperture must be to return
a manageable amount of information to the application. However, the pick
aperture usually is not a 1 pel-by-1 pel rectangle. A larger rectangle makes
better sense because the pick aperture can be difficult to hit with a single
pel; but a larger sampling area, for example 4 pels-by-4 pels, increases the
probability of an intersection between a lighted pel and the pick aperture.
The pick aperture can be specified in any of the units available to the
presentation space. However, the type of unit must be identical to the type
specified for the presentation page. The default size of the pick aperture is
square, with sides equal to the default character cell height.
ΓòÉΓòÉΓòÉ 1.2. Using Correlation ΓòÉΓòÉΓòÉ
This section explains how to perform correlation on the graphics associated
with a segment.
The following figure shows how to set the pick aperture size with
GpiSetPickAperture and correlate the segment chain with GpiCorrelateChain,
passing it the pick-aperture position as the third argument. The functions use
the psizlPick and pptlPick arguments to set the aperture size and position the
aperture center. The correlation is performed on visible and detectable
segments only (PICKSEL_VISIBLE). GpiCorrelateChain copies any segment-tag pairs
to the buffer pointed to by alSegTag and returns the count of hits detected.
#define INCL_GPICORRELATION
#include <os2.h>
LONG fncCORL01 (HPS hps, PSIZEL psizlPick, PPOINTL pptlPick,
LONG lMaxHits, LONG lMaxDepth, PLONG alSegTag)
{
LONG cHits;
GpiSetPickApertureSize(hps, PICKAP_REC, psizlPick);
/* Set the pick aperture. */
cHits = GpiCorrelateChain(hps, PICKSEL_VISIBLE, pptlPick,
lMaxHits, lMaxDepth, alSegTag);
/* Correlate the hits. */
return (cHits); /* Return count of hits. */
} /* fncCORL01 */
ΓòÉΓòÉΓòÉ 2. Coordinate Spaces and Transformations ΓòÉΓòÉΓòÉ
A transformation is an operation performed on a graphics object that changes
the object in one of four ways: translation, rotation, scaling and shearing.
Transformations enable an application to control the location, orientation,
size, and shape of graphics output on any output device.
The transformation of graphics output can be conceptually divided into a series
of distinct transformations applied from one logical stopping point to another.
Coordinate spaces are used as a method of conceptualizing these logical
stopping points. The coordinate spaces are concepts used to explain and
manipulate the transformation process.
A graphics primitive in an intermediate coordinate space cannot be displayed on
an output device and a transformation cannot be interrupted at one of the
distinct stages. The entire series of transformation steps is applied all at
once.
This chapter describes the transformation design process. The following topics
are related to the information in this chapter:
Presentation spaces and device contexts
Segments and retained graphics
Clipping
ΓòÉΓòÉΓòÉ 2.1. About Coordinate Spaces ΓòÉΓòÉΓòÉ
Most of the GPI functions draw their output in a conceptual area called the
world coordinate space. If you picture the presentation space as a blank canvas
on which to draw, the world coordinate space is a Cartesian grid that provides
a reference of scale for what is being drawn.
The components of a picture defined in a world coordinate space are often
defined to a scale convenient only to that component. Applications also can
define each component, or subpicture, starting at the origin (0,0). This
enables applications to define the scale of a subpicture and the location of
the subpicture separately. The ability to define all subpictures at the origin
means there is not always 1-to-1 correspondence between a presentation space
and a world coordinate space. Frequently a separate world coordinate space
exists for every subpicture.
After subpictures are defined in the world coordinate space, they undergo a
process called transformation and then appear on an output device. If an
application has not specifically applied a transformation to its subpictures,
by default the PM applies the identity transformation, which, in effect, makes
no changes to the subpicture.
All graphics systems, not just the PM, use at least one coordinate space to
generate output. The simplest graphics systems use a single coordinate space,
whose points are the pels on the display. These are sometimes called
single-space systems.
The PM creates multiple coordinate spaces and uses transformations to move
subpictures between the coordinate spaces. The PM assembles the application's
graphic output in a process that can use up to five coordinate spaces, known
collectively as the viewing pipeline. The PM coordinate spaces are:
World coordinate space
Model space
Page space
Device space
Media space.
For those who are more familiar with a graphics system that uses a
single-coordinate space, the following table lists the differences to expect
when using PM's multi-coordinate space.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéSingle-Coordinate Space ΓöéPM Multi-Coordinate System Γöé
ΓöéSystems Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDistances and locations ΓöéSeven units of measurement, Γöé
Γöéspecified in pels. Γöéincluding pels, are available.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBecause the shape, or aspect ΓöéThe output is device Γöé
Γöératio, and size of pels can Γöéindependent. Γöé
Γöévary on different devices, theΓöé Γöé
Γöégraphic primitives on one Γöé Γöé
Γöédevice might look different onΓöé Γöé
Γöéanother. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCoordinates entered must ΓöéCoordinates are made Γöé
Γöéalready be device coordinates.Γöédevice-compatible through the Γöé
Γöé ΓöéPM. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Additionally, a single-space system requires that applications keep track of:
The scaling between the subpictures. Often this is accomplished by
forcing the definition of objects to the scale of the picture, instead of
to the scale of the subpicture.
The scaling between the creation space and output space. Often this is
accomplished by forcing the definition of objects to the scale of the
paper or window, instead of to the scale of the subpicture.
All aspects of other transformations.
ΓòÉΓòÉΓòÉ 2.1.1. World Coordinate Space ΓòÉΓòÉΓòÉ
The world coordinate space is where most drawing coordinates are specified.
Each primitive in a world coordinate space is defined using the coordinate
positions in the primitive's definition. For example, if an application draws a
line from (8,4) to (20,75), the coordinate values (8,4) and (20,75) are world
coordinates.
The world coordinate space is specified when the presentation space is created
with GpiCreatePS. The PS_FORMAT option supports two sizes of world coordinate
spaces: short and long. If the size is short (GPIF_SHORT), the world
coordinate space is a rectangular Cartesian space with maximum coordinates of
(32767, 32767) and minimum coordinates of (-32768, -32768). If the world
coordinate space is short, it is the application's responsibility to ensure
that the coordinates defining the subpicture fall within this range.
The second size, long (GPIF_LONG), is the default for the world coordinate
space. Most GPI functions that direct their output to the world coordinate
space, for example GpiLine, accept 32-bit integers as parameters. A 32-bit
integer is equivalent to a rectangular Cartesian space with maximum coordinates
of (134217727, 134217727) and minimum coordinates of (-134217728, -134217728).
World coordinates do not have to be within the range of the presentation page.
A graphic image that requires a high degree of detail and precision might use
most or all of the available coordinate range. A transformation is used to
scale the graphic image down to an appropriate size. The actual presentation
page size is unimportant in most cases. It is used with the page viewport to
redefine the device transform if GpiSetPageViewport is called.
An application can use a clip path clipping area to define the part of the
world space to place in the next coordinate space (the model space). A clip
path is the only clipping region that can be nonrectangular. Its edges can
include arcs, curves, and straight lines. The coordinates that define the
dimensions and shape of a clip path are always world coordinates. (Clipping is
further described in Clipping and Boundary Determination.)
In a world-coordinate space, there can be several graphic primitives. If,
however, an application uses the DM_RETAIN drawing mode to store output in
graphic segments, the operating system assigns a new world space to each
segment. There is also a world space for the drawings outside of segments.
ΓòÉΓòÉΓòÉ 2.1.2. Model Space ΓòÉΓòÉΓòÉ
Model space is the conceptual area where the separate components of a picture,
defined in world space, are brought together. To assemble one or more
primitives from world spaces to model space, the application specifies the
transformations to occur. Then the PM applies them to each of the components.
Model transformations convert world coordinates to model-space coordinates. For
example, an octagon and the word STOP, defined individually in separate
world-coordinate spaces, can be assembled into a stop sign in model space.
Graphics applications can have more than one model space. If there is more than
one model space, the picture components are assembled in page space. If an
application has each model space in a different segment, the model transforms
are reset for each segment.
An application can use a viewing limit clipping area to define the part of a
model space to place in the next coordinate space (the page space). A viewing
limit is always rectangular, and the coordinates that define its location and
dimensions are always model coordinates.
ΓòÉΓòÉΓòÉ 2.1.3. Page Space ΓòÉΓòÉΓòÉ
The page space is where a complete picture is assembled for viewing on a
display screen, or for printing or plotting on a piece of paper. Page
coordinate units can be increments of an inch, a meter, pels, or some arbitrary
value. An application uses GpiCreatePS to specify the units used for page
coordinates.
If the application uses retained-drawing mode, the picture in page space
contains parts of models (or pictures) from each of the model spaces that have
not been clipped. The picture also contains any additional unclipped
graphics-primitive output that the application generated in nonretained-drawing
mode. If the application uses nonretained-drawing mode, the picture in page
space contains all the graphics-primitive output that has not been clipped.
In the page space, an application can use a rectangular clipping area called a
graphics field to define the part of the page space to place in the next
coordinate space (the device space). The coordinates that define the location
and dimensions of the graphics field are always page coordinates.
The page space contains the presentation page whose size and units are defined
when creating the presentation space with GpiCreatePS. The presentation page is
a rectangle in page space.
ΓòÉΓòÉΓòÉ 2.1.4. Device Space ΓòÉΓòÉΓòÉ
The device space is the coordinate space in which a picture is drawn before it
appears in a display screen window or on the printer or plotter.
Device space is defined in device-specific units. Depending on the page unit
used, device-coordinate units can be pels, increments of an inch, increments of
a meter, or arbitrary. For example, if the page unit is pels, the
device-coordinate unit is pels; if the page units are arbitrary, the
device-coordinate units are arbitrary.
ΓòÉΓòÉΓòÉ 2.1.5. Media Space ΓòÉΓòÉΓòÉ
The media space is used only with windows. When an application draws a
primitive at a specified location in a window, it is not actually drawing in
the device space, as the device is the entire terminal screen.
Drawing in a window involves a shifting transformation which moves a drawing
from the given (unitless) position, to position in the specified window.
ΓòÉΓòÉΓòÉ 2.2. About Transformations ΓòÉΓòÉΓòÉ
The coordinate spaces are connected by different transformation functions. In
reality, the input coordinates of the world coordinate space are transformed
directly into device coordinates in a single operation. The intermediate
coordinate spaces exist only to provide a useful model to assist in the
understanding of how to define the different transformation matrixes.
Transformation of graphic primitives occur when a transformation matrix is
applied to those primitives. The individual transformations introduced here do
not actually transform the primitives, but rather define portions of the
transformation matrix. After all portions of the matrix are identified, the
actual operation is performed in a single step.
The transformation functions manipulate graphics primitives as they move from
one coordinate space to the next. Transformation functions usually begin with
the letters Gpi. Most of the function names have a transformation type that
identifies the entities on which it operates. For example, a model
transformation is the transformation type that transforms graphics primitives
between a world coordinate space and a model space. There is a 1-to-1
correspondence between these transformation types and the actual functions. The
transformation matrix data structure is called MATRIXLF.
The following figure lists the sequence of coordinate spaces and the
transformation types between the coordinate spaces. Internally, all
transformations are combined, and the resulting values are held in the same
format as the individual components. By default, there is no viewing window and
no graphics field. The application can use the default page viewport. Clipping
regions for each coordinate space are also shown.
Viewing Pipeline
ΓòÉΓòÉΓòÉ 2.2.1. Identity Transformation ΓòÉΓòÉΓòÉ
The identity transformation is the default transformation between all
coordinate spaces. The identity transformation, makes no change to the original
coordinates of an object. This transformation is also referred to as the unity
transformation, because of the mathematical matrix used to make this
transformation.
The identity matrix looks like this:
Γöî ΓöÉ
Γöé 1 0 0 Γöé
Γöé 0 1 0 Γöé
Γöé 0 0 1 Γöé
Γöö Γöÿ
(Transformations are accomplished with matrix multiplication; and 1, not 0, is
the multiplication identity.)
If a transformation is not explicitly specified, the identity transformation is
used to create that portion of the transformation matrix. Most transformations
applied to a primitive can be in addition to, or instead of, the current
transformation.
ΓòÉΓòÉΓòÉ 2.2.2. Moving through Coordinate Spaces Using the Identity Transformation ΓòÉΓòÉΓòÉ
The effects of transformation can be minimized by defaulting to the identity
transformation. This means that no deliberate action is requested by the
application.
Graphic primitives are drawn in their own coordinate scale in world coordinate
space. The primitives are then combined in model space. Neither the world
coordinate space or the model space have "real world" units associated with
them. This means that if an application draws a line on the x-axis from -300000
to +300000, the line exists as a line 600000 Cartesian units long in both world
coordinate and model space.
Page space is the first of the coordinate spaces to be associated with units
such as millimeters or inches. These units are set with the GpiCreatePS option
PS_UNITS. If the application specifies the option PS_UNITS with the value
PU_ARBITRARY, the page space remains unitless; units are applied when the
output is drawn in device space.
As an example, assume that the units PU_LOMETRIC, (0.1 mm) have been chosen.
Again, assuming the identity transformation between model and page space, the
primitive appears in the page space as a line that extends
300000 * 0.1mm to the right of the origin
300000 * 0.1mm to the left of the origin
A presentation page, a rectangle in page space, has its size defined when a
presentation space is created with GpiCreatePS. The presentation page format is
defined with the GpiCreatePS option, PS_FORMAT. The three choices for that
option are:
GPIF_DEFAULT-32-bit integers or 2GB
GPIF_LONG-32-bit integers
GPIF_SHORT-16-bit integers or 32KB.
PS_FORMAT affects the number of units permitted along the coordinate axes of
the presentation page. If the choice was GPIF_LONG or GPIF_DEFAULT, and, for
example, PS_UNITS remains PU_LOMETRIC, the presentation page axes could range
from 0 to 134217727 0.1mm. If the choice was GPIF_SHORT, the coordinate axes
could range only from 0 to 32767 0.1mm. These limits are the maximum number of
units, presentation pages are usually much smaller.
The presentation page does not affect the primitive in presentation space, it
determines what parts of the primitive are visible. With no transformation to
scale down the primitive from the model to the page space, the presentation
page acts like a sheet of cardboard with a rectangular hole. Only the part of
the page space behind the "hole" is visible in page space. The view of
everything else is blocked by the "cardboard." Only what is visible in the
page space is drawn to the next coordinate space.
Continuing with the example of the 600000 units line above, if GPIF_LONG (or
GPIF_DEFAULT) is selected, the 600000 unit line could easily be viewed in the
presentation page. If GPIF_SHORT is selected, the maximum presentation page
size is 65534 * 0.1 mm units long. In the case, much of the 600000 unit line
would not be drawn into the next coordinate space.
The device space is not affected by the PS_FORMAT option. Whether GPIF_LONG,
or GPIF_SHORT, the device space is a rectangle with maximum coordinates of
(32767, 32767) and minimum coordinates of (-32768, -32768). Note that not all
of this rectangle is visible, since real devices are not that big. The device
space relates to the physical device.
The transformation between the page and device space is handled automatically
by the PM. The presentation page is mapped into a rectangle in the device
space called the page viewport. This transformation is based on the parameters
and options of GpiCreatePS.
Confusion can arise because the effects of the presentation page and the page
viewport appear to be a clipping of the primitives in page and device space.
While the action taken is identical, the term clipping is reserved for the
activity deliberately designated by the application with clipping functions.
ΓòÉΓòÉΓòÉ 2.2.3. Applying Transformations Other Than the Identity Transformation ΓòÉΓòÉΓòÉ
To better understand the workings of transformations other than the identity
transformation, an example of the picture assembly process is illustrated in
the following figure, and a detailed explanation follows.
Picture Assembly Process
In the world space of the preceding figure four segments are drawn, each
containing a different subpicture. The units of the subpictures can be
different (for example, the building might be measured in feet, while the
window might be measured in inches), because each subpicture is converted to
the scale of the completed picture when it is transformed into the completed
picture. All of the subpictures in the previous figure are defined at "real
world" scales in their own (Cartesian) world coordinate space.
The difference between applying and not applying transformations can be seen in
the model space in the previous figure. Without transformations, the
subpictures would be drawn at exactly the coordinates given in the world space
and thus all four subpictures would overlap. With transformations, the
subpictures can be scaled and translated to the scale of the final picture. The
window subpicture, Segment id=200 has been scaled, rotated, and translated.
The model space contains the model of what the application is trying to draw.
There can be more than one model space for very complex drawings, but this is
not a recommended style of programming.
The building also resides in the page space and is prepared in the device space
for printing on an 8 and a half by 11 sheet of paper. This is shown in the
following figure. Most often the page space to device space transformation (the
device transformation) is the identity transformation.
Different Spaces
The transformation process in the previous figure is acting on segments. To
draw the composite picture in model space, create a segment chain that plays
all four segments associated with the building. The purpose of the
world-to-model-space transformation is to transform the graphic segments into a
composite picture.
Having built the composite picture, the next step is to map the composite into
the page space. Usually, the model-to-page-space transformation is the identity
transformation. The different coordinate spaces are shown in the previous
figure.
The user might want an exploded diagram as well as the composite picture. This
is illustrated in the following figure. To create the exploded diagram, the
application must draw the segment chain again, with a slight translation down,
and scaled up (enlarged) with a very large scaling factor.
Again, while it is possible to create several complex images in different model
spaces that must be assembled in the page space, the most frequent use of the
page space is to prepare a view of the model-from-model space with the first
application of "real world" units such as inches or millimeters. As shown in
the previous figures, both world and model space share unitless Cartesian
coordinates.
The usual purpose of the page space is to show multiple views of the image
residing in the model space, as shown in the following figure.
Different Spaces with an Exploded View
The enlarged image on the right side of the page space is drawn after the image
on the left. It therefore has a higher priority and therefore would be drawn on
top of the left side image. To obtain a multi-viewed page space image, the
application defines a clipping region, and applies this region to the second
(enlarged image) playback of the segment chain. The clipping region permits the
enlarged image to appear only on the right side of the page space.
The same building also resides in this model space, but it resides in the page
space, along with an exploded view of the uppermost right side window. The view
is enlarged to such a magnitude that the details of the window are once again
evident. If the images in world coordinate space are not able to be drawn in
the amount of detail now supported by the PM, then drawing details, such as an
exploded view, would reveal the barrenness of the image.
Subpictures can be drawn in world coordinate space without being drawn inside a
graphics segment.
ΓòÉΓòÉΓòÉ 2.2.4. Combining Transformations Between a Coordinate Space Pair ΓòÉΓòÉΓòÉ
There is more than one transformation between the world coordinate and model
spaces, and between the model and page spaces. Depending on the desired output,
the transformations can be combined in different ways.
Between the world coordinate and model space, there are five ways of combining
the three transformations.
World Coordinate to Model Space Transformation Combinations
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéTransformation Function ΓöéEffect ΓöéTransformationΓöé
Γöé Γöé ΓöéType Sequence Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCallSegmentMatrix ΓöéADD ΓöéM I S Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéPREEMPT ΓöéI M S Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéREPLACE Γöé I S Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawSegment (Call Segment) ΓöéDrawing outside Γöé M S Γöé
Γöé Γöéof an instance Γöé Γöé
Γöé Γöédrawing Γöé Γöé
Γöé Γöéprimitive but Γöé Γöé
Γöé Γöéinside a Γöé Γöé
Γöé Γöésegment. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéNo specific function ΓöéDrawing outside Γöé M Γöé
Γöé Γöéof segments Γöé Γöé
Γöé Γöéaltogether. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Abbreviations: I - Instance Transformation, M - Model Transformation, S -
Segment Transformation
Between the model and page space pair are two transformations and they also can
be combined in different ways.
Model to Page Space Transformation Combinations
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéTransformation Function ΓöéEffect ΓöéTransformationΓöé
Γöé Γöé ΓöéType Sequence Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPageViewport ΓöéDrawing inside ΓöéV D Γöé
Γöé Γöéof and outside Γöé Γöé
Γöé Γöéof segments. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetDefaultViewMatrix ΓöéDrawing outside Γöé D Γöé
Γöé Γöéof segments. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Abbreviations: V - Viewing Transformation, D - Default Viewing Transformation
ΓòÉΓòÉΓòÉ 2.2.5. Transformation Mathematics ΓòÉΓòÉΓòÉ
The transformation of a picture can be represented in general terms by two
linear equations that define how the (x,y) coordinates of each point in the
picture are changed.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé The general form of these equations is: Γöé where Γöé
Γöé Γöé Γöé
Γöé x' = Ax + Cy + E Γöé (x,y) defines the original point Γöé
Γöé Γöé (x',y') is the transformed point Γöé
Γöé y' = Bx + Dy + F Γöé A, B, C, D, E, and F are constants. Γöé
Γöé Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The transformations that result from these equations depend on the values of
the constants, which in turn vary according to the type of transformation being
applied.
The operating system handles transformations by using matrix mathematics. In
the matrix mathematics,
Translation is an addition operation
Scaling, reflecting, rotation, and shear are multiplication operations.
If all the transformations were multiplication operations, different types of
transformation could be applied with a single transformation operation.
Therefore, to facilitate the combining of calls, translation in the IBM OS/2
is performed as a multiplication operation, rather than an addition operation.
This requires that the vector representing a point, [ x y ]
be extended by a third component, w: [ x y w ]
This enables all the transformations to be handled in a uniform manner.
This is called a homogeneous coordinate system. The value, w, is a multiplier,
so that the point represented is: (wx, wy).
Note: The PM does not support a 3-dimensional presentation space. The
3-dimensional matrix is created to effect matrix multiplication.
In this notation, the point (x, y) is represented as [ x y 1 ]. To be able
to operate on such three-element vectors, and to combine translation with the
multiplication operations, the 2-by-2 matrix has to be extended to a 3-by-3
matrix, with the third column being:
0
0
1
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé The linear equations: Γöé become the matrix equations: Γöé
Γöé Γöé Γöî ΓöÉ Γöé
Γöé x' = Ax + Cy + E Γöé Γöé A B 0 Γöé Γöé
Γöé Γöé [ x' y' 1 ] = [ x y 1 ] * Γöé C D 0 Γöé Γöé
Γöé y' = Bx + Dy + F Γöé Γöé E F 1 Γöé Γöé
Γöé Γöé Γöö Γöÿ Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
In standard matrix notation, you have:
Γöî ΓöÉ
Γöé Msub11 Msub12 Msub13 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé Msub21 Msub22 Msub23 Γöé
Γöé Msub31 Msub32 Msub33 Γöé
Γöö Γöÿ
ΓòÉΓòÉΓòÉ 2.2.6. Model for Building the Transformation Matrix ΓòÉΓòÉΓòÉ
The transformation matrix shown above can be set equal to an entity as complex
as:
M*I*S*V*D
where * symbolizes matrix multiplication. As mentioned earlier, all the
transformation types might not have a distinct value at all times. One, or all,
could simply be the identity transformation.
These intermediate space and step-wise transformations are not actually how the
operating system performs transformations. The reason for this relates to the
way the PM stores transformation information. The transformation matrix data
structure MATRIXLF, undergoes continuous modification during the drawing
process, and it can be influenced by more than one transformation function from
the application responding, for example, to what a user wants the drawing to
look like.
For example, after creating the model of a building from drawing primitives,
the user might want to see two identical buildings side-by-side. The
application has already applied a series of transformations to the two segments
in world coordinate space to create the model of the building. If the
application, rather than the PM, had to perform the entire transformation over
again from start to finish, it would have to keep track of much more detail.
The PM enables applications to process a smaller portion of the MATRIXLF
structure, in this example the "V" or "V and D" component, to enable the user
to see two buildings side-by-side.
ΓòÉΓòÉΓòÉ 2.2.7. MATRIXLF, the Transformation Matrix ΓòÉΓòÉΓòÉ
For all the transformation functions, the 3-by-3 transformation matrix is
specified as a one-dimensional array in the following order:
(M11, M12, 0, M21, M22, 0, M31, M32, 1)
This one-dimensional array corresponds to the data structure, MATRIXLF. The
elements in the data structure correspond to the matrix multiplication
constants, as shown in the following table.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéTransformation Type ΓöéMatrix Values Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéScaling, Reflection ΓöéM11 and M22 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRotation ΓöéM11, M12, M21, M22 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTranslation ΓöéM31 and M32 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
All nine elements do not have to be specified for every transformation
function. However, those specified are interpreted as the first n of the nine.
If the third, sixth, and ninth elements are specified, they must be 0, 0, and 1
respectively.
ΓòÉΓòÉΓòÉ 2.2.7.1. MATRIXLF Structure ΓòÉΓòÉΓòÉ
Of the nine fields in MATRIXLF, four are special 32-bit FIXED variables. The
remaining five are 32-bit long integer variables.
The scaling, reflecting, and rotation constants, M11,M12,M21,M22, are the
32-bit, signed, FIXED variables, with an implied binary point between the
second and third bytes. The translation constants, M31 and M32, and the three
third-column variables, are 32-bit long integers.
A FIXED variable is a binary representation of a floating-point number. A FIXED
variable has two parts:
The high-order 16-bits, which contain a signed integer in the range
-32768 through 32767.
The low-order 16-bits, which contain the numerator of a fraction in the
range 0 through 65535.
The denominator for this fraction is 65536.
For example, to store the cosine of 60┬░ (0.5) in a FIXED variable, an
application would multiply 65536 by 0.5. The result, 32768, would be the value
to assign to a field in the MATRIXLF structure.
To store a scaling factor of 3 in a FIXED variable, the application would
multiply 65536 by 3. Again, the result, 196608, would be the value to assign
to a field in the MATRIXLF structure.
ΓòÉΓòÉΓòÉ 2.2.7.2. MAKEFIXED Macro ΓòÉΓòÉΓòÉ
The MAKEFIXED macro provides a quick and convenient method for setting the
value of FIXED variables. This macro requires two arguments: the first is the
integer part of the FIXED value, and the second is the fraction part of the
FIXED value. In the following example, MAKEFIXED is used to assign the FIXED
value equivalent of 1 1/8 to the matrix component M11.
matlf.fxM11 = MAKEFIXED(1, 8192)
The first argument, 1, is the integer part of the FIXED value. The second
argument, 8192, is the result of multiplying 65536 by 1/8.
If it is necessary for an application to scale or rotate an object, the
application can avoid most of these mathematics by using the helper functions,
GpiRotate and GpiScale. GpiRotate accepts a rotation in degrees and converts
this value into the appropriate fields in the MATRIXLF structure. Similarly,
GpiScale accepts a scaling factor and fills in the MATRIXLF structure with the
appropriate values.
ΓòÉΓòÉΓòÉ 2.3. About Transformation Operations ΓòÉΓòÉΓòÉ
The available transformations are listed in the following table.
Transformations
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéOperation ΓöéResult Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéScaling ΓöéShrinks or enlarges the object Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéReflection ΓöéCreates a mirror image of an object with Γöé
Γöé Γöérespect to the x- or y- axis Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRotation ΓöéRotates the object Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTranslation ΓöéShifts the object with respect to the originΓöé
Γöé Γöéof the coordinate system Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéShear ΓöéRotates either all the vertical or all the Γöé
Γöé Γöéhorizontal lines in an object Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
These basic operations can be combined.
The PM provides special functions to perform scaling, rotation, and translation
and also enables applications to specify the transformation matrix directly.
Applications can specify values for more than one type of transformation on a
single transformation call.
Transformations are used to manipulate graphic objects as they are being moved
from one coordinate space to another. These operations are performed by
functions called transformation functions. There are also functions that help
perform the transformations called helper functions.
The scaling, reflection, rotation, translation, and shear transformations are
best demonstrated by applying them to a picture. The following figure shows the
image of a flag before any transformations have been applied. The flag is
defined by five points. Their (x,y) coordinates are (0,0), (0,4), (0,6), (2,6),
and (2,4).
Flag Before Transformation
In the next several sections, where the transformations are described in
detail, the effect of the transformation on the flag is illustrated.
ΓòÉΓòÉΓòÉ 2.3.1. Scaling and Reflection Transformations ΓòÉΓòÉΓòÉ
Applications can scale an object by using GpiScale or by modifying the MATRIXLF
structure directly. A scaling transformation reduces or increases the size of a
graphics object. A reflecting transformation creates a mirror image of an
object with respect to the x- or y-axis.
A scaling factor of:
greater than 1 causes an increase in size
greater than 0 but less than 1 causes a reduction in size
less than 0 causes a reflection about that axis. That is, a negative x
scaling factor causes reflection in the x direction.
Note: If an application specifies a scaling factor of greater than 1, the
graphics presentation space must be defined with the coordinate format
GPIF_LONG. This is because 32-bit matrix elements are required to store these
values in retained segment and metafile orders.
The equations to scale by factors Sx and Sy are obtained from the general
equations (with M11 = Sx and M22 = Sy) and can be written:
x' = xSx
y' = ySy
A scaling transformation reduces or increases all the coordinates of an object
by the scaling factor. Any object not aligned on the x- and y-axes is
therefore moved nearer to the origin by a reduction in size, and away from the
origin by an increase in size. For example, if an application applies a
scaling factor of 0.5 to a simple box with its corners at (4,4), (10,4),
(10,10), and (4,10), the four corners moves to (2,2), (5,2), (5,5), and (2,5).
To scale an object about a point without causing it to move, the following
sequence of transformations is required:
1. Translate the scaling point of the object to the origin.
2. Scale the object at the origin.
3. Translate the scaling point of the object back to its original position.
ΓòÉΓòÉΓòÉ 2.3.1.1. Scaling a Graphics Object ΓòÉΓòÉΓòÉ
An application can scale the flag by 0.5, by applying:
x' = 0.5x
y' = 0.5y
The original five points of the flag are transformed:
(0,0) ΓöÇ (0,0)
(0,4) ΓöÇ (0,2)
(0,6) ΓöÇ (0,3)
(2,4) ΓöÇ (1,2)
(2,6) ΓöÇ (1,3)
The following figure shows the effect of the scaling.
Scaling by 0.5
This scaling preserves the shape and orientation of the object, because the
scaling factors in both directions are the same. However, scaling equations
permit different scaling factors to be applied to x and y, which can cause
distortion of the original shape of the object.
ΓòÉΓòÉΓòÉ 2.3.1.2. Reflecting a Graphics Object ΓòÉΓòÉΓòÉ
A negative scaling factor causes a reflection of the object to be drawn. A
scaling factor of -1, for example, causes a mirror image of the object to be
drawn in the appropriate direction.
The following figure shows the flag reflected by applying a negative y scaling
factor.
Reflection
ΓòÉΓòÉΓòÉ 2.3.1.3. MATRIXLF Structure for Scaling and Reflecting ΓòÉΓòÉΓòÉ
When an application scales an object by using the scaling transformation, the
matrix element M11 contains the horizontal scaling component (Sx), and the
matrix element M22 contains the vertical scaling component
(Sy).
Γöî ΓöÉ
Γöé Sx 0 0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé 0 Sy 0 Γöé
Γöé 0 0 1 Γöé
Γöö Γöÿ
If the matrix element M11 contains a negative horizontal reflection component
(-Sx), it causes reflection about the y-axis. If the matrix element M22
contains a negative vertical reflection component (-Sy) it causes reflection
about the x-axis.
ΓòÉΓòÉΓòÉ 2.3.2. Rotation Transformations ΓòÉΓòÉΓòÉ
The application can rotate an object either using GpiRotate or by modifying the
MATRIXLF structure directly.
The operating system applies a transformation to all points in the source
coordinate space. This means that unless an object is drawn about the origin of
the source coordinate space, translation occurs when the object is rotated or
scaled. GpiRotate enables an application to specify a point, relative to the
origin, that is the center of rotation.
The equations for the rotation of an object about the origin (0,0) through an
angle (theta), can be written:
x' = x cos (theta) - y sin (theta)
y' = x sin (theta) + y cos (theta)
A negative (theta) value rotates the object clockwise. For clockwise rotation,
the rotation equations are:
x' = x cos (theta) + y sin (theta)
y' = -x sin (theta) + y cos (theta)
To rotate an object about some other point (p,q), the following sequence of
transformations is required:
1. Translate the object by (-p,-q) to move the point of rotation to the
origin.
2. Rotate the object around the origin.
3. Translate the object by (p,q) to move it back to its original position.
Rotation preserves the shape and size of the object.
ΓòÉΓòÉΓòÉ 2.3.2.1. Rotating a Graphics Object ΓòÉΓòÉΓòÉ
An application can rotate the flag counterclockwise through 90┬░, by applying:
x' = x cos 90 - y sin 90
y' = x sin 90 + y cos 90
Because cos 90 = 0 and sin 90 = 1, these equations become:
x' = - y
y' = x
The original five points are transformed:
(0,0) ΓöÇ (0,0)
(0,4) ΓöÇ (-4,0)
(0,6) ΓöÇ (-6,0)
(2,4) ΓöÇ (-4,2)
(2,6) ΓöÇ (-6,2)
The following figure shows the effect of rotating the flag 90┬░.
Rotation Counterclockwise through 90┬░
ΓòÉΓòÉΓòÉ 2.3.2.2. MATRIXLF Structure for Rotating ΓòÉΓòÉΓòÉ
For counterclockwise rotation:
Γöî ΓöÉ
Γöé cos (theta) sin (theta) 0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé -sin (theta) cos (theta) 0 Γöé
Γöé 0 0 1 Γöé
Γöö Γöÿ
For clockwise rotation:
Γöî ΓöÉ
Γöé cos (theta) -sin (theta) 0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé sin (theta) cos (theta) 0 Γöé
Γöé 0 0 1 Γöé
Γöö Γöÿ
ΓòÉΓòÉΓòÉ 2.3.3. Translation Transformations ΓòÉΓòÉΓòÉ
The application can translate an object either using GpiTranslate or by
modifying the MATRIXLF structure directly.
To move a graphics object by an absolute number of coordinate units, a
translation equation is applied. The equations for translation by Tx and Ty are
obtained from the general equations (with E = Tx, and F = Ty) and can be
written:
x' = x + Tx
y' = y + Ty
Translation preserves the shape, size, and orientation of the object. A
negative Tx value causes movement to the left. A negative Ty value causes
movement downward.
ΓòÉΓòÉΓòÉ 2.3.3.1. Translating a Graphics Object ΓòÉΓòÉΓòÉ
If Tx is equal to 8 and Ty is equal to 5, then:
x' = x + 8
y' = y + 5
The original five points are transformed:
(0,0) ΓöÇ (8,5)
(0,4) ΓöÇ (8,9)
(0,6) ΓöÇ (8,11)
(2,4) ΓöÇ (10,9)
(2,6) ΓöÇ (10,11)
The following figure shows the effect of translating the flag by (8,5).
Translation by (8,5)
ΓòÉΓòÉΓòÉ 2.3.3.2. MATRIXLF Structure for Translating ΓòÉΓòÉΓòÉ
When an application translates an object by using the translation
transformation, the matrix element M31 contains the horizontal translation
component, and the matrix element M32 contains the vertical translation
component, as follows:
Γöî ΓöÉ
Γöé 1 0 0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé 0 1 0 Γöé
Γöé Tx Ty 1 Γöé
Γöö Γöÿ
ΓòÉΓòÉΓòÉ 2.3.4. Shearing Transformations ΓòÉΓòÉΓòÉ
There are two shear transformations: vertical and horizontal. The vertical
shear transformation affects only the y-component of the coordinates of points
in an object, and the horizontal shear transformation affects only the
x-component.
If an application shears an object that contains two orthogonal vectors (two
perpendicular lines), the vectors are no longer orthogonal.
A shearing transformation alters the shape of an object by translating its
x-coordinates relative to its y-coordinates, or its y-coordinates relative to
its x-coordinates. The amount by which the coordinates are translated is
determined by the angle of the shear.
The equation for shearing an object to the left along the x axis by angle
(theta) is:
x' = x - y tan (theta)
y' = y
To shear an object along the y-axis, the tangent of the angle of the shear is
represented by constant B in the general equation.
ΓòÉΓòÉΓòÉ 2.3.4.1. Shearing a Graphics Object ΓòÉΓòÉΓòÉ
The following figure shows the flag sheared to the left along the x-axis.
Shearing Along the X-Axis
ΓòÉΓòÉΓòÉ 2.3.4.2. MATRIXLF Structure for Shearing ΓòÉΓòÉΓòÉ
For vertical shear transformation, the matrix element M11 contains the
horizontal shear component, and the element M21 contains the vertical shear
component, as follows:
Γöî ΓöÉ
Γöé 1 -tan (theta) 0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé 0 1 0 Γöé
Γöé 0 0 1 Γöé
Γöö Γöÿ
For horizontal shear transformation, the matrix element M21 contains the
horizontal shear component, and the matrix element M22 contains the vertical
shear component, as follows:
Γöî ΓöÉ
Γöé 1 0 0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé -tan theta 1 0 Γöé
Γöé 0 0 1 Γöé
Γöö Γöÿ
ΓòÉΓòÉΓòÉ 2.4. About Transformation Functions ΓòÉΓòÉΓòÉ
Transformation functions manipulate objects between coordinate spaces by
applying transformations. Transformation functions require two coordinate
spaces: a source coordinate space, and a target coordinate space. Which
transformation function an application should use is determined by the two
coordinate spaces and by the transformation effect desired.
The world-to-model space, model-to-page space, and page-to-device space
transformations are all actually performed as a single operation. The different
coordinate spaces are conceptual in nature, rather than explicitly defined
entities. Describing them separately is meant to help explain the levels of
activity during transformations.
All transformation functions share certain parameters, although the values and
defaults of those parameters might not be identical.
ΓòÉΓòÉΓòÉ 2.4.1. Current Transformation ΓòÉΓòÉΓòÉ
Every graphics object, whether in world, model, page, or device space, has a
current transformation value, even if that value is simply the identity
transformation.
The default current model transformation is the concatenation of any instance,
segment, and model transformations from the root segment downward. The default
current viewing transformation is the one most recently specified. The device
transformation, which is set by the page viewport and the presentation page,
should not be changed while drawing is in progress.
ΓòÉΓòÉΓòÉ 2.4.2. Accumulating Transformations ΓòÉΓòÉΓòÉ
Each time one of the transformation functions is called by an application, the
application can set the function's option parameter to control how the function
combines the transformation with existing transformations and in what order the
transformations are applied.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIf the application uses this flag...ΓöéThen the operating Γöé
Γöé Γöésystem... Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTRANSFORM_REPLACE ΓöéReplaces any existing Γöé
Γöé Γöétransformations with theΓöé
Γöé Γöénew transformation. The Γöé
Γöé Γöéexisting value of the Γöé
Γöé Γöématrix is discarded and Γöé
Γöé Γöéreplaced by straight Γöé
Γöé Γöésubstitution. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTRANSFORM_PREEMPT ΓöéApplies the new Γöé
Γöé Γöétransformation before Γöé
Γöé Γöéapplying the existing Γöé
Γöé Γöétransformation. Γöé
Γöé ΓöéThe transformation Γöé
Γöé Γöématrix of the new Γöé
Γöé Γöétransformation is Γöé
Γöé Γöépre-multiplied with the Γöé
Γöé Γöétransformation matrix ofΓöé
Γöé Γöéthe current Γöé
Γöé Γöétransformation. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTRANSFORM_ADD ΓöéApplies the new Γöé
Γöé Γöétransformation after Γöé
Γöé Γöéapplying the existing Γöé
Γöé Γöétransformation. Γöé
Γöé ΓöéThe transformation Γöé
Γöé Γöématrix of the new Γöé
Γöé Γöétransformation is Γöé
Γöé Γöépost-multiplied with theΓöé
Γöé Γöétransformation matrix ofΓöé
Γöé Γöéthe current Γöé
Γöé Γöétransformation. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The order in which transformations are applied affects the appearance of the
picture. For example, suppose that a box primitive has been defined, with its
lower-left corner at (4,2) and its upper-right corner at (8,8), and that you
want both to scale the box by 0.5 and to translate it by (-10,-10).
If the box is translated before scaling it, the transformed box is as shown in
the following figure.
Translating before Scaling
The translated box has its lower-left corner at (-6,-8), and its upper-right
corner at (-2,-2). Each of its coordinates is then scaled by 0.5, and the
transformed box has its corners at (-3,-1), (-1,-1), (-3,-4), and (-1,-4).
If the box is scaled before translating it, the transformed box is as shown in
the figure after the following figure.
Scaling before Translating
The scaled box has its lower-left corner at (2,1), and its upper-right corner
at (4,4). The box is then translated by (-10,-10), and the transformed box has
its corners at (-8,-6), (-6,-6), (-6,-9), and (-8,-9).
When an application is drawing a picture in which there are called segments,
and in which transformations are applied to the root segments, the root-segment
transformations should usually be applied to any segments they call. For
example, if a segment that is translated to the left of the picture (by
changing its segment transformation) calls a second segment, that leftward
transformation should also be applied to the called segment. In this instance,
the application would specify TRANSFORM_ADD in the call to GpiCallSegmentMatrix
to add the instance transformation to the calling segments' segment
transformation. Instance transformations are automatically reset on return to
the calling segment.
ΓòÉΓòÉΓòÉ 2.4.3. Concatenating Transformations ΓòÉΓòÉΓòÉ
When an application applies more than one transformation, it can concatenate
the individual transformations to produce a final result. To concatenate
transformations, multiply the individual transformation matrixes. The product
of this multiplication is the concatenated transformation.
There are four ways the final matrix can be concatenated:
1. Hard code the matrix values into the application, then call the
transformation functions.
2. Multiply the individual matrixes, then call the transformation functions.
3. Use the helper functions with the TRANSFORM_ADD option, then call the
transformation functions.
4. Alternately apply transformation operations directly to the
transformation matrix, then apply a transformation function.
Concatenating before calling provides better performance.
ΓòÉΓòÉΓòÉ 2.4.3.1. Hard Coding Values for a Concatenated Matrix ΓòÉΓòÉΓòÉ
Pre-calculating the concatenated matrix values, then hard coding the values
into the application, gives the fastest performance. However, this is rarely
practical as the actual transformations to be performed are often variable.
If an application is, for example, performing interactive graphics, and one of
the options offered to the user is a menu choice of rotate by 90┬░, and enlarge
by 4, then the rotational and scaling factors would not change, and the matrix
values could be hard coded into the application.
ΓòÉΓòÉΓòÉ 2.4.3.2. Multiplying Matrix Values ΓòÉΓòÉΓòÉ
Multiplying transformation matrix values directly offers the second fastest
performance, yet can still respond to a variety of desired transformations. As
many transformation matrixes as needed can be multiplied together. If the
application is concatenating the matrixes itself, it is responsible for
preventing the accumulated transformation side effects.
For example, to rotate an object counterclockwise about the point (p,q) using a
single transformation call requires three transformations to be concatenated.
When the application is specifying each transformation, step-by-step, the
sequence of actions would be:
1. Translate the object by (-p,-q) to move the point of rotation to the
origin.
2. Rotate the object about the origin.
3. Translate the object by (p,q) to move it back to its original position.
The individual matrixes are:
Γöî ΓöÉ Γöî ΓöÉ Γöî ΓöÉ
Γöé 1 0 0 Γöé Γöé cos (theta) sin (theta) 0 Γöé Γöé 1 0 0 Γöé
Γöé 0 1 0 Γöé Γöé -sin (theta) cos (theta) 0 Γöé Γöé 0 1 0 Γöé
Γöé -Tx -Ty 1 Γöé Γöé 0 0 1 Γöé Γöé Tx Ty 1 Γöé
Γöö Γöÿ Γöö Γöÿ Γöö Γöÿ
The matrix for the concatenated transformation is produced incrementally. That
is, two adjacent matrixes are multiplied to produce a single matrix, which is
then multiplied with the third matrix. You can begin by multiplying either the
first two matrixes or the second two matrixes. If you start by multiplying
matrixes 2 and 3 together, the resulting matrix is:
Γöî ΓöÉ
Γöé cos (theta) sin (theta) 0 Γöé
Γöé -sin (theta) cos (theta) 0 Γöé
Γöé Tx Ty 1 Γöé
Γöö Γöÿ
This matrix is multiplied with the first matrix to produce the matrix for
rotating an object at the point (p,q):
Γöî ΓöÉ
Γöé cos (theta) sin (theta) 0 Γöé
Γöé -sin (theta) cos (theta) 0 Γöé
Γöé a b 1 Γöé
Γöö Γöÿ
where:
a = (-Txcos (theta) + Tysin (theta) + Tx)
and
b = (-Txsin (theta) - Tycos (theta) + Ty)
If an application were performing the concatenation for a scaling operation,
again it would have to specify the transformation step-by-step. The sequence
of actions would be:
1. Translate the object's scaling point to the origin.
2. Scale the object at the origin.
3. Translate the object back to its original position.
Here are the three matrixes required to obtain this effect:
Γöî ΓöÉ Γöî ΓöÉ Γöî ΓöÉ
Γöé 1 0 0 Γöé Γöé Sx 0 0 Γöé Γöé 1 0 0 Γöé
Γöé 0 1 0 Γöé Γöé 0 Sy 0 Γöé Γöé 0 1 0 Γöé
Γöé -Tx -Ty 1 Γöé Γöé 0 0 1 Γöé Γöé Tx Ty 1 Γöé
Γöö Γöÿ Γöö Γöÿ Γöö Γöÿ
The matrix of the concatenated transformation is:
Γöî ΓöÉ
Γöé Sx 0 0 Γöé
Γöé 1 Sy 0 Γöé
Γöé (-TxSx+Tx) (-TySy+Ty) 1 Γöé
Γöö Γöÿ
ΓòÉΓòÉΓòÉ 2.4.3.3. Transformation Helper Functions ΓòÉΓòÉΓòÉ
Three helper functions, are provided to perform the matrix math required to
concatenate transformations:
GpiTranslate
GpiRotate
GpiScale
Any of these three functions can be used with the TRANSFORM_ADD option to
concatenate the new matrix with an existing matrix. This method builds up the
matrix in application storage in a sequence of steps before using a single
transform function.
While this is slower than hard coding the matrix, it is faster than
alternating between applying transformation operations directly to the matrix
then applying a transformation function.
The helper functions merely calculate the appropriate matrix. The
transformation is not applied until the array containing the matrix values is
passed to the appropriate transformation function.
Applications use GpiTranslate to change the position of an object. The
application specifies the coordinates of the point to which to move the object
and the name of the transform matrix to use as input to GpiTranslate. The
transformation matrix must be in the form of a one-dimensional array. The
application also can specify whether this transformation is to replace the
value for a previous transformation, or whether it is to be added to it.
Applications use GpiRotate to rotate an object. The application specifies the
angle of rotation, the coordinates of the point around which the object is to
rotate, and the transformation matrix. The transformation matrix must be in
the form of a one-dimensional array. The application also can specify whether
this transformation is to replace the value for a previous transformation, or
whether it is to be added to it.
To scale an object at a point without also moving the object, applications use
GpiScale. When using GpiScale, the application specifies the scaling factor,
the coordinates of the center point, and the transformation matrix. The
transformation matrix must be in the form of a one-dimensional array. The
application also can specify whether this transformation is to replace the
value for a previous transformation, or whether it is to be added to it.
An application could alternate between applying transformation operations
directly to the transformation matrix, then applying a transformation function
with the TRANSFORM_ADD option set. This would build up the matrix in the
presentation space. This method has the slowest performance of the
concatenation methods.
ΓòÉΓòÉΓòÉ 2.4.4. Round-Off Error ΓòÉΓòÉΓòÉ
Whenever an application uses transformations, it should handle any round-off
error that occurs after multiple scaling, rotation, shear, or reflection
transformations. The rounding error increases because a transformation is
incrementally updated by the amount of the error with, for example, the
TRANSFORM_ADD option. For the rotation to remain accurate, the application
should recalculate the transformation, rather than accumulate many small
changes.
For example, if an application uses a rotation transformation to rotate the
hands of a clock, the accuracy of the clock diminishes due to rounding off
after the transformation. The rounding error should be periodically removed by
using the TRANSFORM_REPLACE option at known points, for example, every 90┬░ or
every complete revolution of the clock.
ΓòÉΓòÉΓòÉ 2.4.5. World-Space to Model-Space Transformations ΓòÉΓòÉΓòÉ
The model transformation drawing attribute operates between world and model
space. This attribute can be updated by one of the three following
transformation functions:
GpiSetModelTransformMatrix
GpiSetSegmentTransformMatrix
GpiCallSegmentMatrix
If the model transformation drawing attribute has never been updated, the
attribute defaults to the identity transformation. If the drawing attribute
has been updated, the existing transformation is the concatenation of any
instance, segment, or model transformations from the root segment downwards.
Each time a new segment is opened (using GpiOpenSegment), the model
transformation drawing attribute is reset to its default value.
The three transformations that operate between world space and model space
are:
Model transformations
Segment transformations
Instance transformations
The transformations that occur between world-coordinate and model spaces
depend on the drawing mode and the possible segment type of the drawing
primitive.
The drawing mode can be either nonretain or retain. Nonretain mode is also
called draw mode, as the graphics are immediately displayed. In retain mode,
the graphics orders are stored in chained and unchained segments. A series of
segments are shown in the following figure.
Segments
A model transformation effects objects in any of these segments. A segment
transformation affects the six chained segments, on the left and must be
issued before Root Segment 1 is accessed. An instance transformation can be
applied only to Segment B or Segment D and must be issued from Segment A or
Segment 2 or Segment C. The instance transformation is reset on return to the
calling segment.
ΓòÉΓòÉΓòÉ 2.4.5.1. Model Transformations ΓòÉΓòÉΓòÉ
Model transformations also can be applied to objects both inside and outside of
segments. Model transformations also can be applied to objects created under
retained or nonretained drawing mode. This means model transformations affect
the output from:
GpiDrawChain
GpiDrawFrom
GpiDrawSegment
Any GPI functions that occur outside of a retained-drawing segment
Applications can change the model transformation any number of times in a
single segment. Changing the model transformation changes the transformation
applied to any drawing primitives used subsequently.
An application can determine the values for the current model transformation
by calling GpiQueryModelTransformMatrix, model transformation's scaling,
rotation, and translation values in a one-dimensional array representing
elements in the MATRIXLF structure.
GpiSetModelTransformMatrix specifies the model transformation's scaling,
rotation, and translation values applied to subsequent primitives in the
segment. As this function does not require the name a segment, it also can be
used to apply transformations to primitives outside of segments.
For example, in the building example earlier in the chapter, if the window is
stored in a retained segment, an application could draw several identical
windows on the house by setting a new translation component in the model
transformation before calling GpiBox.
ΓòÉΓòÉΓòÉ 2.4.5.2. Segment Transformations ΓòÉΓòÉΓòÉ
The segment transformation provides a way of defining the model transformation
drawing attribute at the start of a retained segment. The attribute can
subsequently be updated by the model transform orders within the segment. A
segment transformation can be applied only to a retained segment.
Segment transformations alter retained-drawing output. Unlike a model
transformation, which can be set and reset within a segment bracket, a segment
transformation must be set outside of a segment bracket.
An application can determine the values for the current segment transformation
by calling GpiQuerySegmentTransformMatrix, which returns the model
transformation's scaling, rotation, and translation values in a one-dimensional
array representing elements in the MATRIXLF structure.
To apply a segment transformation, applications use
GpiSetSegmentTransformMatrix. GpiSetSegmentTransformMatrix can be used to apply
any sort of transformation to a segment. For example, it can be used to
translate a dynamic segment from one screen position to another, when movement
is requested by the user. The application could perform the following steps,
for example, on receipt of a WM_MOUSEMOVE message:
1. Use the new mouse position to calculate the required displacement from
the current position.
2. Call GpiRemoveDynamics to remove the dynamic segment from its current
position.
3. Call GpiSetSegmentTransformMatrix to translate the segment coordinates by
the required amount.
4. Call GpiDrawDynamics to redraw the segment in its new position.
ΓòÉΓòÉΓòÉ 2.4.5.3. Instance Transformations ΓòÉΓòÉΓòÉ
Instance transformations provide a way of defining the model transformation
drawing attribute for the duration of a called segment.
Instance transformations alter the retained-drawing output from special
segments referred to as called segments. A called segment usually contains a
subpicture duplicated several times in other subpictures. The instance
transformation positions, sizes, and rotates the subpicture each time the
segment is duplicated, because the transformation is set each time the segment
is called. An instance transformation applies only to the called segment, and
is reset on return to the calling segment. There is no query function
associated with the transformation as it must be explicitly set for each called
segment.
To apply an instance transformation, applications call GpiCallSegmentMatrix
from the calling segment. GpiCallSegmentMatrix calls the segment and also
applies the model transformation's scaling, rotation, and translation values in
a one-dimensional array representing elements in the MATRIXLF structure and
passes a segment identifier.
ΓòÉΓòÉΓòÉ 2.4.5.4. World Space-to-Model Space Transformation Summary ΓòÉΓòÉΓòÉ
The following table summarizes the choices available during world-coordinate
space to model space transformations.
World to Model Space Transformation Summary
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéTransformation ΓöéTransformation Function ΓöéApplies Γöé
ΓöéType Γöé Γöéto... Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéModel ΓöéGpiSetModelTransformMatrix ΓöéPrimitives Γöé
ΓöétransformationsΓöé Γöéboth insideΓöé
Γöé Γöé Γöéand outsideΓöé
Γöé Γöé Γöéa segment Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSegment ΓöéGpiSetSegmentTransformMatrix ΓöéA retained Γöé
ΓöétransformationsΓöé Γöésegment, Γöé
Γöé Γöé Γöéissued at Γöé
Γöé Γöé Γöéthe first Γöé
Γöé Γöé Γöéelement of Γöé
Γöé Γöé Γöéthe segmentΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInstance ΓöéGpiCallSegmentMatrix ΓöéOnly the Γöé
ΓöétransformationsΓöé Γöécalled Γöé
Γöé Γöé Γöésegment Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Note: The effect of GpiSetModelTransformMatrix and GpiCallSegmentMatrix on the
model transformation drawing attribute can be duplicated by an equivalent
drawing order in a drawn retained segment.
ΓòÉΓòÉΓòÉ 2.4.6. Model Space-to-Page Space Transformations ΓòÉΓòÉΓòÉ
There are two transformations that operate between the model space and the page
space:
Viewing transformations
Default viewing transformations
All three model transformation types and the viewing transformations can be
considered a part of the picture. The default viewing transformation is part
of the environment, and must not be used for picture construction.
Viewing transformations only apply in retained or nonretained segments. The
viewing transformation attribute is set to the presentation space viewing
transformation matrix value at the start of each drawn root segment and
remains constant for that segment. If GpiSetViewingTransformMatrix is called,
the new value is not used until the next segment is opened. The matrix drawing
attribute is reset to identity at the end of the segment. Each change in a
viewing transformation is equivalent to defining a new model space.
The default viewing transformation is a presentation space attribute and
should not normally be modified in the middle of a picture. This attribute can
be updated by GpiSetDefaultViewMatrix.
A picture is normally constructed in the presentation page with an identity
default viewing transformation. The default viewing transformation can then be
used to scale and scroll the entire picture in the presentation page.
ΓòÉΓòÉΓòÉ 2.4.6.1. Viewing Transformations ΓòÉΓòÉΓòÉ
More than one copy of an entire model space can be drawn in page coordinate
space, and each copy can be transformed as required. Parts of the model space
also can be transformed to the presentation page. For example, an enlarged view
of the tail of an aircraft can be shown with a reduced view of the complete
aircraft in one corner. This is shown in the following figure.
Presentation-Page Space
The entire model space (the aircraft) and a part of the model space (the tail
of the aircraft) are drawn to a single page coordinate space. In each instance,
scaling and translation transformations have been applied.
Alternatively, the displayed picture can be made up of several subpictures with
no common graphical elements. For example, the aircraft can be drawn in one
part of the display, and a map of an airport in another part of the display. In
this instance, the final picture would be derived from different model spaces.
Whether multiple views are derived from a single model space or from different
model spaces, there are two items to address for each instance of a model space
incorporated into the presentation page:
1. The part of the model space to be displayed must be identified by
defining a viewing window for the model space.
2. To position and size the contents of the model space in page coordinate
space, a viewing transformation must be specified.
To get views of one or more model spaces on the screen simultaneously, each
model space is drawn the required number of times. Before each drawing
request, the viewing window is defined and a viewing transformation is
specified.
ΓòÉΓòÉΓòÉ 2.4.6.2. Defining the Viewing Window ΓòÉΓòÉΓòÉ
The viewing window is a conceptual boundary around a part of the model space.
To produce the picture in the previous figure, the aircraft is drawn twice. The
first time, the viewing window is on only the tail of the aircraft, and the
second time, the viewing window is on the entire aircraft. Only those parts of
the model space within the viewing window are visible in the picture assembled
in presentation-page space. GpiSetViewingLimits is used to define the viewing
window.
ΓòÉΓòÉΓòÉ 2.4.6.3. Graphics Field ΓòÉΓòÉΓòÉ
Applications also can specify a type of viewing window for the presentation
page smaller than the page. This window is known as the graphics field. To
define a graphics field, use GpiSetGraphicsField. By default, no graphics field
is specified. If a graphics field is defined, the picture assembled within it
is the picture that is visible on the output device.
An application can determine the current values for the viewing transformation
by calling GpiQueryViewingTransformMatrix, which returns the transformation
values in a one-dimensional array representing elements in the MATRIXLF
structure. The application can set the values by calling
GpiSetViewingTransformMatrix, and passing the transformation values in a
one-dimensional array representing elements in MATRIXLF structure.
ΓòÉΓòÉΓòÉ 2.4.6.4. Default Viewing Transformations ΓòÉΓòÉΓòÉ
The default viewing window is the same size as the model space. Therefore, to
display one or more entire model spaces, draw the picture the required number
of times and let the viewing window default each time.
Default viewing transformations scroll or zoom pictures in a window on a
display screen. An application can determine the current values for the default
viewing transformation by calling GpiQueryDefaultViewMatrix, which returns the
default-viewing-transformation values in a one-dimensional array representing
elements in MATRIXLF structure. The application can set these values by calling
GpiSetDefaultViewMatrix and passing the transformation values in a
one-dimensional array representing elements in MATRIXLF structure.
A default viewing transformation is applied when the screen contents are zoomed
or scrolled by user interaction. A picture is zoomed when the user wants to
increase or decrease the size of an area of interest. A picture is usually
scrolled when there is more in the presentation page than can be displayed in a
single page of output. Anything lying off the screen, but within the range of
the presentation page, can be scrolled into view. The default viewing
transformation applies to the entire page coordinate space, and can be added
to, or can replace, the current default viewing transformation. The PM applies
it after any viewing transformations.
When a presentation page is created, the default viewing transformation is set
to identity. For example, if the presentation-page contents are scrolled:
Erase the screen contents.
Call GpiSetDefaultViewMatrix to translate the presentation-page picture
by the required amount.
Draw the picture again.
The following figure shows the airplane presentation-page contents scrolled to
the left.
Scrolling the Presentation Page
Every presentation-page coordinate is translated to the left by the same
amount.
Zooming is implemented in the same way, except that the default viewing
transformation is used to scale the picture up or down as required.
If you want to display only one view of a single picture, and if you do not
want scrolling and zooming capabilities, you can let the viewing and default
viewing transformations default. When both transformations are permitted to
default, page coordinate space is effectively the same as model space.
ΓòÉΓòÉΓòÉ 2.4.7. Page-Space to Device-Space Transformations ΓòÉΓòÉΓòÉ
There is only one transformation between the page coordinate space and the
device space, the device transformation. The device transformation enables
applications to work in any presentation-page units regardless of the target
device. Unlike the transformations previously described, the device
transformation only scales and translates objects, and it is defined by two
rectangles.
The first rectangle is called the presentation page. Its location is the bottom
left origin and its dimensions are fixed. The second is called the page
viewport. Its location is the bottom left origin and its dimensions can be
varied.
The device transformation, which maps the picture in presentation-page space to
device space, happens automatically. The device transformation is established
when the presentation space is created, and ensures that graphics are displayed
in the correct size and, where possible, that their aspect ratio is preserved.
To modify the device transformation, applications use GpiSetPageViewport. Input
for this function is the device coordinates of the lower-left and upper-right
corners of the page viewport. Applications should modify the default device
transformation only when it is necessary to use nonstandard page units.
ΓòÉΓòÉΓòÉ 2.4.7.1. Presentation Pages ΓòÉΓòÉΓòÉ
A presentation page is a rectangle in a page space. Its lower-left corner is
always positioned at the origin of the page space.
An application can determine the dimensions of the presentation page by calling
GpiQueryPS. It returns a pointer to a SIZEL structure that contains the page
dimensions. If an application specifies arbitrary page units when creating a
presentation space with GpiCreatePS, the page viewport is constructed such that
the origin of the page rectangle maps to the origin of the default device
rectangle and either the right or top edge maps to the corresponding edge.
Thus, the aspect ratio of the graphic is preserved.
If either the height or width of the presentation page is set to 0 (using
GpiCreatePS), the application must set GPIA_ASSOC to set the default
presentation page size to the default device rectangle size.
ΓòÉΓòÉΓòÉ 2.4.7.2. Page Viewports ΓòÉΓòÉΓòÉ
A page viewport is a rectangle in device space, whose origin and size can be
varied. The operating system uses the presentation-page rectangle and the
page-viewport rectangle to define the device transformation.
An application can determine the current dimensions of the page viewport by
calling GpiQueryPageViewport, which returns a pointer to a RECTL structure that
contains the coordinates of the viewport. The application can set the location
and dimensions of the page viewport by calling GpiSetPageViewport and passing
it a pointer to a RECTL structure that contains the new values.
The ratio of the page width to the page-viewport width defines a horizontal
scaling factor. The ratio of the page height to the viewport height defines a
vertical scaling factor. Applications can use DevQueryCaps to obtain the
horizontal and vertical resolution of a device in pels per meter. The
dimensions of a pel can vary from one device to another, but they usually fall
in the range of 0.25 to 0.50 mm.
The page viewport can be shifted in the device space by a translation
transformation.
ΓòÉΓòÉΓòÉ 2.4.7.3. Mapping the Presentation Page to the Device ΓòÉΓòÉΓòÉ
When an application associates a presentation space with a device context, a
default device transformation is set. A page viewport is defined according to
the rules in the following table:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéPresentation-page ΓöéPage viewport size ΓöéUsage. Γöé
Γöéspecification Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPels ΓöéThe same size as theΓöéThe lower-left corner Γöé
Γöé Γöépresentation page. Γöéof the presentation Γöé
Γöé Γöé Γöépage maps to the Γöé
Γöé Γöé Γöélower-left corner of Γöé
Γöé Γöé Γöéthe device space. For Γöé
Γöé Γöé Γöéexample, if an Γöé
Γöé Γöé Γöéapplication defines a Γöé
Γöé Γöé Γöépresentation page of Γöé
Γöé Γöé Γöé300 coordinates Γöé
Γöé Γöé Γöé(x-axis)-by-200 Γöé
Γöé Γöé Γöécoordinates (y-axis), Γöé
Γöé Γöé Γöéthen the picture is Γöé
Γöé Γöé Γöétransformed to a Γöé
Γöé Γöé Γöéscreen area of the Γöé
Γöé Γöé Γöésame size. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMetric units ΓöéThe coordinates thatΓöéThe lower-left corner Γöé
Γöé Γöéproduce the correct Γöéof the presentation Γöé
Γöé Γöématrix for the Γöépage maps to the Γöé
Γöé Γöéphysical spacing of Γöélower-left corner of Γöé
Γöé Γöéthe pels. Γöéthe device space. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéArbitrary units ΓöéThe default size forΓöéThe page viewport is Γöé
Γöé Γöéthe device is used. Γöéconstructed such that Γöé
Γöé ΓöéFor a plotter or Γöéthe presentation-page Γöé
Γöé Γöéprinter, this is theΓöécoordinates give equalΓöé
Γöé Γöémaximum accessible Γöéx- and y-spacing. The Γöé
Γöé Γöéarea of the paper, Γöélower-left corner of Γöé
Γöé Γöéand for a screen, itΓöéthe presentation page Γöé
Γöé Γöéis the maximized Γöémaps to the lower-leftΓöé
Γöé Γöéwindow size. Γöécorner of the device Γöé
Γöé Γöé Γöéspace, and either the Γöé
Γöé Γöé Γöéright or the top edgesΓöé
Γöé Γöé Γöémap, such that the Γöé
Γöé Γöé Γöépicture is contained Γöé
Γöé Γöé Γöéwithin the device Γöé
Γöé Γöé Γöérectangle and its Γöé
Γöé Γöé Γöéaspect ratio is Γöé
Γöé Γöé Γöépreserved. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The following figure shows mapping from the presentation page to the device.
The device transformation can be explicitly specified using GpiSetPageViewport.
Mapping a Picture from the Presentation Page to the Device
In this example, a map of the world has been drawn in a presentation page,
defined in arbitrary units, that is much larger than the device space. The
device transformation scales the picture to fit the maximized window size and
preserves its aspect ratio.
ΓòÉΓòÉΓòÉ 2.4.7.4. Coding the Device Transformation ΓòÉΓòÉΓòÉ
The PM automatically transforms the presentation-page contents to the area of
the device space within the page viewport. The drawing is not clipped to the
page viewport because this is a scaling transformation only. The entire picture
is displayed, regardless of the size of the page viewport specified. The
following figure shows the airplane presentation-page contents scaled to fit
the page viewport.
Device Space
A page viewport smaller than the presentation page has been defined. The
picture assembled in the presentation page is therefore scaled to fit the page
viewport.
After transformation to device space, graphics coordinates must be in the range
-32768 through +32767, even if the presentation page is defined in GPIF_LONG
format. An attempt to address a coordinate outside this range results in a
coordinate-overflow error. To determine if a graphics object will give an
error, applications can do the following:
If the application is not rotating or shearing a graphics object, it
calls GpiConvert to convert the device-space limits to
world-coordinate-space limits, then uses these limits when creating the
graphics object.
If the application is rotating or shearing a graphics object, it uses
GpiConvert to convert the device-space limits back to model space, and
ensures that the picture boundary is inside these limits. Note that this
method only applies if all rotational and shearing is performed using 1
of the model transformation types.
Remember that world-coordinate space has its own own limits:
-32768 through +32767 for a GPIF_SHORT-format presentation page
-134217728 through +134217727 for a GPIF_LONG-format presentation page.
Although applications can specify a page viewport of any size, the
presentation page can be mapped only to an area equal to, or less than, the
available device space. If an application specifies a viewport larger than the
available device space, part of the presentation page contents are displayed
outside the visible device output area. To find out the dimensions of the page
viewport for the currently associated device, use GpiQueryPageViewport.
Applications can store the dimensions of the current page viewport before
changing them, and restore them later.
ΓòÉΓòÉΓòÉ 2.4.7.5. Device-Transformation Matrix ΓòÉΓòÉΓòÉ
To directly manipulate the device-transformation matrix it is necessary for
applications to know the following values:
X1 the x-coordinate of the lower-left corner of the page viewport
Y1 the y-coordinate of the lower-left corner of the page viewport
X2 the x-coordinate of the upper-right corner of the page viewport
Y2 the y-coordinate of the upper-right corner of the page viewport
XPS the presentation-space width -1
YPS the presentation-space height -1.
The device-transformation matrix is defined as:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé The device-transformation matrix: Γöé where: Γöé
Γöé Γöî ΓöÉ Γöé Γöé
Γöé Γöé Msub11 0 0 Γöé Γöé a = (Xsub2-Xsub1)/(Xps+1) Γöé
Γöé Γöé 0 Msub22 0 Γöé Γöé Γöé
Γöé Γöé Msub31 Msub32 1 Γöé Γöé b = (Ysub2-Ysub1)/(Yps+1) Γöé
Γöé Γöö Γöÿ Γöé Γöé
Γöé Γöé c = Xsub1+(a-1)/2 Γöé
Γöé Γöé Γöé
Γöé Γöé d = Ysub1+(b-1)/2 Γöé
Γöé Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 2.4.8. Windowing-System Transformation ΓòÉΓòÉΓòÉ
There is one transformation, the windowing-system transformation, performed
automatically by the PM. The windowing-system transformation, which is a
translation transformation only, maps the coordinates of the picture in device
space to the coordinates of the screen window or printer page. This happens
when a picture is first drawn and whenever the display window in which the
picture has been drawn is moved.
ΓòÉΓòÉΓòÉ 2.4.9. Transforming Bit-Map Data ΓòÉΓòÉΓòÉ
In general, graphics defined in device coordinates (bit maps and image
primitives) cannot be transformed. For example, the size of an image primitive
is specified in device coordinates, and cannot be altered. The size, therefore,
remains unaltered down the viewing pipeline. The position of an image
primitive, however, is specified in world coordinates. The image is therefore
subject to translation transformations. Note, however, that GpiWCBitBlt permits
the target rectangle to be specified in world coordinates, which are
transformed.
Because the position of the image primitive is specified in world coordinates
and its width is specified in device coordinates, positioning two images
together on the screen causes special difficulties. The second image cannot be
positioned without knowing the width, in world coordinates, of the first image.
To get the width of the first image:
1. Identify two coordinate positions, one on the image's left edge, and one
on its right edge. For example, the two positions could be (10,80) and
(150,80). These positions are in device coordinates.
2. Convert these device coordinates to world coordinates using GpiConvert.
GpiConvert converts an array of (x,y) coordinates that apply in one
coordinate space to their corresponding values in another coordinate
space.
3. Subtract the lower x-coordinate from the higher x-coordinate. In the
above example, the width of the image is the difference between the
world-coordinate equivalents of 150 and 10.
When you have the width of the first image in world coordinates, you can
calculate the start position of the second image.
Paths, although defined in world coordinates, are device-dependent and are
bound in device coordinates when they are defined. Subsequent transformations
(other than the windowing-system transformation) have no effect on paths.
However, if a path is used to create a wide line, the width of the line is
scaled as required.
ΓòÉΓòÉΓòÉ 2.5. Using Coordinate Spaces and Transformations ΓòÉΓòÉΓòÉ
This section explains how to:
Set an application's drawing units to convenient units
Translate, rotate, and scale a picture
Shear a picture
ΓòÉΓòÉΓòÉ 2.5.1. Setting Drawing Units ΓòÉΓòÉΓòÉ
Applications can use GpiCreatePS to set the device transformation so that it
uses page units that might be more convenient than pels; for example,
centimeters. If the output device is a screen, the application first opens a
device context by calling WinOpenWindowDC. If the output device is a printer or
plotter, the application opens a printer or plotter device context by calling
DevOpenDC. The application then creates a presentation space by calling
GpiCreatePS, specifying low-metric page units and associating the device
context with the presentation space. The following figure is an example of how
to set drawing units.
HWND hwnd; /* Client-window handle */
HAB hab; /* Anchor-block handle */
HPS hps; /* Presentation-space handle */
HDC hdc; /* Device-context handle */
SIZEL sizlPage; /* Presentation-page rectangle */
hdc = WinOpenWindowDC(hwnd);
sizlPage.cx = 0;
sizlPage.cy = 0;
hps = GpiCreatePS(hab, /* Anchor-block handle */
hdc, /* Device-context handle */
&sizlPage, /* Address of SIZEL structure */
PU_LOMETRIC /* Centimeters as page units */
| GPIA_ASSOC); /* Associates window DC with PS */
ΓòÉΓòÉΓòÉ 2.5.2. Translating, Rotating, and Scaling a Picture ΓòÉΓòÉΓòÉ
GpiTranslate, GpiRotate, and GpiScale provide a convenient method for
transforming objects in a picture. The following figure shows how to use these
functions to translate, rotate, and scale a triangle.
MATRIXLF matlfTransform;
POINTL ptlStart, ptlTrans, ptlRotate, ptlScale;
FIXED fxAngle, afxScale[2];
POINTL aptlTriangle[] = { 575, 300, 575, 500, 500, 300 };
ptlStart.x = 500; /* Starting point x direction */
ptlStart.y = 300; /* Starting point y direction */
GpiMove(hps, &ptlStart);
GpiPolyLine(hps, sizeof(aptlTriangle) / sizeof(POINTL), aptlTriangle);
ptlTrans.x = 75; /* x coordinate for translation */
ptlTrans.y = 75; /* y coordinate for translation */
GpiTranslate(hps, /* Presentation-space handle */
&matlfTransform, /* Address of matrix */
TRANSFORM_REPLACE, /* Replace old matrix with new */
&ptlTrans); /* Coordinates for translation */
GpiSetModelTransformMatrix(hps, /* Presentation-space handle */
9, /* Number of points in matrix */
&matlfTransform, /* Address of matrix */
TRANSFORM_REPLACE); /* Replace old matrix with new */
GpiMove(hps, &ptlStart); /* Move to starting point */
GpiPolyLine(hps, sizeof(aptlTriangle) / sizeof(POINTL), aptlTriangle);
fxAngle = MAKEFIXED(-45, 0); /* Rotate 45 degrees clockwise */
ptlRotate.x = 550; /* x coordinate rotation origin */
ptlRotate.y = 350; /* y coordinate rotation origin */
GpiRotate(hps, /* Presentation-space handle */
&matlfTransform, /* Address of matrix */
TRANSFORM_REPLACE, /* Replace old matrix with new */
fxAngle, /* Rotation angle */
&ptlRotate); /* Origin of rotation */
GpiSetModelTransformMatrix(hps, 9, &matlfTransform, TRANSFORM_REPLACE);
GpiMove(hps, &ptlStart); /* Move to starting point */
GpiPolyLine(hps, sizeof(aptlTriangle) / sizeof(POINTL), aptlTriangle);
ptlScale.x = 550; /* x coordinate scale origin */
ptlScale.y = 350; /* y coordinate scale origin */
afxScale[0] = MAKEFIXED(2, 0); /* Scaling factor on x axis */
afxScale[1] = MAKEFIXED(2, 0); /* Scaling factor on y axis */
GpiScale(hps, /* Presentation-space handle */
&matlfTransform, /* Address of matrix */
TRANSFORM_REPLACE, /* Replace old matrix with new */
&afxScale[0], /* Scaling factor */
&ptlScale); /* Origin of scaling operation */
GpiSetModelTransformMatrix(hps, 9, &matlfTransform, TRANSFORM_REPLACE);
GpiMove(hps, &ptlStart); /* Move to starting point */
GpiPolyLine(hps, sizeof(aptlTriangle) / sizeof(POINTL), aptlTriangle);
ΓòÉΓòÉΓòÉ 2.5.3. Shearing a Picture ΓòÉΓòÉΓòÉ
The following figure is an example of shearing a picture by modifying the
transformation matrix directly.
MATRIXLF matlfTransform;
POINTL ptlStart, ptlEnd;
ptlStart.x = 500; /* x coordinate, lower-left corner of box */
ptlStart.y = 300; /* y coordinate, lower-left corner of box */
GpiMove(hps, &ptlStart);
ptlEnd.x = 700; ; /* x coordinate, upper-right corner of box */
ptlEnd.y = 500; ; /* y coordinate, upper-right corner of box */
GpiBox(hps, DRO_OUTLINE, &ptlEnd, 0, 0); /* Draw first box */
matlfTransform.fxM11 = MAKEFIXED(1, 0);
matlfTransform.fxM12 = MAKEFIXED(0, 0);
matlfTransform.lM13 = 0;
matlfTransform.fxM21 = MAKEFIXED(0, 65536 / 2); /* Shear factor .5 */
matlfTransform.fxM22 = MAKEFIXED(1, 0);
matlfTransform.lM23 = 0;
matlfTransform.lM31 = 200; /* Translate 200 units right */
matlfTransform.lM32 = 0;
matlfTransform.lM33 = 1;
GpiSetDefaultViewMatrix(hps, 9, &matlfTransform, TRANSFORM_REPLACE);
GpiMove(hps, &ptlStart);
GpiBox(hps, DRO_OUTLINE, &ptlEnd, 0, 0); /* Draw sheared box */
ΓòÉΓòÉΓòÉ 2.5.4. Using World to Model Space Transformations ΓòÉΓòÉΓòÉ
The following is an example of a sequence of calls in which segment, model, and
instance transformations are applied to graphics objects.
GpiSetDrawingMode (DM_RETAIN) /* Sets the current drawing mode */
/* to DM_RETAIN */
GpiOpenSegment (segment 1) /* Creates a chained segment */
GpiCloseSegment
GpiSetSegmentAttrs /* Make segment 1 an unchained segment */
GpiOpenSegment (segment 2) /* Creates a retained, chained segment */
GpiSetModelTransformMatrix (TRANSFORM_ADD)
/* Specifies a transformation to */
/* apply to subsequent primitives. */
/* This is in addition to the current */
/* model transformation. */
GpiCallSegmentMatrix (1, TRANSFORM_ADD)
/* Calls segment 1 and applies a */
/* transformation to it. */
/* This transformation is in addition */
/* to the current model transformation, */
/* and applies only to the called */
/* segment. */
.
.
GpiSetCurrentArcParams
GpiPointArc /* The 3-point arc is not subject */
/* to the transformation specified */
/* on the call to GpiCallSegmentMatrix. */
/* The transformation that was */
/* current before segment 1 was called */
/* is applied to the remainder of */
/* segment 2. */
GpiCloseSegment
GpiSetSegmentTransformMatrix (segment 2)
/* Specifies a segment transformation */
/* for segment 2 */
GpiDrawSegment /* Draws segment 2 */
ΓòÉΓòÉΓòÉ 2.5.5. Viewing Transformation ΓòÉΓòÉΓòÉ
Each time an application draws the model space, it specifies a different
viewing transformation to transfer a view of the picture-to-page coordinate
space. GpiSetViewingTransformMatrix is used to apply a viewing transformation.
There is one viewing transformation for each part or whole model space to be
incorporated in page-coordinate space.
GpiSetViewingTransformMatrix cannot be called while there is an open segment,
and it has no effect on primitives outside segments. When it has been
specified, the viewing transformation applies to all subsequently created
segments until it is next changed. The viewing transformation that is current
when a segment is created is a fixed part of the segment. Once specified, the
viewing transformation cannot be queried, nor can it be altered, unless you
re-create the segment. This is inconvenient when several versions of the same
picture are being drawn. The problem can be solved by:
Defining the picture in one or more unchained segments.
Creating a segment chain and calling the unchained segments from each
root segment.
Setting the viewing transformation before each root segment.
Each time the segment chain is drawn, multiple views of the same picture are
produced. This sequence is illustrated in the following example, where the
segment chain comprises three root segments, each of which calls a single
unchained segment.
GpiSetInitialSegmentAttrs /* Switches off the chained attribute */
GpiOpenSegment /* Creates an unchained segment */
/* containing the picture definition */
GpiCloseSegment
GpiSetInitialSegmentAttrs /* Switches on the chained attribute */
GpiSetViewingTransformMatrix /* Sets the viewing transformation */
/* for segment 1 */
GpiOpenSegment (segment 1)
GpiCallSegmentMatrix /* Calls the unchained segment */
GpiCloseSegment
GpiSetViewingTransformMatrix /* Sets the viewing transformation */
/* for segment 2 */
GpiOpenSegment (segment 2)
GpiSetViewingLimits /* Specifies the area of interest */
/* in the model space. */
GpiCallSegmentMatrix /* Calls the unchained segment */
GpiCloseSegment
GpiSetViewingTransformMatrix /* Sets the viewing transformation */
/* for segment 3 */
GpiOpenSegment (segment 3)
GpiCallSegmentMatrix /* Calls the unchained segment */
GpiCloseSegment
When a segment chain has been created using this method, an application cannot
change the viewing transformation unless it re-creates the segment chain. The
viewing transformation of a segment is permanently recorded and cannot be
edited. The application would not, however, have to re-create the picture
definition in the unchained segment.
If the picture definition comprises a number of unchained segments, an
application must create an intermediate segment to contain the
GpiCallSegmentMatrix calls for those segments. Each root segment would then
call the intermediate segment.
The viewing transformation applies to the entire root segment and cannot be
overridden from within the segment. It is particularly useful for positioning
and scaling one or more segments of a subpicture within the presentation page
when a segment transformation cannot be used. A segment transformation can be
overridden by any model or instance transformations within the segment. A
typical example of its use is when importing a subpicture using GpiPutData or
GpiPlayMetaFile.
Note: The viewing transformation must be set to its default value before an
application defines an unchained segment to be called from another segment.
ΓòÉΓòÉΓòÉ 3. Editing Retained Graphics and Graphics Segments ΓòÉΓòÉΓòÉ
This chapter describes editing retained graphics and graphics segments. The
following topics are related to the information in this chapter:
Presentation spaces and device contexts
Coordinate spaces and transformations
Creating and drawing retained graphics
ΓòÉΓòÉΓòÉ 3.1. About Editing Retained Graphics and Graphics Segments ΓòÉΓòÉΓòÉ
In the OS/2 operating system, applications store retained graphics in segments.
One of the advantages of using graphics segments is that segments can be
edited, which allows the retained image to be modified without having to
re-create the unmodified portion with multiple GPI functions.
Creating and Drawing Retained Graphics described how to create a segment, and
store GPI functions within the segment bracket (the GPI functions bracketed by
GpiOpenSegment and GpiCloseSegment). To understand how to edit a segment, the
underlying structure of a segment is described here in greater detail.
The GPI functions are not inserted directly into a segment bracket. Instead,
the operating system converts the GPI functions into graphics orders. A
graphics order, also known as a drawing order, is the smallest complete portion
of a segment. Once the GPI functions are converted into graphics orders, these
orders are stored in the GpiOpenSegment-GpiCloseSegment bracket.
Generally, each of the GPI functions within the segment bracket generates one
element of the segment. An element is the smallest portion of a segment that
can be edited and is made up of one or more orders. The following figure
illustrates the levels of graphic segment construction.
GpiOpenSegment (...); Graphic Segment
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ element
GpiLine (...); Γöé line order Γöé element 0 pointer
Γöé Γöé
GpiBeginElement (...); Γöé begin element order Γöé element 1
Γöé Γöé
GpiBox (...); Γöé box order Γöé
GpiPolyline (...); Γöé polyline order Γöé
Γöé Γöé
GpiEndElement (...); Γöé end element order Γöé
Γöé Γöé
GpiLabel (...); Γöé label order Γöé element 2
Γöé Γöé
GpiSetColor (...); Γöé set-color order Γöé element 3
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
GpiCloseSegment (...);
Structure of a Graphics Segment
Elements 0, 2, and 3 are each composed of a single order. Element 1 is composed
of two orders bracketed by GpiBeginElement and GpiEndElement.
ΓòÉΓòÉΓòÉ 3.1.1. Graphics Orders ΓòÉΓòÉΓòÉ
A graphics order is a low-level graphics command that corresponds to a
primitive function or attribute. In addition to code and data requirements,
each graphics order uses approximately 11 bytes of storage. An application that
uses 2000 graphics drawing orders will use around 22KB of memory to store them.
The following table describes the four sizes of graphics orders.
Graphics Orders
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéGraphics Order Size ΓöéContent Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé1 byte ΓöéA hexadecimal identifier Γöé
Γöé Γöécorresponding to a drawing function Γöé
Γöé Γöéor attribute function. This Γöé
Γöé Γöéidentifier is also known as the Γöé
Γöé Γöéorder code. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé2 byte ΓöéThe order code is in the first byte,Γöé
Γöé Γöéand data is in the second byte. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLong ΓöéThe order code is in the first byte.Γöé
Γöé Γöé Γöé
Γöé ΓöéThe length value of the actual data,Γöé
Γöé Γöéin bytes, is in the second byte. Γöé
Γöé Γöé Γöé
Γöé ΓöéThe actual data (up to 255 bytes). Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéVery long ΓöéA hexadecimal identifier Γöé
Γöé(maximum length of 64KB)Γöéspecifically for extended orders, isΓöé
Γöé Γöéin the first byte. Γöé
Γöé Γöé Γöé
Γöé ΓöéThe order code is in the second Γöé
Γöé Γöébyte. Γöé
Γöé Γöé Γöé
Γöé ΓöéA length value that specifies how Γöé
Γöé Γöémany bytes are used by the Γöé
Γöé Γöégraphics-order arguments, (high Γöé
Γöé Γöéorder) is in the third byte. Γöé
Γöé Γöé Γöé
Γöé ΓöéA length value that specifies how Γöé
Γöé Γöémany bytes are used by the Γöé
Γöé Γöégraphics-order arguments, (low Γöé
Γöé Γöéorder) is in the fourth byte. Γöé
Γöé Γöé Γöé
Γöé ΓöéThe actual data. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The following example shows a long graphics order that corresponds to GpiLine:
81 8 100 0 0 0 100 0 0 0
The first number, 81, is the hexadecimal identifier that corresponds to
GpiLine. The second number, 8, is the length value that specifies how many
bytes are used by the graphics-order arguments. The next eight bytes contain
the arguments for GpiLine. In this case, the arguments specify the line's end
point at (100,100).
Graphics
Segment
Γöé
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇ 0x21 Γö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ order # ΓöÇΓöÇΓöÉ
Γöé Γöé Γöé 0x08 Γö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ length Γöé
Γöé ptl.x = 100L; Γöé Γöé 0x00 Γöé ΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
Γöé ptl.y = 100L; Γöé Γöé 0x00 Γöé Γö£ΓöÇΓöÇ x Γöé
Γöé GpiMove (hps, &ptl); Γö╝ΓöÇΓöÇΓöÿ 0x10 Γöé Γöé Γö£ΓöÇΓöÇ element
Γöé ptl.x = 200L; Γöé 0x00 Γöé ΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé
Γöé ptl.y = 400L; Γöé 0x00 Γöé ΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
Γöé GpiMove (hps, &ptl); Γö╝ΓöÇΓöÇΓöÉ 0x00 Γöé Γö£ΓöÇΓöÇ y Γöé
Γöé Γöé Γöé 0x20 Γöé Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé 0x00 Γöé ΓöÇΓöÇΓöÇΓöÇΓöÿ ΓöÇΓöÇΓöÿ
ΓööΓöÇΓöÇ 0x81 Γö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ order # ΓöÇΓöÇΓöÉ
0x08 Γö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ length Γöé
0x00 Γöé ΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
0x00 Γöé Γö£ΓöÇΓöÇ x Γöé
0x30 Γöé Γöé Γö£ΓöÇΓöÇ element
0x00 Γöé ΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé
0x00 Γöé ΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
0x00 Γöé Γö£ΓöÇΓöÇ y Γöé
0x40 Γöé Γöé Γöé
0x00 Γöé ΓöÇΓöÇΓöÇΓöÇΓöÿ ΓöÇΓöÇΓöÿ
Γöé
Graphics Orders
The encoding that appears in the Graphics Segments column is a hexadecimal
version of the order, length, and parameter information.
In most cases, graphics orders in a segment correspond to a subpicture, which
is part of a complete, more complex picture. Your application would combine the
individual segments to form the complete picture.
Three drawing modes affect how the operating system stores graphics orders in
segments. These modes are described in the following table. The default drawing
mode is draw (DM_DRAW). To specify another as the current drawing mode, use
GpiSetDrawingMode.
The actual drawing mode is a combination of the drawing mode as set using
GpiSetDrawingMode, and the segment status-chained, unchained, or outside of the
segment. The actual drawing mode does not affect the storing of orders in
segments.
Segment Graphics Drawing Modes
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDrawing Mode ΓöéGpiSetDrawingMode ΓöéWhen this mode is set...Γöé
Γöé ΓöéValue Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw ΓöéDM_DRAW Γöéit is not possible to Γöé
Γöé Γöé Γöéstore graphics orders inΓöé
Γöé Γöé Γöéa chained segment. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRetain ΓöéDM_RETAIN Γöéyour application can Γöé
Γöé Γöé Γöéstore graphics orders inΓöé
Γöé Γöé Γöéchained and unchained Γöé
Γöé Γöé Γöésegments. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw-and-retain ΓöéDM_DRAWANDRETAIN Γöéyour application can Γöé
Γöé Γöé Γöéstore graphics orders inΓöé
Γöé Γöé Γöéchained and unchained Γöé
Γöé Γöé Γöésegments. In this mode,Γöé
Γöé Γöé Γöéoutput intended for a Γöé
Γöé Γöé Γöéchained segment is both Γöé
Γöé Γöé Γöédrawn on the device and Γöé
Γöé Γöé Γöéstored in a segment. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 3.1.2. Graphics Elements ΓòÉΓòÉΓòÉ
Graphics elements are composed of either a single graphics order, or a series
of graphic orders that are bracketed by an opening and closing element
function.
The purpose of this element bracket is to allow the addition of a single
element, that comprises more than one graphics order, to a segment. This is
most useful when you know that you will want to retrieve those orders at a
later time, and manipulate them as a group rather than as individual functions.
Note: There is no reason for enclosing a single GPI function within a
GpiBeginElement-GpiEndElement bracket, although it is a valid construction.
Element brackets also are valid when drawing graphics directly to the output
device, but again, they serve no purpose unless converted to a retained segment
at a later time. Elements cannot be nested, so two elements cannot begin in
succession without an intervening GpiEndElement request. Certain GPI functions
cannot be called between GpiBeginElement and GpiEndElement. For example,
GpiLabel cannot be used between GpiBeginElement and GpiEndElement.
Element construction is valid only within segments.
ΓòÉΓòÉΓòÉ 3.1.2.1. Adding Elements to a New Segment ΓòÉΓòÉΓòÉ
There are four ways of adding elements to a newly created segment:
Call one or more GPI functions. Each function generates one element of
the segment. This is the simplest way of supplying graphics data to a
segment.
Call GpiBeginElement, and follow it with one or more GPI functions. Close
the element using GpiEndElement. All the GPI functions enclosed within
the bracket and GpiBeginElement and GpiEndElement generate a single
element of the segment, and therefore occupy a single-element-pointer
position. Subsequently, the graphics orders cannot be accessed
individually with the element pointer, although the orders can be
accessed directly, for example, using GpiGetData.
Call GpiElement. As input, you supply the graphics orders themselves,
rather than the GPI functions that generate them. No matter how much data
you supply on this request, it is considered a single element of the
segment.
Multiple orders added to a segment in this way cannot be accessed
individually using the element pointer, but they can be accessed
directly, for example, using GpiGetData.
GpiElement cannot be included within a GpiBeginElement-GpiEndElement
bracket. The data passed by GpiElement must not include GpiBeginElement
and GpiEndElement.
Call GpiPutData. As with GpiElement, supply graphics orders as input. You
can even include GpiBeginElement and GpiEndElement orders in this data,
and thus add more than one element to the segment. GpiPutData is useful
when there is a large amount of data to add to a segment.
GpiPutData cannot be used if the segment editing mode is set to
SEGEM_REPLACE. When the segment editing mode is SEGEM_INSERT, the element
pointer must point to the last element in the current segment. The
segment editing mode can be set by using GpiSetEditMode..
GpiPutData is most often used in conjunction with GpiGetData, which
copies data as a list of drawing orders from a segment to application
storage.
ΓòÉΓòÉΓòÉ 3.1.2.2. Element Types ΓòÉΓòÉΓòÉ
Each element that results from a single GPI function has an associated element
type.
The element type is generally the graphics-order code associated with the
graphics order generated by the GPI function, and is supplied by the system.
For example, GpiLine has the element type, OCODE_GCLINE, which identifies it as
a line-drawing request. Your application can determine the current
classification of an element using GpiQueryElementType.
When using GpiElement or GpiBeginElement, you can simultaneously add several
graphics orders to a segment. Those orders become one element of the segment.
You can supply your own classification for these compound elements by supplying
a value for the type parameter of GpiElement or GpiBeginElement in the range of
0x81000000 through 0XFFFFFFFF.
For example, the orders passed by a single GpiElement function could change the
line type to dotted, set the current color to blue, and draw a line. You could
classify this element with a type value that identifies it as a blue dotted
line.
Note: Element types are used only for classification. They are not used as
location markers or correlation tags.
ΓòÉΓòÉΓòÉ 3.1.2.3. Element Pointer ΓòÉΓòÉΓòÉ
Use the element pointer to change the contents of an existing segment. When
calling GpiOpenSegment, the element pointer is set to 0. The first element that
you add to a newly created segment causes the pointer to be set to 1, and each
subsequent element causes the pointer to be incremented by 1. When a segment is
closed, the element pointer is always reset to 0.
Your application can move the element pointer to a specified value using
GpiSetElementPointer. For example, to address the sixth element in a segment,
set the element pointer to 6.
Your application also can move the element pointer by a specific number, rather
than to a specific number, using GpiOffsetElementPointer. For example, if the
element pointer currently addresses element 3, to move it to element 8, code an
offset of 5 in GpiOffsetElementPointer. The pointer moves backward rather than
forward through the segment. The offset value can be a positive or negative
number.
If the sum of the offset and the current pointer position is less than 0, the
operating system sets the pointer so that it points to position 0. Position 0
precedes the first element in the segment. If the sum of the offset and the
current pointer position is greater than the number of elements in the segment,
the operating system sets the pointer so that it points to the last element in
the segment.
You can determine the current location of the element pointer using
GpiQueryElementPointer. To request the contents of a part of or all of the
elements at the current pointer position, use GpiQueryElement.
ΓòÉΓòÉΓòÉ 3.1.2.4. Labels ΓòÉΓòÉΓòÉ
You can include labels in a segment to make locating particular elements of the
segment easier. If you label an element that is likely to be edited, you can
access that element when necessary, regardless of whether the actual position
of the label-element pair within the segment has changed.
Warning: When editing segments, do not inadvertently insert elements between a
label and the element that follows. Your application will no longer be able to
use certain GPIs correctly because their default locations and offsets will be
invalid.
A label is only a place-holder or reference point, and is itself an element of
the segment. Labels are long integer values. To include a label in a segment,
use GpiLabel. The following example includes the label 5 in the current
segment, whose segment id is 4.
GpiOpenSegment(hps, 4L);
GpiLabel(hps, 5L);
.
.
.
Your application can set the element pointer to the label position using
GpiSetElementPointerAtLabel, then increment the pointer position to the element
itself using GpiOffsetElementPointer with an offset of 1.
Note: This example of GPI cannot work properly if your application has allowed
the insertion of elements between a label and the element that follows it.
Labels do not have to be unique. If you do not use unique labels,
GpiSetElementPointerAtLabel positions the element pointer at the first
occurrence of the label, starting from the current pointer position. If the
label is not found between the current pointer position and the end of the
segment, an error condition is raised. Using labels as a navigation aid might
be quicker than scanning the segment for a particular element.
If you do not use labels, you must locate an element before you can change it.
To locate a specific element in a segment, you must repeatedly move the element
pointer using GpiSetElementPointer then read the contents of the element using
GpiQueryElement. This can be quite a lengthy procedure depending upon the
number of elements in the segment.
ΓòÉΓòÉΓòÉ 3.1.3. Graphics Segments ΓòÉΓòÉΓòÉ
Segments are made up of elements, which are in turn made up of one or more
graphic orders. The previous sections have discussed the properties and
functions for orders and elements. The following sections discuss the
attributes and functions that apply to segments as a whole.
The segment attributes are encoded in a segment prior to the graphics orders
that correspond to GPIs and attributes.
ΓòÉΓòÉΓòÉ 3.1.3.1. Segment Attributes ΓòÉΓòÉΓòÉ
Each segment has a number of characteristics, called attributes that you can
set in accordance with your application's requirements. The attributes of a
segment are quite different from those of a graphics primitive, in that segment
attributes have ON and OFF settings. There are seven segment attributes, each
described in the following table.
Graphic Segment Attributes and Initial Settings
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute ΓöéValue ΓöéIf set... ΓöéDefault Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéChained ΓöéATTR_CHAINED Γöéthe operating ΓöéON Γöé
Γöé Γöé Γöésystem adds Γöé Γöé
Γöé Γöé Γöéeach new Γöé Γöé
Γöé Γöé Γöésegment in Γöé Γöé
Γöé Γöé Γöéyour Γöé Γöé
Γöé Γöé Γöéapplication's Γöé Γöé
Γöé Γöé Γöépresentation Γöé Γöé
Γöé Γöé Γöéspace to the Γöé Γöé
Γöé Γöé Γöésegment chain.Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFast chain ΓöéATTR_FASTCHAIN Γöéthe operating ΓöéON Γöé
Γöé Γöé Γöésystem Γöé Γöé
Γöé Γöé Γöéprevents the Γöé Γöé
Γöé Γöé Γöéresetting of Γöé Γöé
Γöé Γöé Γöéprimitive Γöé Γöé
Γöé Γöé Γöéattributes to Γöé Γöé
Γöé Γöé Γöétheir default Γöé Γöé
Γöé Γöé Γöévalues before Γöé Γöé
Γöé Γöé Γöédrawing the Γöé Γöé
Γöé Γöé Γöésegment chain.Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDynamic ΓöéATTR_DYNAMIC Γöéthe operating ΓöéOFF Γöé
Γöé Γöé Γöésystem draws Γöé Γöé
Γöé Γöé Γöésegment outputΓöé Γöé
Γöé Γöé Γöéby using the Γöé Γöé
Γöé Γöé ΓöéXOR raster Γöé Γöé
Γöé Γöé Γöéoperation. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDetectable ΓöéATTR_DETECTABLE Γöéyour ΓöéOFF Γöé
Γöé Γöé Γöéapplication Γöé Γöé
Γöé Γöé Γöécan perform Γöé Γöé
Γöé Γöé Γöécorrelation Γöé Γöé
Γöé Γöé Γöéoperations on Γöé Γöé
Γöé Γöé Γöésegments Γöé Γöé
Γöé Γöé Γöécreated in Γöé Γöé
Γöé Γöé Γöéthis Γöé Γöé
Γöé Γöé Γöépresentation Γöé Γöé
Γöé Γöé Γöéspace. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPropagate ΓöéATTR_PROP_DETECTABLEΓöéthe detectableΓöéON Γöé
Γöédetectable Γöé Γöéattribute willΓöé Γöé
Γöé Γöé Γöébe set in eachΓöé Γöé
Γöé Γöé Γöésegment calledΓöé Γöé
Γöé Γöé Γöéby a chained Γöé Γöé
Γöé Γöé Γöésegment. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéVisible ΓöéATTR_VISIBLE ΓöéGpiDrawChain, ΓöéON Γöé
Γöé Γöé ΓöéGpiDrawFrom, Γöé Γöé
Γöé Γöé Γöéand Γöé Γöé
Γöé Γöé ΓöéGpiDrawSegmentΓöé Γöé
Γöé Γöé Γöéwill generate Γöé Γöé
Γöé Γöé Γöéoutput on a Γöé Γöé
Γöé Γöé Γöédevice. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPropagate visible ΓöéATTR_PROP_VISIBLE ΓöéThe visible ΓöéON Γöé
Γöé Γöé Γöéattribute willΓöé Γöé
Γöé Γöé Γöébe set in eachΓöé Γöé
Γöé Γöé Γöésegment calledΓöé Γöé
Γöé Γöé Γöéby a chained Γöé Γöé
Γöé Γöé Γöésegment. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
When an application creates a segment in a presentation space, the operating
system assigns initial attributes to it. By default, five of the attributes
will be set ON and two will be set OFF. Your application can override the
defaults for all subsequently created segments within the presentation space
using GpiSetInitialSegmentAttrs.
Use GpiQueryInitialSegmentAttrs, to retrieve the values of the current initial
attributes.
ΓòÉΓòÉΓòÉ 3.1.3.1.1. The Dynamic Attribute ΓòÉΓòÉΓòÉ
Dynamic segments are graphics segments that can be moved from where they were
drawn on the screen to a different coordinate position, or altered in some
other way, without affecting the remaining part of the picture. The new
position of a dynamic segment can be provided with an input device, such as a
mouse, or it can be application-generated.
The dynamic attribute is set to OFF by default. The setting is always inherited
by called segments from the setting of their callers. If a calling segment is
nondynamic, any segments called by it are also nondynamic, regardless of how
they have been defined. If the calling segment is dynamic, all segments called
by it are also dynamic. Any segment explicitly defined as dynamic must have a
unique name, and it cannot be created when the current drawing-mode parameter
is DM_DRAW or DM_DRAWANDRETAIN. Although no error condition is raised if you
define an unchained segment as dynamic, it is not treated as dynamic unless the
segment is called from a dynamic root segment.
Graphics objects to be moved without disturbing the remaining contents of the
display are drawn in exclusive-OR mode. Segments that you define as dynamic
always are drawn in exclusive-OR mode, regardless of the current mix attribute
settings and any GpiSetMix functions the segment itself might contain.
For performance reasons, dynamic segments are to be grouped at the start of the
picture chain. There are GPI functions that handle dynamic segments as a group,
so it is more efficient if the entire segment chain does not have to be scanned
to locate them.
When the entire picture chain is drawn, however, dynamic segments are to be
drawn after all other segments in the chain to ensure that the effects of
drawing in exclusive-OR mode are not adversely affected by drawings in other
mix modes. Also, you must ensure that no nondynamic drawing overlays the
dynamic segments after they have been drawn. The PM ensures that dynamic
segments are always drawn on top of other graphics.
ΓòÉΓòÉΓòÉ 3.1.3.1.2. The Detectability Attribute ΓòÉΓòÉΓòÉ
The detectability attribute of a segment determines if that segment can be
selected with an input device, such as a mouse. A segment with this attribute
is said to be selectable. Selectable segments can be selected for correlation
operations. The detectability attribute is set OFF by default. All detectable
segments must have unique names. If you define a zero segment as detectable, it
is created as nondetectable.
ΓòÉΓòÉΓòÉ 3.1.3.1.3. The Propagate-Detectability Attribute ΓòÉΓòÉΓòÉ
This attribute controls whether the detectability attribute of a calling
segment is inherited by any segments called from it. The
propagate-detectability attribute is set ON by default. This value overrides
the detectability setting of the called segment. For example, if you set the
detectability attribute of a calling segment to OFF, all segments called from
it are nondetectable, regardless of how they have been defined.
ΓòÉΓòÉΓòÉ 3.1.3.1.4. The Visibility Attribute ΓòÉΓòÉΓòÉ
The visibility attribute controls whether a segment is to be visible on an
output device. The contents of a segment that is not defined with the
visibility attribute set ON are still executed whenever the segment is drawn.
This can cause changes to the current position and to current attribute values,
even though the primitives themselves are not visible on the output device. The
visibility attribute is set ON by default.
ΓòÉΓòÉΓòÉ 3.1.3.1.5. The Propagate-Visibility Attribute ΓòÉΓòÉΓòÉ
This attribute controls whether the visibility attribute of a calling segment
is inherited by any segments called from it. The propagate-visibility attribute
is set ON by default. This value overrides the visibility setting of the called
segment. For example, if the visibility attribute of a calling segment is set
to OFF, all segments called from it are invisible, regardless of how they have
been defined.
ΓòÉΓòÉΓòÉ 3.1.4. Changing the Attributes of a Segment ΓòÉΓòÉΓòÉ
After you create a segment, you might need to alter its attributes. For
example, if you created a segment using the default attributes and you want to
perform a correlation operation on the subpicture in that segment, you will
need to set the detectable attribute using GpiSetSegmentAttrs. You can retrieve
the values of the attributes for any segment using GpiQuerySegmentAttrs.
You can change the default segment-attribute settings globally for a single
presentation space using GpiSetInitialSegmentAttrs. The attribute setting that
you specify in this function applies to all segments created subsequently in
that presentation space, except that a nonretained segment can never have the
dynamic attribute. For example, if you want all segments to be detectable, you
can call this function to change the setting for all of them before you create
them. GpiSetInitialSegmentAttrs cannot be used to change the attributes of
existing segments.
You also can change the attributes of any single retained segment, but not
those created subsequently, using GpiSetSegmentAttrs. This is useful if, for
example, you want most of the segments in a picture chain to be detectable. You
can change the attribute setting to detectable for the entire chain, before
creating it, using GpiSetInitialSegmentAttrs; then, change the attribute to
nondetectable for each of the segment exceptions using GpiSetSegmentAttrs. You
can also use GpiSetSegmentAttrs, for example, to make a visible segment
invisible when an erase request is received from the operator, or to take a
segment out of the chain by redefining it as unchained. If you change an
unchained segment to chained, it is added to the end of the segment chain. If
you want the newly chained segment to be positioned elsewhere in the chain, use
GpiSetSegmentPriority rather than GpiSetSegmentAttrs.
Some of these segment attributes apply equally to primitives that are outside
of segments, although their default settings cannot be changed. Primitives
outside of segments are always detectable and visible. They cannot be dynamic,
because the dynamic attribute applies only to retained graphics. The chained
and fast-chaining attributes do not apply to primitives outside of segments.
ΓòÉΓòÉΓòÉ 3.1.5. Editing a Segment ΓòÉΓòÉΓòÉ
The operating system provides segment editing functions for writing
applications that allow users to edit segments or elements in a segment. For
example, after performing a correlation operation using your application, a
user might need to alter the elements that intersected the pick aperture.
Correlation and the pick aperture are explained in in Correlation.
You can edit the contents of any retained segment that has a unique name. You
also can edit the contents of a retained zero segment that has not yet been
closed. Zero segments cannot be edited after they have been closed, because you
cannot refer to a zero segment when it is no longer the current open segment.
Before you can begin editing, you must set the current drawing-mode parameter
to DM_RETAIN. You cannot edit a segment if the current drawing-mode parameter
is DM_DRAWANDRETAIN or DM_DRAW. To begin editing, call GpiOpenSegment and
specify the name of the segment you want to edit. When you are finished editing
a segment, close it using GpiCloseSegment.
The operating system has two edit modes: insert mode and replace mode. You can
set the edit modes using GpiSetEditMode. You can determine which mode is
currently set using GpiQueryEditMode.
The current edit mode applies to all segments in the presentation space until
you change it. The edit mode is not an attribute of a particular segment and
can be changed at any time. The default edit mode, which is set when you create
a presentation space, is insert mode. When you create a graphics segment, you
are actually editing it in insert mode.
If the edit mode is set to insert (SEGEM_INSERT) you can insert an element at
the current location of the element pointer. The operating system shifts the
element that was previously at that location into the next slot, and so on,
until the last element is shifted into a new, final slot. The following figure
shows a segment before and after a new element is inserted at position 0, the
beginning of the segment.
Original Segment New Segment
Element Pointer
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Position 0 Γöé ΓöéΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöé Γöé
Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 1 Γöé Element 1 ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ Γöé New element Γöé
Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 2 Γöé Element 2 ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇΓöé Element 1 Γöé
Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 3 Γöé Element 3 ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé Element 2 Γöé
Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 4 Γöé Element 4 ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé Element 3 Γöé
Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 5 Γöé Element 5 ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé Element 4 Γöé
Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 6 Γöé Element 6 ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé Element 5 Γöé
Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 7 Γöé Element 7 ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé Element 6 Γöé
Γöé Γöé Γöé Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé Element 7 Γöé
Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Inserting a New Element in a Segment
The new element is inserted after the current element; then, the element
pointer is set to the new element.
If replace mode is set (SEGEM_REPLACE) you can replace the element at the
current pointer location with a new element. The following figure shows a
segment before and after the third element was replaced.
Original Segment New Segment
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Position 0 Γöé Γöé Γöé Γöé
Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 1 Γöé Element 1 Γöé Γöé Element 1 Γöé
Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 2 Γöé Element 2 Γöé Γöé Element 2 Γöé
Γöé Γöé Element pointer Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 3 Γöé Element 3 ΓöéΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöé Element 3 Γöé
Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 4 Γöé Element 4 Γöé Γöé Element 4 Γöé
Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 5 Γöé Element 5 Γöé Γöé Element 5 Γöé
Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 6 Γöé Element 6 Γöé Γöé Element 6 Γöé
Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 7 Γöé Element 7 Γöé Γöé Element 7 Γöé
Γöé Γöé Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Replacing an Element with a New Element
The new element overwrites the previous element; the element pointer does not
change.
Replacing elements is the recommended technique for redrawing identical
primitives with different attributes-for example, color.
You can insert or replace data in an existing segment using any of the
functions described in Adding Elements to a New Segment. As mentioned
previously, GpiPutData is valid only in insert mode and only when the element
pointer is addressing the final element in the segment. That is, when you are
editing, you can use GpiPutData only to add data to the end of a segment.
A replace request is not valid when the element pointer is set to 0. If you
call GpiOpenSegment to create a new segment without first ensuring that the
current edit mode is insert, your first attempt to add an element to the
segment might cause an error condition to be raised.
ΓòÉΓòÉΓòÉ 3.1.5.1. Deleting a Graphics Element ΓòÉΓòÉΓòÉ
The PM has three different functions that allow you to delete elements within
the currently opened segment.
Function Description
GpiDeleteElement Deletes a single element at the current
element pointer location.
GpiDeleteElementRange Deletes a range of elements in a segment.
GpiDeleteElementsBetweenLabels Deletes a series of elements between two
labels.
When you remove an element from a segment, the element pointer addresses the
element immediately before the one you deleted. As with other editing
functions, the current drawing mode parameter must be DM_RETAIN when you are
deleting elements. The current editing mode (insert or replace) has no effect
on the delete functions.
ΓòÉΓòÉΓòÉ 3.1.5.2. Deleting Graphics Segments ΓòÉΓòÉΓòÉ
When you have finished drawing the subpicture associated with a segment, you
should delete the segment. The PM has two different functions that allow you to
delete segments.
Function Description
GpiDeleteSegment Deletes a retained segment
GpiDeleteSegments Deletes a range of retained segments.
Your application can only delete segments that have unique names because you
use the segment identifiers to identify the segment or range of segments for
deletion. Retained zero segments cannot be deleted. They disappear only when
their associated presentation space is deleted or reset. The presentation
space can be reset either by GpiResetPS with the GRES_SEGMENTS flag or the
GRES_ALL flag set, or by GpiSetPS. Resetting the presentation space is
described in Reusing the Presentation Space.
If GpiDeleteSegment occurs within a segment bracket and the segment identified
is the currently open segment, the operating system deletes the segment and
ignores the remainder of the functions up to, and including, GpiCloseSegment.
If GpiDeleteSegment occurs within a segment bracket and the identifier for a
segment other than the currently open segment, the operating system deletes
the segment, then continues processing the remaining functions in the segment
bracket. If GpiDeleteSegment occurs outside of a segment and references a
segment in the segment chain, the operating system removes the segment from
the chain and links the two adjacent segments, if such segments exist.
If the range of segments deleted by GpiDeleteSegments were in the segment
chain, the operating system "repairs" the chain by linking the segments
immediately preceding and following the deleted segments, if such segments
exist.
ΓòÉΓòÉΓòÉ 3.1.5.3. Copying a Single Graphics Element ΓòÉΓòÉΓòÉ
Your application can copy the graphics orders from a single element using the
GpiQueryElement and GpiElement functions. GpiQueryElement copies the graphics
orders (or part of the orders, depending on allocated size) from an element
into an array of bytes. GpiQueryElement is not valid within an element bracket,
nor if the drawing mode is other than DM_RETAIN.
GpiElement copies the data from the array back into the current segment. The
data may not contain any begin or end element orders. GpiElement is not valid
within an element bracket. The element is retained if the drawing mode is
DM_RETAIN and drawn if the mode is either DM_DRAW, or DM_DRAWANDRETAIN.
ΓòÉΓòÉΓòÉ 3.1.5.4. Copying Multiple Graphics Elements ΓòÉΓòÉΓòÉ
Your application can use GpiGetData and GpiPutData to:
Copy elements from one segment to another
Copy elements from one position in a segment to another position in the
same segment.
GpiGetData copies a buffer of graphics orders from a named segment, into an
area of application storage, whose byte size you specify on input. Only the
named segment must not be open when you call this function. The named segment
is also known as the source segment.
The first time GpiGetData is called, data retrieval has to start at the
beginning of the segment. This is done by declaring an element offset of 0.
Output from GpiGetData depends on whether the area of application storage is
large enough to hold the entire buffer of graphics orders. If so, the buffer
is returned along with a count of the number of bytes of data returned to you
from the segment. If not, the application storage is filled, and the count is
set to the size of the application storage. The offset of the element where
GpiGetData stopped copying, and the count are returned. Your application can
then determine if a subsequent GpiGetData needs to be called, by checking that
the count is less than the size (length) of the application storage.
On subsequent GpiGetData functions, the element offset can be 0, or it can be
the offset value that was returned from the previous function. In this manner,
if your application calls GpiGetData more than once to copy an entire segment,
it can "pick up where it left off", rather than recopying the segment from the
beginning each time.
You can copy the data from the application storage to a new location in a
segment using GpiPutData. This receiving segment is also known as the
destination segment. The segment into which you are copying the data can be
open when you call GpiPutData.
If GpiGetData does not retrieve a complete segment, the data it does retrieve
can be written out to the second segment using GpiPutData, even if the last
order copied is incomplete.
The current drawing mode determines whether the graphics orders are executed,
stored in the segment, or both. When you call GpiPutData, the current edit
mode must be SEGEM_INSERT and, if there is already data in the destination
segment, the element pointer must address the last element of the segment.
Because the PM does not support explicit renaming of segments,
GpiGetData-GpiPutData is the method you use to rename a segment. That is,
create a second segment with the desired name, copy the contents of the first
segment to it, then delete the original segment.
ΓòÉΓòÉΓòÉ 3.1.6. Drawing Retained Graphics ΓòÉΓòÉΓòÉ
Nonretained graphics segments and primitives outside of graphics segment are
always drawn immediately to the current output device. Segments that have been
retained in segment store, however, can be drawn any number of times to any
number of device contexts. The PM has three different functions that allow you
to draw segments:
Function Description
GpiDrawSegment Draws a single segment in the chain
GpiDrawFrom Draws a group of segments in the chain
GpiDrawChain Draws the entire chain
GpiDrawSegment draws a single, named segment, which can be chained or
unchained. You supply the segment name as input to this function.
GpiDrawSegment can draw a dynamic segment in some circumstances. These are
described in Drawing Dynamic Segments.
GpiDrawFrom draws one or more root segments from the segment chain. You supply
the names of two root segments as input. The drawing process starts at the
first named segment and draws all chained and called segments, excluding
dynamic segments, up to and including the second named segment.
The order in which you specify the segment names is to reflect their relative
positions in the segment chain. If the second-named segment appears in the
segment chain before the first-named segment, no error is raised, but drawing
starts from the first named segment and continues to the end of the chain.
This also happens if the second segment is an unchained segment rather than a
root segment. If the drawing control, DCTL_DYNAMIC is set, any dynamic
segments already drawn on the display are removed before GpiDrawFrom begins to
draw nondynamic segments. Then they are redrawn after GpiDrawFrom ends.
GpiDrawChain draws all nondynamic chained segments in a named presentation
space, as well as any unchained segments called by those chained segments. It
does not draw dynamic segments. You supply only the presentation space handle
as input to this function. If the drawing control, DCTL_DYNAMIC is set, any
dynamic segments already drawn on the display are removed before GpiDrawFrom
begins to draw nondynamic segments. Then they are redrawn after GpiDrawFrom
completes.
You can call any of these functions while a segment is open. The open segment
is not modified by these functions, although any of them can result in the
current attribute values and current position being modified. For more
information about the attribute-resetting process, see Graphics Attributes.
The current drawing mode determines whether the segments identified in the
drawing functions are executed, stored in the segment, or both. The current
drawing mode does not affect which segments are drawn, or the priority in
which they are drawn for any of these three GPI drawing functions.
If an error occurs during the drawing process, you can determine where the
error occurred using GpiErrorSegmentData. This function returns information
about the last error that occurred during a segment-drawing operation. It
returns a pointer to the segment identifier and a pointer to one of three
constants that indicate when the error occurred.
Constant Error occurred...
GPIE_SEGMENT While drawing the segment
GPIE_ELEMENT While calling GpiElement
GPIE_DATA While calling GpiPutData
ΓòÉΓòÉΓòÉ 3.1.7. Drawing Dynamic Segments ΓòÉΓòÉΓòÉ
A dynamic segment is a chained segment that possesses special properties.
Dynamic segments are those that can be moved or changed in some other way
without disturbing the remaining parts of the picture. To draw dynamic segments
on the display screen for the first time, use GpiDrawDynamics. GpiDrawDynamics
draws every dynamic segment in the segment chain.
When they have been drawn on the display, dynamic segments can be updated. For
example, to move one or more dynamic segments to another part of the display
screen, remove them from their current position using GpiRemoveDynamics. You
can restrict the scope of this function by supplying the names of a start
segment and a finish segment. The start segment and finish segment can be the
same. Dynamic segments outside of this range are not removed from the display
screen.
If you intend to re-associate the presentation space, call GpiRemoveDynamics
first; otherwise, GpiRemoveDynamics cannot remove the dynamic segments after
the presentation space has been re-associated. The dynamic segments effectively
cease to be dynamic.
After removing the appropriate dynamic segments from the display screen, you
can redraw them elsewhere, again using GpiDrawDynamics. If you specify a range
of dynamic segments in GpiRemoveDynamics, the redrawing is restricted to that
range. Note that, when dynamic segments have been drawn on the display screen,
you must not edit their definitions in segment store.
Dynamic segments are treated like nondynamic segments when you are directing
output to a hardcopy device. GpiRemoveDynamics and GpiDrawDynamics raise an
error condition if the current output device is not a display window.
ΓòÉΓòÉΓòÉ 3.1.8. The Drawing Controls ΓòÉΓòÉΓòÉ
GpiErase clears the output display of the currently associated device to
CLR_BACKGROUND, which is the normal background color for the device. If you are
using the default color table, this value clears the window background to
white. This is a once-only request and must be issued each time you want the
display screen cleared before drawing a new picture. You can use this function
for either a micro presentation space or a normal presentation space.
To get this effect for more than one drawing request, you can use
GpiSetDrawControl. This function establishes current values for five drawing
controls, which remain in effect until they are reset. The following table
describes the five drawing controls.
Drawing Controls
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéControl ΓöéValue ΓöéIf set, the Γöé
Γöé Γöé Γöéoperating system... Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBoundary data ΓöéDCTL_BOUNDARY Γöécomputes the Γöé
Γöéaccumulation Γöé Γöédimensions of the Γöé
Γöé Γöé Γöésmallest rectangle Γöé
Γöé Γöé Γöéthat would Γöé
Γöé Γöé Γöécompletely surround Γöé
Γöé Γöé Γöéthe retained-drawingΓöé
Γöé Γöé Γöéoutput. Γöé
Γöé Γöé ΓöéThis control is Γöé
Γöé Γöé Γöédescribed in Γöé
Γöé Γöé ΓöéClipping and Γöé
Γöé Γöé ΓöéBoundary Γöé
Γöé Γöé ΓöéDetermination. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCorrelation ΓöéDCTL_CORRELATE Γöéperforms correlationΓöé
Γöé Γöé Γöéoperations on any Γöé
Γöé Γöé Γöéprimitives or any Γöé
Γöé Γöé Γöéoutput associated Γöé
Γöé Γöé Γöéwith GpiPutData or Γöé
Γöé Γöé ΓöéGpiElement. Γöé
Γöé Γöé ΓöéThis control is Γöé
Γöé Γöé Γöédescribed in Γöé
Γöé Γöé ΓöéCorrelation. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDisplay control ΓöéDCTL_DISPLAY Γöédraws retained Γöé
Γöé Γöé Γöéoutput on the deviceΓöé
Γöé Γöé Γöéidentified by the Γöé
Γöé Γöé Γöécurrent device Γöé
Γöé Γöé Γöécontext. If this Γöé
Γöé Γöé Γöécontrol is not set, Γöé
Γöé Γöé Γöéno retained output Γöé
Γöé Γöé Γöéwill appear on the Γöé
Γöé Γöé Γöédevice. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw-dynamic-segments ΓöéDCTL_DYNAMIC Γöécalls Γöé
Γöé Γöé ΓöéGpiRemoveDynamics Γöé
Γöé Γöé Γöébefore drawing any Γöé
Γöé Γöé Γöéretained output and Γöé
Γöé Γöé Γöéthen, after drawing Γöé
Γöé Γöé Γöéthe retained output,Γöé
Γöé Γöé Γöéit calls Γöé
Γöé Γöé ΓöéGpiDrawDynamics to Γöé
Γöé Γöé Γöédraw output stored Γöé
Γöé Γöé Γöéin dynamic segments.Γöé
Γöé Γöé ΓöéThis automatically Γöé
Γöé Γöé Γöéremoves all dynamic Γöé
Γöé Γöé Γöésegments from the Γöé
Γöé Γöé Γöédisplay screen Γöé
Γöé Γöé Γöébefore a GpiDraw... Γöé
Γöé Γöé Γöérequest is issued, Γöé
Γöé Γöé Γöéthen later redraws Γöé
Γöé Γöé Γöéthe segments. This Γöé
Γöé Γöé Γöéensures that dynamicΓöé
Γöé Γöé Γöésegments are always Γöé
Γöé Γöé Γöédrawn on top of Γöé
Γöé Γöé Γöénondynamic segments Γöé
Γöé Γöé Γöéand primitives. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéErase-before-draw ΓöéDCTL_ERASE Γöécalls GpiErase Γöé
Γöé Γöé Γöébefore drawing any Γöé
Γöé Γöé Γöéretained output. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
GpiSetDrawControl can be called in either a micro or a normal presentation
space, although not all of the controls are valid in a micro presentation
space. GpiDrawSegment can be used to draw a dynamic segment in some
circumstances. Its effects are as follows:
If the named segment is both chained and dynamic, and the DCTL_DYNAMIC
drawing control is set, all dynamic segments in the chain, including the
named segment, are drawn as dynamic.
If the named segment is both chained and dynamic, and the DCTL_DYNAMIC
control is not set, the named segment is not drawn.
If the named segment is unchained and dynamic, it is drawn as a
nondynamic segment, regardless of the setting of the DCTL_DYNAMIC
control.
If you called GpiRemoveDynamics prior to calling GpiDrawDynamics and you
specified a range of dynamic segments, the operating system draws only that
range. If you set the DCTL_DYNAMIC control using GpiSetDrawControl, the
operating system calls GpiRemoveDynamics before drawing the subpictures from
the dynamic segments.
The DCTL_DISPLAY control is the only control set to DCTL_ON by default. All
other controls are set to DCTL_OFF when you create a presentation space.
ΓòÉΓòÉΓòÉ 3.2. Using Segment Editing Functions ΓòÉΓòÉΓòÉ
You can use editing functions to:
Create a chained-dynamic segment
Delete a segment
Edit the contents of a segment
The following figure shows an example of how to edit the contents of a
segment. In the example, three elements are inserted. The steps required for
this task are as follows:
1. Set the segment edit mode to insert or replace using GpiSetEditMode.
2. Set the drawing mode to retain.
3. Open the segment using GpiOpenSegment, passing it the segment identifier
from a previous correlation operation.
4. Set the element pointer so that it points to the position at which you
will replace or insert an element using GpiSetElementPointer,
GpiSetElementPointerAtLabel or GpiOffsetElementPointer.
5. Insert the new primitives using any of the Gpi primitive functions.
6. Delete any unnecessary primitives using GpiDeleteElement or
GpiDeleteElementRange.
7. Close the segment using GpiCloseSegment.
#define INCL_GPISEGEDITING
#define INCL_GPICONTROL
#include <os2.h>
void fncESEG01(void){
HPS hps;
LONG idNonChained;
POINTL ptl;
GpiSetEditMode(hps, SEGEM_INSERT);
GpiSetDrawingMode(hps, DM_RETAIN);
GpiOpenSegment(hps, idNonChained);
GpiSetElementPointer(hps, 0L);
GpiSetColor(hps, CLR_YELLOW);
ptl.x = 100; ptl.y = 100;
GpiMove(hps, &ptl);
ptl.x = 150; ptl.y = 150;
GpiBox(hps, DRO_OUTLINE, &ptl, 40L, 40L);
ptl.x = 30; ptl.y = 30;
GpiMove(hps, &ptl);
GpiSetElementPointer(hps, 5L);
GpiDeleteElement(hps);
GpiCloseSegment(hps);
} /* fncESEG01 */
The first element inserted contains the graphics order that sets the color to
yellow; the second element moves the current position; and the third element
draws an outlined box with rounded corners. After the three elements are
inserted, the code deletes the element at position 5 in the segment (this
element was previously at positions 1 and 2).
ΓòÉΓòÉΓòÉ 4. Fonts ΓòÉΓòÉΓòÉ
In typography, a font is a collection of characters that share a common height,
line weight, and appearance. In Presentation Manager, fonts are an
lcid-identified resource, like bit maps, and are used in conjunction with the
character string primitive data structures to define the appearance of
displayed and printed text. The primary role of the PM with regard to fonts is
to evaluate whether a particular font is appropriate for a given situation.
The following topics are related to information in this chapter:
Presentation spaces and device contexts
Character string primitives
Coordinate spaces and transformations
Color and mix attributes
ΓòÉΓòÉΓòÉ 4.1. About Fonts ΓòÉΓòÉΓòÉ
Font height is specified in printer's points, referred to in this book as just
points. A point equals approximately 1/72 of an inch. The line weight and
appearance of a font are specified by the categories listed in the following
table.
Examples of Line Weight and Font Appearance Categories
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute ΓöéCategory ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLine Weight ΓöéNormal ΓöéCharacters drawn with a normal line Γöé
Γöé Γöé Γöéweight Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéBold ΓöéCharacters drawn with a heavier lineΓöé
Γöé Γöé Γöéweight Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAppearance ΓöéCondensed ΓöéCharacters drawn with half the Γöé
Γöé Γöé Γöéaverage character width Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéExpanded ΓöéCharacters drawn with twice the Γöé
Γöé Γöé Γöéaverage character width Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéItalic ΓöéCharacters drawn with a normal line Γöé
Γöé Γöé Γöéweight and sloped to the right Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
A font family is a collection of fonts that share common design characteristics
such as stroke width and serif. Stroke width refers to the width of lines used
to draw the characters and symbols of a font. A serif is a short cross-line
drawn at the ends of the main strokes forming a character or symbol.
Text output is drawn with the characters and symbols of a font. The operating
system stores fonts either in memory or on devices. Applications can access
fonts through a device context associated with the current presentation space.
When an application creates a presentation space, using GpiCreatePS or
WinGetPS, the operating system assigns the presentation space a default font
from one of the available fonts. An application can retrieve information about
the default font using GpiQueryFontMetrics.
ΓòÉΓòÉΓòÉ 4.1.1. Image Font and Outline Font Implementation ΓòÉΓòÉΓòÉ
The operating system can define and implement the characters of a font as
either images or outlines.
Each of the characters in an image font (sometimes called a raster font) is
created by alternating the ON and OFF settings of pels to produce the image.
The image characters are stored as a bit map. Sometimes image fonts are even
referred to as bit-map fonts.
The characters in an image font must be drawn in a fixed size-you cannot rotate
or scale them, for example-but usually they are of good quality. They are
displayed faster than outline characters, and frequently they look better at
low resolutions.
The characters in an outline font, on the other hand, are drawn using a
sequence of lines and arcs. Then the characters are filled if so requested. The
outline characters are stored as a collection of line, fillet, and spline
functions. Outline fonts are transformable because the outline characters can
be scaled, rotated, and sheared. Outline fonts can be implemented as vectors,
drawn by a series of small, straight lines. If that is the case, they can be
referred to correctly as vector fonts. Vector fonts can be drawn much faster
than fonts requiring the inclusion of actual curves and arcs.
A major advantage of outline fonts is their device independence. Unlike image
fonts, whose appearance depends on the device's pel definition.
The following figure is an example of a character in both an image font and an
outline font.
Image and Outline Characters
The image character is produced by manipulating pels. The outline character is
produced by drawing a sequence of lines and arcs. (The resultant shape of an
outline character can be filled if desired.)
Most of the functions and data structures described in this chapter relate only
to outline fonts.
ΓòÉΓòÉΓòÉ 4.1.2. PM-Supplied Fonts ΓòÉΓòÉΓòÉ
The PM provides a number of both image and outline typographic-quality
character fonts. On some devices, image fonts in small font sizes have a better
appearance than their outline-font equivalents.
Type size is measured in points. There are approximately 72 points to an inch,
so each character in a 24-point font, for example, is 1/3-inch high. Each
incremental unit of a presentation page in PU_TWIPS format is 1/20 of a
printer's point (1/1440 inch).
The following image fonts are available on all OS/2-supported display adapters:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFont Family Name ΓöéPoint Sizes Available Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTms Rmn Γöé8, 10, 12, 14, 18, 24 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéHelv Γöé8, 10, 12, 14, 18, 24 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCourier (monospace) Γöé8, 10, 12 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSystem Monospace Γöé10 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
In addition, a default system font is used in window components such as title
bars and menus. It is a proportionally spaced Swiss font.
The outline fonts provided by the PM are Adobe** Type 1. The appearance and
performance characteristics of these fonts are more flexible than for image
fonts.
The following table lists the outline fonts available with the operating system
and their equivalent fonts from earlier versions of the OS/2 operating system.
Available Outline Fonts
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéOutline Font ΓöéOS/2 Fonts Available ΓöéEquivalent Γöé
ΓöéFamily Name Γöé ΓöéName Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTimes New Roman** ΓöéTimes New Roman ΓöéTms Rmn Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéTimes New Roman Bold ΓöéTms Rmn Bold Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéTimes New Roman Bold Italic ΓöéTms Rmn Bold Γöé
Γöé Γöé ΓöéItalic Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéTimes New Roman Italic ΓöéTms Rmn ItalicΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéHelvetica** ΓöéHelvetica ΓöéHelv Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéHelvetica Bold ΓöéHelv Bold Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéHelvetica Bold Italic ΓöéHelv Bold Γöé
Γöé Γöé ΓöéItalic Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéHelvetica Italic. ΓöéHelv Italic Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCourier ΓöéCourier ΓöéCourier Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéCourier Bold ΓöéCourier Bold Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéCourier Bold Italic ΓöéCourier Bold Γöé
Γöé Γöé ΓöéItalic Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéCourier Italic ΓöéCourier ItalicΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSymbol ΓöéSymbol ΓöéNone Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéThe outline font names provided with earlier versions of the Γöé
ΓöéOS/2 operating system are still supported, but the Γöé
Γöécorresponding new fonts are obtained when the previous font Γöé
Γöénames are selected. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 4.1.3. Availability of Additional Fonts ΓòÉΓòÉΓòÉ
Over 600 Adobe Type 1 fonts are available from font vendors, and user systems
could have a large number of these installed. Applications must be capable of
functioning properly with whatever font the user selects.
An application can examine the font metrics to see what a font looks like or
display different font characters from which the user can choose. When dealing
with an interactive or user-driven application, the recommended method of
choosing a font is to call WinFontDlg, which displays an example of the font in
a dialog box.
Additional Adobe Type 1 fonts can be used just like other outline fonts.
Notice, however, that some of those fonts are more stylized; that is, the fonts
have a greater variation in the widths of different characters within the same
font, which is provided by kerning.
Adobe Type 1 fonts, provided with and for a particular application, can be
loaded with GpiLoadFonts, provided that the following rules are observed:
The .AFM file of the font must be specified as the font file.
The .PFB file must be in the same directory as the .AFM file.
ΓòÉΓòÉΓòÉ 4.1.4. Font Data Structures and Attributes ΓòÉΓòÉΓòÉ
The attributes of fonts are contained in the FONTMETRICS data structure. The
appearance of the actual text is influenced also by the attributes of the
individual characters, which can be found in the CHARBUNDLE data structure.
An application can determine whether to use a particular font by examining its
font metrics, which are the measurements that define the features of that font.
The measurements are decided on by a font designer, whose most important
criteria might be ensuring that the font is pleasing to the eye.
Unlike the attributes of a character string primitive, the individual font
metrics attributes cannot be changed using specific GPI functions. Your
application can determine the values of the current logical font attributes by
calling GpiQueryFontMetrics, which accepts as input the amount of data to be
returned as well as a pointer to the data area. Unlike other GPI calls,
GpiQueryFontMetrics does not return the size necessary for all font metrics
data. Querying with a sizeof operator, instead of calling the query twice,
returns the size data.
The following table and text defines and explains the uses of the various font
metric attributes.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFace name ΓöéThe full typeface name of a Γöé
Γöé Γöéfont, such as Courier Bold Γöé
Γöé ΓöéItalic. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFamily name ΓöéA broader equivalent of the Γöé
Γöé Γöéface name (e.g.Courier). Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCode page ΓöéThe mapping between a set of Γöé
Γöé Γöécodepoints and a set of Γöé
Γöé Γöégraphic characters. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter cell ΓöéControls the height and width Γöé
Γöé Γöéof outline font characters. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter cell ascent ΓöéDistance between the baseline Γöé
Γöé Γöéto the top of the character Γöé
Γöé Γöécell. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter cell descent ΓöéDistance between the baseline Γöé
Γöé Γöéand the bottom of the Γöé
Γöé Γöécharacter cell. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMaximum baseline extent ΓöéMaximum vertical extent of Γöé
Γöé Γöéfont characters in world Γöé
Γöé Γöécoordinates. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMaximum ascender ΓöéMaximum distance a font Γöé
Γöé Γöécharacter ascends above the Γöé
Γöé Γöébaseline. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMaximum descender ΓöéMaximum distance a font Γöé
Γöé Γöécharter descends below the Γöé
Γöé Γöébaseline. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInternal leading ΓöéVertical distance equal to theΓöé
Γöé Γöédifference between the maximumΓöé
Γöé Γöébaseline extent and the em Γöé
Γöé Γöéheight. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEm height ΓöéEquivalent to the character Γöé
Γöé Γöécell height. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEm width ΓöéEquivalent to the character Γöé
Γöé Γöécell width. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéX height ΓöéHeight above the baseline of Γöé
Γöé Γöéany lowercase character. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLowercase ascent ΓöéMaximum distance of a Γöé
Γöé Γöélowercase character above the Γöé
Γöé Γöébaseline. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLowercase descent ΓöéMaximum distance of a Γöé
Γöé Γöélowercase character below the Γöé
Γöé Γöébaseline. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéExternal leading ΓöéMaximum vertical font spacing Γöé
Γöé Γöéthat can be added without Γöé
Γöé Γöéadversely affecting the Γöé
Γöé Γöéappearance of the text. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAverage character width ΓöéAverage width of font Γöé
Γöé Γöécharacters in world Γöé
Γöé Γöécoordinates Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter slope ΓöéInitial slope of a character Γöé
Γöé Γöéwith respect to a vertical Γöé
Γöé Γöéline. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInline direction ΓöéCharacter angle measured with Γöé
Γöé Γöérespect to a horizontal line. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWeight class ΓöéSpecifies the thickness of Γöé
Γöé Γöéeach stroke of a font Γöé
Γöé Γöécharacter. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFirst, last, default, and ΓöéSee the topic Glyphs, Code Γöé
Γöébreak characters ΓöéPages and Code Points. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The face name attribute is the typeface name by which a particular font design
is known. Two examples are Times New Roman Bold and Times New Roman Italic.
Roman is the family name of these fonts. You always should provide a face name
because most outline fonts are known by it.
The code page to be associated with the font is identified by this metric. Some
fonts are specific to a particular code page and should be used with only that
code page. Other fonts are universal and can be used with any supported code
page.
Every character in a font is drawn within a rectangular region called a
character cell. The character-cell height is the distance from the bottom of
the character cell to its top. The width of the character cell is the distance
from one side to the other.
An imaginary horizontal line, called a baseline, is drawn through the lower
portion of the character cell. The operating system uses the baseline to
position characters. All uppercase and most lowercase letters in a given font
rest approximately on the baseline. Some lowercase letters, such as g and y,
descend below the baseline.
The distance from the baseline to the top of the character cell is the
character-cell ascent. Similarly, the character-cell descent is the distance
from the baseline to the bottom of the character cell. The following figure
illustrates characters drawn along a baseline inside their character cells.
Various font metrics also are illustrated.
Some Font Metrics
The maximum baseline extent is the sum of the maximum ascender and the maximum
descender values. The internal leading is the space allowed for diacritics
above capital letters. When an application draws a string of text, the
operating system positions the leftmost point of the baseline over a
predetermined point for each character in the string.
A font's Em height is a measure of its visual height. This measurement was
given its name because, historically, the height of an uppercase letter M
usually was equal to the average height of all uppercase characters in the
font. However, this is no longer the case.
The value of Em height represents the font point size in world coordinates and
is the same as the character cell height. For an outline font, this can be set
by the character cell height attribute. The value of Em Width is the equivalent
horizontal dimension and is the same as the character cell width. For an
outline font this also can be set by the character cell width attribute. These
are, in fact, the dimensions of the em square (a typographic term) and, like
point size, cannot be defined in terms of any measurable characteristic of a
visible character of the font.
The average distance from the baseline to the top of any lowercase character is
called a font's x height. This measurement was given its name because the
height of a lowercase x usually is equal to the average height of all lowercase
characters in the font.
The maximum ascender is the height of the tallest character in a font. The
maximum descender is the depth (below the baseline) of the lowest character in
a font.
The lowercase ascent is the height of the tallest lowercase character in a
font. The lowercase descent is the depth (below the baseline) of the lowest
lowercase character in a font.
Many fonts reserve part of the space in the top of each character cell for
accent marks. This reserved space is called internal leading. Some fonts
require a certain amount of space to be left between rows of text. This space,
called external leading, is not included in the character-cell height or ascent
measurements. The external leading is the recommended space to leave between
rows of text to preserve its pleasing appearance.
The average character width is stored in the lAveCharWidth field in the
FONTMETRICS structure. The average character width is a measure of character
width based on the normal frequency of lowercase letter usage in the English
language. You can use this value to approximate the average width of a
character in string length calculations.
The maximum baseline extent for a font is the sum of the maximum ascender and
the maximum descender. Maximum baseline extent is not equal to cell height for
outline fonts, but is for image fonts.
The character slope is an angle measured clockwise with respect to a typical
vertical line. The slope of a normal font is 0; the slope of an italic font is
other than 0. The character slope in the FONTMETRICS data structure can be
thought of as the initial slope, since the slope can be changed in the
CHARBUNDLE data structure.
The inline direction is an angle measured clockwise with respect to a
horizontal line. The inline direction for a Swiss, Helvetica, or Roman font is
normally 0-exactly horizontal. The inline direction for a Hebrew font is
normally 180, because Hebrew text is oriented right to left.
The character-rotation angle is an angle measured counterclockwise with respect
to a horizontal line. The baselines of characters are aligned with the vector
drawn at the angle of rotation.
The weight class specifies the thickness of each stroke that forms part of each
character in a font.
The first, last, default, and break character all are associated with glyphs
for UGL fonts and code pages.
A superscript is a character drawn immediately above and to the right of a
normal character in a string of text. Superscripts are identified by a width
and height and by vertical and horizontal offsets.
A subscript is a character drawn immediately below and to the right of a normal
character in a string of text. Subscripts are identified by a width and height
and by vertical and horizontal offsets.
ΓòÉΓòÉΓòÉ 4.1.5. Glyphs, Code Pages, and Code Points ΓòÉΓòÉΓòÉ
The image or picture that you associate with each character or symbol in a font
is called a glyph. The mapping between a set of glyphs and their code points is
called a code page.
For a single byte character set (SBCS), each code page contains up to 256 code
points. Normally these are 8-bit integers in the range 0 through 255, with one
code point identifying one glyph in that code page. The code pages can be
either ASCII or EBCDIC. Because a code point repeats on a new code page, you
need both the code page and code point to uniquely identify a glyph.
There usually is one code page per font. However, double byte character sets
(DBCS) are sometimes used for Asian languages with large character sets. Fonts
are a set of glyph definitions and a default code page mapping. The same set of
font glyph definitions is remapped for different code pages.
Each font contains four special glyph points:
First glyph
Last glyph
Default glyph
Break glyph
First and last glyph points are of more interest to the font designers than
application programmers because they apply to the set of font glyph
definitions rather than a particular code page. The last character is the
maximum code point of the font that has a glyph associated with it and may be
bigger than 256.
The default glyph appears in text when an application specifies a glyph point
that does not exist in the font.
The break glyph usually is the space character and often has the same code
point as the default character.
Actually a font can have more or less than 256 definitions, but any particular
code page may have less than 256 but no more. There may be a translation
between the code point in the code page and the code point (between the first
and last glyphs) that references the glyph in the font.
The operating system assigns unique identifiers to each of its code pages.
Common code pages are 437-the United States code page, and 850-the
multilingual code page. The default code page is 850.
An application can determine the current code page by calling GpiQueryCp. or
it can assign a new code page using GpiSetCp. If you default the code page in
the FATTRS structure when calling GpiCreateLogFont, you get the current code
page as specified by GpiSetCp (or returned by GpiQueryCp). You can specify any
one of the code page identifiers returned to you from WinQueryCpList.
When using a font other than the system font, you specify the required code
page in the FATTRS structure of GpiCreateLogFont. You can determine the code
page for that font (if it is the current logical font) by using
GpiQueryFontMetrics.
ΓòÉΓòÉΓòÉ 4.1.6. Proportional and Monospace Fonts ΓòÉΓòÉΓòÉ
When text is drawn, the operating system aligns each character by positioning
its character cell next to that of the previous character.
A monospace font provides the same amount of space for each character, whatever
its shape. These fonts also are called fixed fonts. Courier and System
Monospaced are monospace fonts. Monospace fonts, in fact, are essential for
some purposes- for example program listings, where vertical alignment is
important.
A proportionally-spaced font is one in which some characters are allotted less
space than others, so that each character occupies the proportion of space that
is correct for its shape. For example, a lowercase letter l does not need the
same space as a lowercase letter m. Many graphics fonts supplied by the PM,
including the system font, support proportional spacing.
The font metrics value maxcharinc specifies the width of the widest character
in the font, and the value avecharwidth specifies an average width of the
characters in the font.
You can retrieve information about the widths of the characters in the current
font by calling GpiQueryWidthTable. You provide the code point of the first
character you are interested in and the number of characters for which you want
width-table information.
ΓòÉΓòÉΓòÉ 4.1.7. Kerning ΓòÉΓòÉΓòÉ
Kerning, like proportional spacing, is a type of letter spacing. In a kerned
font, some characters are allowed to overhang others and, therefore, occupy an
area that is less than each character's increment for that font. Usually this
feature is restricted to pairs of characters whose appearance might benefit
from greater proximity. The five character pairs that most commonly benefit
from kerning are Yo, We, To Tr, and Ta.
Kerning is not available in the system-provided image fonts. The Helvetica and
Times New Roman outline fonts provided with the system do include kerning
information. You can specify kerning as a requirement on the GpiCreateLogFont.
Selecting a kerned font lets kerning take place whenever it is defined.
The a-space is the area of the character cell before the character; the b-space
is the area of the character cell occupied by the character; the c-space is the
area of the character cell after the character. The a-space and c-space are
shown in the following figure.
a-Space, b-Space, and c-Space
The best way to implement kerning is to use a kerning-pair table. The kerning
table will exist only for certain pairs of characters for which adjustments are
desirable.
Each of the entries in a kerning-pair table contains the code points of a pair
of kerned characters and an adjustment that should be applied to the character
width of the first character of the pair. A negative value means that the space
is decreased, and a positive value means it is increased, whenever the two
characters in a kerning pair are produced together. A kerning-pair table might
be provided with a purchased font. If so, it will be recorded in the font
header.
If kerning is specified on a character-pair basis (that is, if the font has a
kerning-pair table), the font has a specific number of kerned pairs.
GpiQueryKerningPairs returns kerning-pair information from the current logical
font. For each pair of kerned characters, you are given the characters
themselves and an adjustment in world coordinates that must be applied to the
character width of the first character of the pair.
When you specify negative a- and c-space values, the values affect any
character paired with the kerned character. Because this form of kerning cannot
be applied selectively, you have to choose the kerned characters carefully. For
example, an italic letter f ( Я ) is a good candidate for this sort of kerning,
because it can overhang most of the characters that precede and follow it.
An application can adjust the amount of space between all characters in a font
with GpiSetCharExtra. Any extra space is added to font kerning values. An
application also can adjust the width of a font's break character (space) with
GpiSetCharBreakExtra.
Kerning is not available on all devices. On devices that support kerning,
kerning is enabled by default. When kerning is not supported on a device,
kerning support is switched off by default. When kerning support is switched
off, the kerning information supplied with a font is ignored. To determine
whether a device supports kerning, use DevQueryCaps.
The kerning information can be implemented by your application when a character
string primitive is written to an output device. This is called rendering the
text. GpiCharStringPos and GpiCharStringPosAt, permit specification of the
starting position for each character. The entire character string can be
searched for character pairs that also are kerning pairs for the kerning
information to be applied.
ΓòÉΓòÉΓòÉ 4.1.8. FATTRS Data Structure ΓòÉΓòÉΓòÉ
The FATTRS structure is used to identify the characteristics of a requested
font. Certain attributes of a font that govern many individual character string
primitives are contained in FATTRS, as follows:
Record length
Selection indicators
Match value
Face name
Registry identifier
Code page
Maximum baseline extent
Average character width
Type indicator
Font use indicator
ΓòÉΓòÉΓòÉ 4.1.8.1. Record Length ΓòÉΓòÉΓòÉ
Record length determines the length of the FATTRS structure. An application
normally specifies this with the sizeof operator.
ΓòÉΓòÉΓòÉ 4.1.8.2. Selection Indicators ΓòÉΓòÉΓòÉ
There are five selection indicators:
Indicator If set ON, selects...
FATTR_SEL_ITALIC A font with an italic appearance. This is intended
for use with an image font and results in a
simulation of an italic font.
FATTR_SEL_BOLD A boldface version of the font. This is intended
for use with an image font and results in a
simulation of a boldface font.
FATTR_SEL_OUTLINE Hollow characters when using an outline font. This
only can be used with outline fonts.
This indicator is less important than the others
because improved performance is now available
(from Adobe Type Manager) on filled outline fonts
than was originally available when this option
(FATTR_SEL_OUTLINE) was introduced.
FATTR_SEL_STRIKEOUT A font in which the characters are struck through.
This option also might be selected on the
character string primitive.
FATTR_SEL_UNDERSCORE A font in which the characters are underscored.
This option also might be selected on the
character string primitive.
Any combination of these indicators can be set. When set, they cause a
simulation of the selected feature. For example, if you require a bold,
italicized version of a PM image font, PM simulates that feature because bold,
italic image fonts are not supplied.
ΓòÉΓòÉΓòÉ 4.1.8.3. Match Value ΓòÉΓòÉΓòÉ
The match value is a number that identifies a physical font. It is allocated to
the font when the font is loaded. If the match value is less than 0, the font
is a device font; and, if the match value is greater than 0, the font is a
generic font.
A device font is exclusive to the device with which it is associated, and its
match number is guaranteed to be unique only within the device driver. If an
application prints on a different printer, the application cannot guarantee
that the font will be identical just by specifying the match value. A generic
font is available on more than one device. The PM-supplied fonts, for example,
are generic fonts. Printer fonts always are device fonts, but you also can and
should use generic fonts with printers.
You can choose whether or not to use the match value to specify the font when
calling GpiCreateLogFont. Specifying the match value is easier but less
flexible than the alternative, which is to specify the font name and outline
characteristics. For an image font, the alternative is to specify the maximum
baseline extent and average character width of the required font.
ΓòÉΓòÉΓòÉ 4.1.8.4. Face Name ΓòÉΓòÉΓòÉ
The face name value in the FATTRS data structure is identical to the face name
of the FONTMETRICS data structure when describing a specific font.
ΓòÉΓòÉΓòÉ 4.1.8.5. Registry Identifier ΓòÉΓòÉΓòÉ
The registry identifier is a unique number by which the font is registered with
IBM. The registry identifier of a particular font can be retrieved by calling
GpiQueryFonts. If you do not have a registry number, set this value to 0.
ΓòÉΓòÉΓòÉ 4.1.8.6. Code Page ΓòÉΓòÉΓòÉ
The code page is the identifier of the code page to be associated with the
font. You can default the code page in GpiCreateLogFont by specifying 0. Like
the face name, the code page in the FATTRS data structure is identical to the
code page in the FONTMETRICS data structure when describing a specific font.
ΓòÉΓòÉΓòÉ 4.1.8.7. Maximum Baseline Extent ΓòÉΓòÉΓòÉ
The maximum baseline extent is the vertical space occupied by characters in the
font. If you are setting the font-use indicator FATTR_FONTUSE_OUTLINE, you
should set the maximum baseline extent to 0. Outline fonts take an equivalent
value from the character cell attribute that is current when text is written to
an output device.
The maximum baseline extent value is required to select an image font and must
be specified in world coordinates. For image fonts, this is the vertical height
in world coordinates of character images in the font. This field must be
specified when requesting an image font with GpiCreateLogFont.
The maximum baseline extent measurement is shown in a previous figure. The
maximum baseline extent in the FATTRS data structure is used for programming,
unlike the maximum baseline extent in the FONTMETRICS data structure, which is
only measurement as recommended by the font's designer.
ΓòÉΓòÉΓòÉ 4.1.8.8. Average Character Width ΓòÉΓòÉΓòÉ
The average character width of a font is the average character increment in
world coordinates. The character increment is the sum of the a-space, b-space,
and c-space of a character. If you are setting the font-use indicator
FATTR_FONTUSE_OUTLINE, you can set the average character width to 0 because the
outline fonts take an equivalent value from the character cell attribute that
is current when text is written to an output device.
This field should be specified when requesting an image font using
GpiCreateLogFont. It must be specified in world coordinates.
ΓòÉΓòÉΓòÉ 4.1.8.9. Type Indicator ΓòÉΓòÉΓòÉ
PM provides a type indicator to allow the further specification of font most
appropriate to your application. The type indicators found in the FATTR data
structure are not interchangeable with the type indicators in the FONTMETRICS
data structure.
The most commonly used type indicator, FATTR_TYPE_KERNING, causes kerning to
take effect for those fonts that contain kerning-pair information.
FATTR_TYPE_KERNING is supported only for PostScript** devices.
There are three other type indicators provided:
Indicator When...
FATTR_TYPE_ANTIALIASED An anti-aliased font is required
FATTR_TYPE_MBCS A mixed single- or double-byte code page is
required
FATTR_TYPE_DBCS A double-byte code page is required.
ΓòÉΓòÉΓòÉ 4.1.8.10. Font-Use Indicators ΓòÉΓòÉΓòÉ
The font-use indicators tell the PM what you intend to do with the font, and
determine whether you get an image font or an outline font. There are three
font-use indicators:
Indicator If set ON...
FATTR_FONTUSE_OUTLINE Forces selection of an outline font. This value
must be set if you intend to use graphics
characters in a path definition.
FATTR_FONTUSE_TRANSFORMABLE Allows the scaling, rotating, or shearing of font
characters. Set this value ON if the current
character mode is CM_MODE3.
FATTR_FONTUSE_NOMIX Allows the PM to ignore current mix-mode values.
Set this value ON if the graphics text is not
going to be written over or underneath other
graphics, because it improves the performance of
text drawing.
FATTR_FONTUSE_TRANSFORMABLE and FATTR_FONTUSE_OUTLINE normally are both
specified to select an outline font. Specify neither if you want to select an
image font.
ΓòÉΓòÉΓòÉ 4.1.9. Public and Private Fonts ΓòÉΓòÉΓòÉ
The fonts supplied by PM are loaded automatically when the system is started
and are available to any application at any time. They are said to be public
fonts. Any font that you define locally has to be loaded before you can use it.
If you load a locally defined font using the Install option of the Workplace
Font Palette, that font is available to any application in the system, and,
therefore is a public font. Some devices provide their own fonts. All device
fonts are public fonts.
Any font loaded using GpiLoadFonts from within an application is a private
font. A private font is available only to the application that loads it. The
file in which you store a locally created font definition can contain more than
one font definition. GpiLoadFonts loads a named font file and, therefore, loads
all fonts defined in that file. GpiQueryFontFileDescriptions provides the
family name and the face name of each font in a locally defined font file. Use
this function to determine if a particular file contains the font you want to
use before you load it.
To unload a previously loaded private font file, call GpiUnloadFonts. You
cannot unload public fonts with this function.
You cannot use private fonts in a document that you want to print using the
spooler. If you want to print the document from a printer server, using the
PM_Q_STD format, all the fonts used in the document must be installed as public
fonts on the server. You can use either public or private fonts if you specify
the data format PM_Q_RAW or if you want to print without the spooler.
ΓòÉΓòÉΓòÉ 4.1.10. Drawing a Character String Primitive ΓòÉΓòÉΓòÉ
To draw a string of one or more graphics characters from the current font, call
GpiCharString. The string starts at the current position and, when it has been
drawn, the new current position is the point at which the next character would
be, had there been one.
To draw the string starting at a position other than the current position, call
GpiCharStringAt. This is equivalent to calling GpiSetCurrentPosition or
GpiMove, followed by GpiCharString. You supply the text of the character string
as a parameter to the appropriate GPI function.
Note: You also can call WinDrawText, which draws text to the screen a line at
a time. WinDrawText differs from the GpiCharString... functions in that
WinDrawText ignores the DM_RETAIN drawing mode and can only be used to
draw to a window device context.
The following figure shows some examples of a character string primitive.
The Character String Primitive
This example shows the string Presentation Manager drawn from different
logical fonts.
ΓòÉΓòÉΓòÉ 4.1.11. Font Files and Dynamic-Link Libraries ΓòÉΓòÉΓòÉ
You can use the Font Editor to alter and customize image-font files. Files
created with the Font Editor have a .FNT extension. After you create a custom
font, put it into a dynamic-link library (DLL) that the application can load.
Once the application loads this library, it can use any of the custom fonts the
library contains.
DLLs that contain fonts are unique; they contain data segments and empty (or
useless) code segments. They are unique because they contain no executable
code, unlike normal DLLs. Also you are able to install the font file as a
public font if desired; GpiLoadFonts will make it available only as a private
font. The operating system naming convention for a DLL that contains font
information end with a .FON extension.
To create a DLL, you must use an assembler, a linker, and the operating system
Resource Compiler. For this example, assume that your custom font file is named
NEWFONT.FNT.
After creating your custom font file, you need to create a special assembler
language file with your editor. Call this file MYFONT.ASM, for example. The
following figure shows an example of the source code for this file.
code segment word ;Makes dummy code segment aligned on word boundary
db "empty_segment" ;Initializes a string in dummy segment
code ends ;Dummy segment ends here
end ;Terminates source file
After you have created MYFONT.ASM, assemble it by using the following command:
masm myfont
After assembling the MYFONT.ASM file, create a module-definition file. Call
this file MYFONT.DEF, for example. It should contain the statements in the
following figure.
LIBRARY myfont
SEGMENTS CODE MOVEABLE
The first statement tells the linker that you are creating a library with the
module name, MYFONT. The second statement tells the linker that the segments in
this library are movable code segments.
After creating MYFONT.DEF, start the linker with the command in the following
figure.
link myfont,,,,myfont.def
This command creates an empty executable file called MYFONT.EXE.
After creating the empty executable file, which is the template for a DLL,
create a resource file and call it MYFONT.RC. For example, if your font file is
called NEWFONT.FNT, you would place the statement in the following figure in
MYFONT.RC.
FONT 200 NEWFONT.FNT
This statement assigns the identifier, 200, to the font resource NEWFONT.FNT.
Finally, use the Resource Compiler to add the font file (NEWFONT.FNT) to the
empty DLL as in the following figure.
rc myfont.rc
The executable file, MYFONT.EXE, now contains your custom fonts. After you have
renamed this file, MYFONT.FON, you can load the fonts into your application
using GpiLoadFonts and pass it a pointer to the path and library name as the
second argument-for example, c:\os2\dll\myfont.fon.
ΓòÉΓòÉΓòÉ 4.2. Using Fonts ΓòÉΓòÉΓòÉ
You can use the font functions to:
Determine the characteristics of available fonts
Select a font for text output
Delete or unload a font when finished
Create a font
Create marker sets and pattern sets
Use a bit map as a fill pattern
Use a clip path as a fill pattern
ΓòÉΓòÉΓòÉ 4.2.1. Selecting a Font ΓòÉΓòÉΓòÉ
Every presentation space has a current font, and graphics characters must be
drawn in that font. By default, the current font is the system font. Before an
application can use any font other than the system font, it has to identify the
other font as the new current font.
There are two distinct ways to identify the other font:
Call GpiQueryFonts to request information about the available physical
fonts, and then explicitly select one of those fonts by supplying its
identifier as input to GpiCreateLogFont.
This process has 11 steps and is covered in the topic "Explicit Font
Selection." This method of selecting a font is most useful for selecting
image fonts.
If you must have an image font, you are urged to use this "explicit
selection"method, because you need to specify a maximum baseline extent
and an average character width in the FATTRS structure. These values can
be determined only by calling GpiQueryFonts. If you specify values that
are not valid, you are likely to be given an outline font.
Use GpiCreateLogFont to specify the features you require in a font, and
permit the PM programming interface to make an appropriate font available
to you.
This process has two steps and is covered in the topic "Closest Matching
Font Selection."
ΓòÉΓòÉΓòÉ 4.2.1.1. Explicit Font Selection ΓòÉΓòÉΓòÉ
An application can select either a public or a private font with
GpiCreateLogFont. A public font is available to all applications. A private
font is loaded by an application for its exclusive use.
Use the Presentation Manager Control Panel to load a public font. Four DLLs
contain the Times Roman, Helvetica, Courier, and System Monospaced image fonts.
The names of these libraries are:
TIMES.FON
HELV.FON
COURIER.FON
SYSMONO.FON
Unlike most DLLs, font libraries typically use the file name extension .FON.
If the user loads all four libraries, a total of 76 public fonts are
available. An application can use both outline and image formats of these
fonts. Characters in the image format are available in sizes ranging from 8 to
24 points. Characters in the outline format can be any size.
Call GpiLoadFonts to load a private font. Pass the function the path and name
of the DLL that contains the font. After the application loads the DLL of
fonts, it can determine the characteristics of the fonts in that library by
calling GpiQueryFonts.
To select a public font from all of the available public fonts, do the
following:
1. Call GpiQueryFonts. passing the QF_PUBLIC flag, a NULL pointer to the
font's face name, and a count of 0 to determine the number of available
public fonts, as shown in the following figure.
#define INCL_GPILCIDS
#include <os2.h>
void fncFONT06(void){
FONTMETRICS fm, afm[80];
LONG cFonts = 0, cPublicFonts;
HPS hps;
cPublicFonts = GpiQueryFonts(hps, /* Queries all public fonts */
QF_PUBLIC,
(PSZ) NULL,
&cFonts,
sizeof(fm),
(PFONTMETRICS) NULL);
} /* fncFONT06 */
Note: To load and use a private font, follow the same procedure, but
specify QF_PRIVATE, instead of QF_PUBLIC, in the calls to GpiQueryFonts.
2. Copy the value returned by GpiQueryFonts into a LONG integer variable.
3. Allocate memory for the FONTMETRICS data structures.
4. Call GpiQueryFonts again, passing the QF_PUBLIC flag, a NULL pointer to
the font's face name, the count returned by the previous call, and the
address of an array of FONTMETRICS structures.
GpiQueryFonts the font metrics of every font available the array of
FONTMETRICS structures. The font metrics define in detail the physical
characteristics of a font.
Because the font metrics are so detailed, the amount of information
returned to you from GpiQueryFonts can be extensive. You can restrict the
amount of information returned by this function by:
Specifying an absolute number of fonts about which you require
information.
Asking for information about fonts of a specific face name only.
Limiting the length of the font-metrics buffer.
If you request information for more fonts than are available on the
system, GpiQueryFonts returns all the information about the available
fonts and a value indicating how many fonts it has returned.
If you request information for fewer fonts than are available on the
system (that match the specified face name, and so forth), GpiQueryFonts
returns a value indicating the number of fonts that it was unable to
return.
The following figure is an example of this technique of selecting a font.
#define INCL_GPILCIDS
#include <os2.h>
PFONTMETRICS fncFONT07 (HPS hps, PLONG pcPublicFonts) {
PFONTMETRICS afm = NULL;
LONG fonts = 1000;
*pcPublicFonts = GpiQueryFonts(hps,
QF_PUBLIC,
(PSZ) NULL,
&fonts,
sizeof(*afm),
(PFONTMETRICS) NULL);
if (!DosAllocMem(&afm,
sizeof(*afm)*(*pcPublicFonts),
PAG_COMMIT | PAGWRITE )) {
GpiQueryFonts(hps,
QF_PUBLIC,
(PSZ) NULL,
pcPublicFonts,
sizeof(*afm),
afm);
} /* endif */
return afm;
}
5. Examine the array of FONTMETRICS structures.
a. For an outline font, examine the face name and other attributes of
the font your application requires.
b. For an image font, examine the device resolution fields. These
fields are the ones that determine if a particular font and its
metrics match the device with which you wish to use it.
Note: If your application is interactive, organize the face names and
other information relevant to those fonts (such as point sizes) in a
menu. When the operator has selected a font, supply the relevant
information from the font metrics of that font in the FATTRS structure of
GpiCreateLogFont.
6. After determining which font to use, your application must fill in the
fields of the FATTRS structure. Some of the data for these fields will be
copied (explicitly) from the FONTMETRICS structure. Then call
GpiCreateLogFont.
If you do not supply a face name, the default font is used. If you
supply a face name, and the presentation driver cannot find a matching
font, a default font is selected.
The FATTRS structure describes a logical font. An application can have up
to 254 logical fonts defined at any one time in a single presentation
space. A logical font is a list of font attributes, whereas a physical
font is the bit-map or vector information that the system uses to draw
characters.
7. The fonts supplied by the PM programming interface, the fonts you load
using the Control Panel, and any fonts you load with GpiLoadFonts are all
physical fonts.
Copying the entries in the FATTRS structure ensures that, if a particular
font is unavailable, an attempt is made to find the most suitable
substitute. Without the FATTRS information, PM is less likely to locate a
suitable font.
8. Initialize a local identifier (lcid) for the new font.
9. Call GpiCreateLogFont and pass as input parameters:
The lcid for the font
The address of an 8-character array containing the name you want to
give to the logical font, (or, if you do not want to specify a name,
the value NULL)
The address of the FATTRS structure
10. Examine the return value from GpiCreateLogFont. The value will be 2 if
the function is successful; 1, if the default font was used.
11. Pass the lcid to GpiSetCharSet, assigning the font to your application's
presentation space. Then the application can use it for text output.
(This step identifies a logical font as the current font.)
The following figure shows how to select an image font at least 14 device
coordinate units high.
#define INCL_GPILCIDS
#include <os2.h>
LONG fncFONT08(HPS hps, LONG lcid, LONG xres, LONG yres) {
FATTRS fat;
PFONTMETRICS afm;
LONG cFonts;
LONG i;
LONG rc = 0;
afm = fncFONT07(hps, &cfonts);
if (amf) {
for (i=0; 1<cfonts; i++) {
if (!(afm[i].fsDefn & FM_DEFN_OUTLINE)
afm[i].sXDeviceRes == xres &&
afm[i].sYDeviceRes == yres &&
afm[i].lMaxBaselineExt >= 14) {
fat.usRecordLength = sizeof(fat);
fat.fsSelection = 0;
fat.lMatch = 0;
strcpy(fat.szFacename, afm[i].szFacename);
fat.idRegistry = afm[i].idRegistry;
fat.usCodePage = 0;
fat.lMaxBaselineExt = afm[i].lMaxBaselineExt;
fat.lAveCharWidth = afm[i].lAveCharWidth;
fat.fsType = 0;
fat.fsFontUse = 0;
rc = GpiCreateLogFont(hps, (PSTR8) NULL, lcid, &fat);
if (rc) {
GpiSetCharSet(hps, lcid);
} /* endif */
} /* endfor */
} /* endif */
return rc;
}
GpiQueryFonts returns device coordinates for image fonts. For outline fonts,
it returns notional coordinates. Notional coordinates are the coordinate in
which the font was defined. Usually outline fonts are defined over a
1000-by-1000 matrix, with the unit of the matrix a 1/1000 of the em height.
ΓòÉΓòÉΓòÉ 4.2.1.2. Reassociating the Presentation Space ΓòÉΓòÉΓòÉ
The match value of any device font is guaranteed to be unique only for the
current device. If you associate the presentation space with a different device
context, any logical fonts that also are device fonts are no longer available.
On the new device, the match number could identify a different device font
(which may not be suitable) or no font at all. Therefore, you should redefine a
logical font and select it as the current font if you reassociate the
presentation space when the current font is a device font. Otherwise, the
default font is used.
If you do not intend to use the font on the new device, however, you need not
redefine it. You will be able to continue using the font if you reassociate the
presentation space with the original device context.
Any generic fonts can continue to be used after the presentation space is
reassociated if they are suitable for the new device. An image font, for
example, can be used only on devices that are all-points addressable.
ΓòÉΓòÉΓòÉ 4.2.1.3. Font Resolution ΓòÉΓòÉΓòÉ
Device fonts, particularly printer fonts, usually are designed for a specific
resolution, namely the resolution of the device on which they are to be used.
By contrast, generic outline fonts are not device-specific. Generic image fonts
are designed for a particular resolution value and, therefore, are really
applicable only to devices with a matching resolution value.
The horizontal and vertical font resolution values for the device are returned
by DevQueryCaps. The desired horizontal and vertical device resolution values
in the font metrics of the font concerned are returned by GpiQueryFonts.
Compare these the device and the desired resolution values only for an image
font. If they are identical then this image font is designed for use with this
device (for example, the point size in the font metrics will be accurate for
this device). To select a font, do the following:
1. Query the available fonts using GpiQueryFonts.
2. If you want an outline font, search the metrics of fonts returned by
GpiQueryFonts for a font that is an outline font and that has the
required face name.
3. If you want an image font, search the metrics of the fonts returned by
GpiQueryFonts for a font that is an image font and that has the
following:
Required face name
Required point size
Horizontal device resolution font metric that matches the horizontal
resolution for the device
Vertical device resolution font metric that matches the vertical
resolution for the device.
4. As an alternative to the above for an image font, search the metrics of
the fonts returned by GpiQueryFonts for a font that is an image font and
that has the following:
Required face name
Required em height in world coordinates.
Before you define a logical font, determine the resolution of the current
device by using DevQueryCaps with the CAPS_VERTICAL_FONT_RES and
CAPS_HORIZONTAL_FONT_RES parameters.
Compare the values returned from this function with the xDeviceRes and
yDeviceRes values in the font metrics of the available fonts. These two values
contain the resolution of the device for which the font was designed. All
measurements are in pels per inch. By comparing the font resolution with the
device resolution, you can identify the image font best suited to the current
device.
ΓòÉΓòÉΓòÉ 4.2.1.4. Closest-Matching Font Selection ΓòÉΓòÉΓòÉ
The alternative to selecting a specific font is to set the match value to 0. To
have the Presentation Manager programming interface select the closest-matching
font available, do the following:
1. Define a logical font with GpiCreateLogFont. This function establishes a
link between the calling application and an appropriate physical font.
GpiCreateLogFont accepts a number of options as input, including the font
attributes, which describe the physical features and capabilities of the
font.
2. Complete the FATTRS structure of GpiCreateLogFont. The FATTRS structure
describes a logical font, which the system uses to find the closest
matching physical font. Depending on whether you are selecting a font
using a match number, fill in the FATTRS structure, observing the rules
listed in the following table.
Filling in the FATTRS Structure
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIf using a match number ΓöéIf not using a match number Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSet the match number to the ΓöéSet the match number to zero. Γöé
Γöérequired FONTMETRICS value. Γöé Γöé
ΓöéThe FONTMETRICS value is the ΓöéIf your font is an image font:Γöé
Γöévalue in the FONTMETRICS Γöé Γöé
Γöéstructure for the required ΓöéSet the maximum baseline Γöé
Γöéfont returned by GpiQueryFontsΓöéextent to the required Γöé
Γöé. ΓöéFONTMETRICS value. Γöé
Γöé Γöé Γöé
ΓöéSet the maximum baseline ΓöéSet the average character Γöé
Γöéextent to zero. Γöéwidth to the required Γöé
Γöé ΓöéFONTMETRICS value. Γöé
ΓöéSet the average character Γöé Γöé
Γöéwidth to zero. Γöé Γöé
Γöé Γöé Γöé
ΓöéNote: A negative lMatch is Γöé Γöé
Γöéonly unique for a device. A Γöé Γöé
Γöépositive lMatch is only uniqueΓöé Γöé
Γöéon a particular system at a Γöé Γöé
Γöéparticular time. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Also observe the rules concerning the font-use indicator that are listed
in the following table.
Font-Use Indicator Considerations
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIf you have not set the ΓöéIf you have set the Γöé
ΓöéFATTR_FONTUSE_OUTLINE ΓöéFATTR_FONTUSE_OUTLINE Γöé
Γöéindicator: Γöéindicator: Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPM looks for an image font ΓöéPM looks for a suitable Γöé
Γöéthat has the required Γöéoutline font whose selection Γöé
Γöéselection indicators and whoseΓöéindicators match those you Γöé
Γöémaximum baseline extent and Γöéhave specified. Γöé
Γöéaverage character width match Γöé Γöé
Γöéthose you have specified. ΓöéIf no suitable outline font isΓöé
Γöé Γöéfound, the default font is Γöé
ΓöéIf no suitable image font is Γöéused. No attempt is made to Γöé
Γöéfound, PM looks for an outlineΓöésubstitute an image font. Γöé
Γöéfont with the required face Γöé Γöé
Γöéname and selection indicators.Γöé Γöé
Γöé Γöé Γöé
ΓöéIf no suitable outline font isΓöé Γöé
Γöéfound, the default font is Γöé Γöé
Γöémade available to you. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Outline fonts are affected by the current character attributes (for example,
character box, shear, and angle). Because an outline font might be made
available to you, even when you requested an image font, call
GpiQueryFontMetrics to determine whether the font is an image font or an
outline font. GpiQueryFontMetrics returns the metrics of the current logical
font in world coordinates.
The setting of the definition indicators in the FONTMETRICS structure tell you
whether the font is either an image or outline font, or a device or generic
font. If the font is an outline font, specify values for the character
attributes before using the font. Outline fonts are unaffected by the maximum
baseline extent and average character width values specified in
GpiCreateLogFont.
If the default font provided is an image font, and you also have specified
FATTR_FONTUSE_TRANSFORMABLE, any attempt to draw graphics characters in
CM_MODE3 raises an error condition. This is an exception to the general rule
that a FATTR_FONTUSE_TRANSFORMABLE font must be used in CM_MODE3 only.
ΓòÉΓòÉΓòÉ 4.2.2. Selecting the New Current Font ΓòÉΓòÉΓòÉ
In addition to completing the FATTRS structure, you must supply as input to
GpiCreateLogFont a unique lcid for the font. The identifier is a number in the
range of 1 through 254. Because you can have more than one logical font
definition in a presentation space, you must select the current font by
supplying the font's lcid as input to GpiSetCharSet.
You do not have to call GpiSetCharSet to use the default font. When you want to
reset the current font to its default value, however, call GpiSetCharSet with
the value LCID_DEFAULT. The current font, like other modal attributes, reverts
automatically to its default value when specific GPI functions are called.
ΓòÉΓòÉΓòÉ 4.2.3. Deleting Logical Fonts and Unloading Physical Fonts ΓòÉΓòÉΓòÉ
A logical font can be used only by the application that defines it. The logical
font definition is stored in the presentation space and is saved on the LIFO
stack with its lcid when GpiSavePS is called. Unlike a physical font
definition, a logical font definition is temporary and is lost when the
presentation space is deleted.
To specifically delete a logical font, call GpiDeleteSetId, which deletes the
logical font, and makes its lcid available for reuse. Sometimes this is
necessary because there are only 255 lcids available. The logical font must not
be the current font when you call GpiDeleteSetId.
Logical fonts are deleted to release the lcid and free memory. Unload private
fonts using GpiUnloadFonts to free memory and to make them no longer available.
Uninstall public fonts using the Control Panel to free memory and to make them
no longer available.
You must end the association between physical and logical fonts before calling
GpiUnloadFonts.
If you call GpiUnloadFonts to unload a private font file, you must end the
association between the physical fonts in that file and the logical fonts
defined by the application. Do the following:
Call GpiSetCharSet to select a current font (such as the default font)
that is not linked to the physical fonts you are unloading
Call GpiDeleteSetId to delete each logical font that refers to any of the
physical fonts in the font resource file. If you fail to do this, an
error is returned to your application from GpiUnloadFonts.
*GpiUnloadFonts.
ΓòÉΓòÉΓòÉ 4.2.4. Creating Fonts ΓòÉΓòÉΓòÉ
You cannot edit the definitions of any of the PM-provided fonts, although you
can create and edit image-font files using the Font Editor. A font file
contains a header, that describes the font in general terms and a section
containing bit maps of the characters themselves. The font definition is stored
in a resource file.
ΓòÉΓòÉΓòÉ 4.2.5. Creating Marker Sets and Pattern Sets ΓòÉΓòÉΓòÉ
Like character sets, marker sets and pattern sets are defined in fonts. For
both marker sets and pattern sets, there are system-provided defaults. You also
can create your own image markers or patterns, but not outline markers or
patterns, using the Font Editor. The font definition containing the image or
pattern can be loaded either as a public font (using the Install selection from
the Control Panel) or as a private font (using GpiLoadFonts). The current
character mode has no effect on marker sets and pattern sets. Any character
from a font can be used as a marker or as an area-fill pattern.
Before you can use a locally defined marker set or pattern set, you must call
GpiCreateLogFont to define a logical font and to give it an lcid, just as you
would for a character font. Most of the values you can specify with
GpiCreateLogFont are not applicable to marker sets and pattern sets.
Furthermore, in the instance of marker sets and pattern sets, you usually know
that you want to use a particular font.
To select a locally defined marker set or pattern set:
1. Call GpiQueryFonts to obtain a match value for the font.
2. Call GpiCreateLogFont, specifying the face name, match value, and lcid
for the font.
3. Select the logical font as the current marker set or pattern set by
calling GpiSetMarkerSet or GpiSetPatternSet, as appropriate.
To revert to using the default pattern or marker sets, call GpiSetPatternSet
or GpiSetMarkerSet with the value LCID_DEFAULT.
ΓòÉΓòÉΓòÉ 4.2.6. Using Bit Maps as Area-Fill Patterns ΓòÉΓòÉΓòÉ
An alternative to using the Font Editor to create your own pattern sets is to
use a bit map as an area-fill pattern. You must call GpiSetBitmapId to give the
bit map an lcid, and then call GpiSetPatternSet, specifying the lcid of the bit
map. The bit map becomes a pattern set containing one pattern, and the current
pattern-symbol attribute is ignored. GpiQueryBitmapHandle returns the handle of
the bit map currently known by the lcid that you supply as input.
PM cannot distinguish among the lcids associated with a particular presentation
space. Any lcid can identify a character set, marker set, pattern set, or bit
map (that is being used as an area-fill pattern). For example, if you call
GpiQueryNumberSetIds to determine how many lcids are currently assigned in the
presentation space, the number returned to you includes all logical fonts
defined for this presentation space. You also can use GpiDeleteSetId to remove
lcids associated with the non-font entities. If you call this function to
delete a bit map that is being used as an area-fill pattern, the bit map itself
is not deleted. However, it is disassociated from its lcid, and the lcid can be
reused.
ΓòÉΓòÉΓòÉ 4.2.7. Using Paths with Fill Patterns ΓòÉΓòÉΓòÉ
Using paths lets you fill a character string with a complicated or nonrepeating
pattern. The following sequence is recommended:
Select the required outline font, and set the required character
attributes.
Create a path by calling GpiBeginPath, GpiCharString, and GpiEndPath.
Set the required pattern symbol and other AREABUNDLE pattern attributes.
Fill the path using GpiFillPath.
The following figure provides an example of using paths with fill patterns to
create characters.
Using Clip Paths to Create Characters
ΓòÉΓòÉΓòÉ 4.3. Font-File Format ΓòÉΓòÉΓòÉ
The OS/2 font-file format consists of two sections. The first section contains
the general attributes of the font, and describes features such as its
typeface, style, and nominal size. The second section contains the actual
definitions of the characters belonging to the font.
The font resource is a set of self-defining records of the form:
typedef struct _RECORD {
ULONG ulIdentity; /* structure identity code */
ULONG ulSize; /* structure size in bytes */
. /* data */
.
.
} RECORD;
A font starts with a special font-signature structure and ends with an ending
structure. The font signature has the form:
typedef struct _FONTSIGNATURE {
ULONG ulIdentity;
ULONG ulSize;
CHAR achSignature [12]
} FONTSIGNATURE;
Where:
ulIdentity 0xFFFFFFFE
ulSize 20
achSignature "OS/2 FONT" for an OS/2 1.x format font, or
"OS/2 FONT 2" for an OS/2 2.x format font.
A 2.x format font includes additional font description information in the
PANOSE structure. This structure will be added to the end of the .FNT file
(prior to the ENDFONT record).
The font end structure has the form:
typedef struct _ENDFONT{
ULONG ulIdentity;
ULONG ulSize;
}ENDFONT
Where:
ulIdentity 0xFFFFFFFF
ulSize 8
All records should be in the order of their identity fields.
There are three or four records in a font resource between the font signature
and the font end:
The font metrics
The font character definitions
The pair kerning table.
The PANOSE description (for "OS/2 FONT 2" fonts).
Following compilation, the records in the resource are in the order defined
above.
ΓòÉΓòÉΓòÉ 4.3.1. Metric Information Contained in Fonts ΓòÉΓòÉΓòÉ
This section gives an explanation of how to set the fields of the FOCAMETRICS
structure when developing:
A bit map or outline font for general use by PM graphics applications
A description of a bit map or outline device font that is built in to a
device or can be downloaded to a device.
The following structure contains the physical font metrics used when creating
fonts. It is defined in the file \INCLUDE\PMFONT.H.
typedef struct _FOCAMETRICS {
ULONG ulIdentity;
ULONG ulSize;
CHAR szFamilyname[32];
CHAR szFacename[32];
SHORT usRegistryId;
SHORT usCodePage;
SHORT yEmHeight;
SHORT yXHeight;
SHORT yMaxAscender;
SHORT yMaxDescender;
SHORT yLowerCaseAscent;
SHORT yLowerCaseDescent;
SHORT yInternalLeading;
SHORT yExternalLeading;
SHORT xAveCharWidth;
SHORT xMaxCharInc;
SHORT xEmInc;
SHORT yMaxBaselineExt;
SHORT sCharSlope;
SHORT sInlineDir;
SHORT sCharRot;
USHORT usWeightClass;
USHORT usWidthClass;
SHORT xDeviceRes;
SHORT yDeviceRes;
SHORT usFirstChar;
SHORT usLastChar;
SHORT usDefaultChar;
SHORT usBreakChar;
SHORT usNominalPointSize;
SHORT usMinimumPointSize;
SHORT usMaximumPointSize;
SHORT fsTypeFlags;
SHORT fsDefn;
SHORT fsSelectionFlags;
SHORT fsCapabilities;
SHORT ySubscriptXSize;
SHORT ySubscriptYSize;
SHORT ySubscriptXOffset;
SHORT ySubscriptYOffset;
SHORT ySuperscriptXSize;
SHORT ySuperscriptYSize;
SHORT ySuperscriptXOffset;
SHORT ySuperscriptYOffset;
SHORT yUnderscoreSize;
SHORT yUnderscorePosition;
SHORT yStrikeoutSize;
SHORT yStrikeoutPosition;
SHORT usKerningPairs;
SHORT sFamilyClass;
PSZ pszDeviceNameOffset;
} FOCAMETRICS;
Note: FOCAMETRICS is a parallel structure with FONTMETRICS as returned to
applications in the GpiQueryFonts and GpiQueryFontMetrics function
calls.
The FONTMETRICS fields are derived from FOCAMETRICS by the Presentation
Manager graphics engine. Most values are passed though unchanged. The
exceptions are:
The Identity field. This must be 1. This field is not a part of the
FONTMETRICS structure.
The Size field. This must be set to the size of the FOCAMETRICS
structure. This field is not a part of the FONTMETRICS structure.
The Codepage field. Ignore the description in FONTMETRICS, and use the
following:
Place 850 in this field if the font is intended to support any PM
supported code page.
Place 65400 in this field if the font has special glyphs, for
example if it is a Symbol font.
Place other valid code pages in this field if the font is specific
to this code page.
Do not place other values in this field.
FONTMETRICS fields which contain values in world coordinates. The
corresponding field in FOCAMETRICS should contain pel values for bit-map
fonts, and notional units for outline fonts.
See FONTMETRICS for a detailed explanation of the fields.
ΓòÉΓòÉΓòÉ 4.3.2. Font Character Definitions ΓòÉΓòÉΓòÉ
Two formats of font character definition are supported. These are:
Image format The character glyphs are represented as pel images.
Outline format The character glyphs are represented by vector data that
traces the outline of the character.
Note: Intelligent Font Technology fonts (such as ATM Type-1
fonts) may be stored in a technology specific format,
and thus will not conform to this definition for
outline fonts.
The definition consists of a header portion and a portion carrying the
characters themselves.
The header portion contains information about the format of the character
definitions and data about each character including width data and the offset
into the definition section at which the character definition begins. (See
Definitions of Terms Used When Describing Fonts.)
1. Proportional characters (a+b+c = character increment) for each character:
a,b,c >= 0
2. Characters where a, b, and c are definitions for all characters:
b >= 0
a, c any integer
Raster fonts contain a "null character". The character definition record for
this occurs after the one for the last character. Thus the format has
usLastChar+2 characters, although the null character is not counted in the
range returned. The null character is composed of zeros and is always eight
pels wide.
ΓòÉΓòÉΓòÉ 4.3.2.1. Font Definition Header ΓòÉΓòÉΓòÉ
This structure defines the format or the character definition records that
follow it:
typedef struct_FONTDEFINITIONHEADER {
ULONG ulIdentity;
ULONG ulSize;
SHORT fsFontdef;
SHORT fsChardef;
SHORT usCellSize;
SHORT xCellWidth;
SHORT yCellHeight;
SHORT xCellIncrement;
SHORT xCellA;
SHORT xCellB;
SHORT xCellC;
SHORT pCellBaseOffset;
} FONTDEFINITIONHEADER;
typedef FONTDEFINITIONHEADER FAR *PFONTDEFINITIONHEADER;
Where:
ulIdentity
4 bytes.
Must be equal to 2.
ulSize
4 bytes.
Size of this structure in bytes.
fsFontdef
2 bytes of flags.
Indicates which fields are present in the font definition data in the
header.
Type 1
Bit 0 1 = width defined in header
Bit 1 1 = height defined in header
Bit 2 1 = char increment same as width, so that it is defined for
the whole font
Bit 3 0 = a-space not defined
Bit 4 0 = b-space not defined
Bit 5 0 = c-space not defined
Bit 6 1 = base offset same for all characters.
Type 2
Bit 0 0 = width for each character unique
Bit 1 1 = height defined in header
Bit 2 0 = char increment same as width, so that it is unique for
each character
Bit 3 0 = a-space not defined
Bit 4 0 = b-space not defined
Bit 5 0 = c-space not defined
Bit 6 1 = base offset same for all characters.
Type 3
Bit 0 0 = width for each character unique
Bit 1 1 = height defined in header
Bit 2 0 = char increment same as width, so that it is unique
Bit 3 0 = a-space not defined
Bit 4 0 = b-space not defined
Bit 5 0 = c-space not defined
Bit 6 1 = base offset same for all characters.
FsChardef
2 bytes of flags.
Indicates which fields are present on a per character basis.
Type 1
Bit 0 1 = width defined for each character (performance op)
Bit 1 0 = height is in header
Bit 2 0 = char increment is in header
Bit 3 0 = a-space not defined
Bit 4 0 = b-space not defined
Bit 5 0 = c-space not defined
Bit 6 0 = base offset defined in header
Bit 7 1 = offset to glyph defined.
Type 2
Bit 0 1 = width defined for each character
Bit 1 0 = height is in header
Bit 2 0 = char increment same as width
Bit 3 0 = a-space not defined
Bit 4 0 = b-space not defined
Bit 5 0 = c-space not defined
Bit 6 0 = base offset defined in header
Bit 7 1 = offset to glyph defined.
Type 3
Bit 0 1 = width not defined, use a, b, c
Bit 1 0 = height is in header
Bit 2 0 = char increment same as width
Bit 3 1 = a-space defined
Bit 4 1 = b-space defined
Bit 5 1 = c-space defined
Bit 6 0 = base offset defined in header
Bit 7 1 = offset to glyph defined.
usCellSize
2-byte integer.
Indicates the length in bytes of each character definition record (the per
character data).
Type 1 6 bytes
Type 2 6 bytes
Type 3 10 bytes.
xCellWidth
2-byte integer
The width of the characters, in pels for image fonts, and relative units
for outline fonts.
Type 1 Width of the characters
Type 2 Zero
Type 3 Zero.
yCellHeight
2-byte integer.
The height of the characters, in pels for image fonts, and relative units
for outline fonts.
Type 1 Height of the characters
Type 2 Height of the characters
Type 3 Height of the characters.
xCellIncrement
2-byte integer.
The distance along the character baseline required to step from one
character to the next (when forming a character string).
Type 1 Width of the characters
Type 2 Zero
Type 3 Zero.
xCellA
2-byte signed integer.
The width of the space before a character in the inline direction (the
a-space).
Type 1 Zero
Type 2 Zero
Type 3 a-space for all characters.
xCellB
2-byte integer.
The width of a character (inline direction). The b-space.
Type 1 Zero
Type 2 Zero
Type 3 b-space for all characters.
xCellC
2-byte signed integer.
The width of the space after a character in the inline direction (the
c-space).
Type 1 Zero
Type 2 Zero
Type 3 c-space for all characters.
pCellBaseOffset
2-byte signed integer.
The position of the top of a character definition relative to the baseline
in the direction perpendicular to the baseline.
Type 1 Baseline offset for all characters
Type 2 Baseline offset for all characters
Type 3 Baseline offset for all characters.
Character Definition Record
xCellSize bytes per record.
The following fields may or may not be present, according to the font
character definition fields flags. If a field is present, it is present for
each character and the value applies to that character only.
There are usLastChar+2 such records for raster fonts. The final one is for
the null character.
Character Definition Offset: 4-byte integer.
The offset into the Font File at which the character definition
begins.
Data for a single character raster or vector should not span two
segments; that is, if a character is too big to fit into a segment it
should be put in the next segment.
This field should be set to zero if the character being defined is a
blank character.
Character Cell Width: 2-byte integer.
The width of the character definition in pels.
Character Cell Height: 2-byte integer.
The height of the character definition in pels.
Character Increment: 2-byte integer.
The length along the character baseline required to step from this
character to the next (when forming a character string).
Character a-space: 2-byte signed integer.
The width of the space before the character in the inline direction.
Character b-space: 2-byte integer.
The width of the character shape (inline direction).
Character c-space: 2-byte signed integer.
The width of the space after the character in the inline direction.
Character Baseline Offset: 2-byte signed integer.
The position of the top of a character definition relative to the
baseline in the direction perpendicular to the baseline.
Note: Type 1 fonts have offset/width pairs (like type 2); however, the
usCellSize and xCellIncrement are nonzero. In the fsType field of the
font metrics, the proportional-space flag, bit 0, is set.
ΓòÉΓòÉΓòÉ 4.3.2.2. Image Data Format ΓòÉΓòÉΓòÉ
The bits for each character are stored separately, and start on a byte
boundary. Sequential bytes represent vertical pieces of the character image.
For example, a 15-bit-wide H is stored as follows:
Byte Byte
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
1 Γöé 00000000 Γöé 0000000- Γöé 13 Bytes 1 through 12 are composed of
2 Γöé 01100000 Γöé 0000110- Γöé 14 whole bytes of data stored row by row.
3 Γöé 01100000 Γöé 0000110- Γöé 15
4 Γöé 01100000 Γöé 0000110- Γöé 16 Bytes 13 through 24 are composed of
5 Γöé 01100000 Γöé 0000110- Γöé 17 bytes stored row by row, where each byte
6 Γöé 01111111 Γöé 1111110- Γöé 18 contains 7 bits of information and the
7 Γöé 01111111 Γöé 1111110- Γöé 19 last bit is unused.
8 Γöé 01100000 Γöé 0000110- Γöé 20
9 Γöé 01100000 Γöé 0000110- Γöé 21 Thus the character is laid down in
10 Γöé 01100000 Γöé 0000110- Γöé 22 byte-wide columns.
11 Γöé 01100000 Γöé 0000110- Γöé 23
12 Γöé 00000000 Γöé 0000000- Γöé 24
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Notes:
1. There is always an additional (null) character defined in an Image Font
(defined at character position LastChar+2) which is 8 bits wide, the
height of the font character, and set to all zeros.
2. The maximum size of each individual Image Font must not exceed 64KB.
ΓòÉΓòÉΓòÉ 4.3.3. The Kerning Pair Table ΓòÉΓòÉΓòÉ
The kerning pair table record is not present if the _KerningPairs record in the
metrics is zero. If it is present, the code points are words, not bytes. This
table should be sorted by kpChar1 and kpChar2 order to allow binary searches.
typedef struct _KERNPAIRTABLE {
ULONG ulIdentity;
ULONG ulSize;
CHAR cFirstpair;
}KERNPAIRTABLE;
typedef struct _KERNPAIRS {
SHORT sFirstChar;
SHORT sSecondChar;
SHORT sKerningAmount;
}KERNINGPAIRS;
Where:
ulIdentity 3
ulSize 10
sFirstChar First character of the kerning pair.
sSecondChar Second character of the kerning pair.
sKerningAmount Kerning value. Positive values increase the inter-character
spacing while negative values bring the characters closer
together.
Outline Data Format
Fonts defined by outlines (vectors) may contain any of these graphics orders:
Line at given position (GLINE)
Line at current position (GCLINE)
Relative line at given position (GRLINE)
Relative line at current position (GCRLINE)
Fillet at given position (GFLT)
Fillet at current position (GCFLT)
Sharp fillet at given position (GSFLT)
Sharp fillet at current position (GCSFLT)
Bezier curve at given position (GBEZ)
Bezier curve at current position (GCBEZ)
No operation (GNOP1)
Comment (GCOMT)
End of symbol definition (GESD).
The maximum length of the data in these orders is 255 bytes. The drawing order
code and the length fields are not included in the length count.
The size of each outline font definition must not be longer than 64KB.
ΓòÉΓòÉΓòÉ 4.3.4. Additional Metrics ΓòÉΓòÉΓòÉ
The additional metrics structure extends the metrics describing the font to
include the PANOSE fields. The fields allow for quantitative descriptions of
the visual properties of font faces. The format of the ADDITIONALMETRICS
structure is:
typedef struct {
ULONG ulIdentity;
ULONG ulSize;
PANOSE panose;
} ADDITIONALMETRICS;
Where:
ulIdentity 4
ulSize 20
panose The ten digit PANOSE number with two bytes of padding.
The PANOSE definition consists of ten digits, each of which describes one of
up to sixteen variations. The current digits are:
1. Family Kind (6 variations)
0 = Any
1 = No Fit
2 = Text and Display
3 = Script
4 = Decorative
5 = Pictorial
2. Serif Style (16 variations)
0 = Any
1 = No Fit
2 = Cove
3 = Obtuse Cove
4 = Square Cove
5 = Obtuse Square Cove
6 = Square
7 = Thin
8 = Bone
9 = Exaggerated
10 = Triangle
11 = Normal Sans
12 = Obtuse Sans
13 = Perp Sans
14 = Flared
15 = Rounded
3. Weight (12 variations)
0 = Any
1 = No Fit
2 = Very Light
3 = Light
4 = Thin
5 = Book
6 = Medium
7 = Demi
8 = Bold
9 = Heavy
10 = Black
11 = Nord
4. Proportion (10 variations)
0 = Any
1 = No Fit
2 = Old Style
3 = Modern
4 = Even Width
5 = Expanded
6 = Condensed
7 = Very Expanded
8 = Very Condensed
9 = Monospaced
5. Contrast (10 variations)
0 = Any
1 = No Fit
2 = None
3 = Very Low
4 = Low
5 = Medium Low
6 = Medium
7 = Medium High
8 = High
9 = Very High
6. Stroke Variation (9 variations)
0 = Any
1 = No Fit
2 = Gradual/Diagonal
3 = Gradual/Transitional
4 = Gradual/Vertical
5 = Gradual/Horizontal
6 = Rapid/Vertical
7 = Rapid/Horizontal
8 = Instant/Vertical
7. Arm Style (12 variations)
0 = Any
1 = No Fit
2 = Straight Arms/Horizontal
3 = Straight Arms/Wedge
4 = Straight Arms/Vertical
5 = Straight Arms/Single Serif
6 = Straight Arms/Double Serif
7 = Non-Straight Arms/Horizontal
8 = Non-Straight Arms/Wedge
9 = Non-Straight Arms/Vertical
10 = Non-Straight Arms/Single Serif
11 = Non-Straight Arms/Double Serif
8. Letterform (16 variations)
0 = Any
1 = No Fit
2 = Normal/Contact
3 = Normal/Weighted
4 = Normal/Boxed
5 = Normal/Flattened
6 = Normal/Rounded
7 = Normal/Off Center
8 = Normal/Square
9 = Oblique/Contact
10 = Oblique/Weighted
11 = Oblique/Boxed
12 = Oblique/Flattened
13 = Oblique/Rounded
14 = Oblique/Off Center
15 = Oblique/Square
9. Midline (14 variations)
0 = Any
1 = No Fit
2 = Standard/Trimmed
3 = Standard/Pointed
4 = Standard/Serifed
5 = High/Trimmed
6 = High/Pointed
7 = High/Serifed
8 = Constant/Trimmed
9 = Constant/Pointed
10 = Constant/Serifed
11 = Low/Trimmed
12 = Low/Pointed
13 = Low/Serifed
10. X-height (8 variations)
0 = Any
1 = No Fit
2 = Constant/Small
3 = Constant/Standard
4 = Constant/Large
5 = Ducking/Small
6 = Ducking/Standard
7 = Ducking/Large
When using the PANOSE number to match fonts, the ordering of the PANOSE digit
is the key to finding the closest match. The most significant digit is the
first digit, and the least significant digit is number ten. To find matches,
the digits need to be compared, in the order given. A font mapper may want to
change the precedence of the digits, to give higher weightings to other font
features.
ΓòÉΓòÉΓòÉ 4.3.5. Font Directory ΓòÉΓòÉΓòÉ
This section describes the directory section of a font resource. A font
resource contains a directory consisting of a set of structures each containing
the metrics of a font and a pointer to the font itself. This font directory is
generated by the resource compiler.
The format of the font directory is:
typedef struct {
USHORT usHeaderSize;
USHORT usnFonts;
USHORT usiMETRICS;
FONTENTRY fntEntry[1];
} FONTDIRECTORY;
typedef struct {
USHORT usIndex;
FONTFILEMETRICS metrics;
} FONTENTRY;
Where:
usHeaderSize The size of the header, in bytes.
usnFonts The number of fonts in the resource.
usiMetrics The size of the FOCAMETRICS structures that follow the header.
Note that the set of metrics for all the fonts in the resource
follow the header.
usIndex The index of a particular font; an identifier assigned to the
font when the resource was created (defined in the .RC file).
metrics The font metrics structure for the font. This is identical to a
FOCAMETRICS structure with the addition of the PANOSE fields to
the end.
ΓòÉΓòÉΓòÉ 4.3.6. Definitions of Terms Used When Describing Fonts ΓòÉΓòÉΓòÉ
a-space, b-space, c-space - The a-space is the distance from the left of the
character frame to the left edge of the character. The b-space is the width
of the character. The c-space is the distance from the right edge of the
character to the right of the character frame. Negative values of a and c
allow adjacent character frames to overlap. See also character increment,
and space default values.
average char width - The average horizontal distance from the left edge of one
character to the left edge of the next. Contrast with max char increment.
baseline - The line on which the bottom of a character rests, and below which
a descender extends.
beak char code point - The code point of the space or break character.
Contrast with default char code point, first char code point, and last char
code point.
character increment - A set of three values (a-space, b-space, and c-space)
that define the proportions of a character. The sum of the three values
(a+b+c) specifies only one value for the entire character increment. See
also font width and space default values.
character rotation - The angle by which each character is rotated around its
own center, increasing clockwise from vertical. Contrast with character
slope and inline direction.
character slope - The angle by which a character is slanted, increasing
clockwise from vertical. Contrast with character rotation and inline
direction.
default char code point - The code point of the character to be used if a code
point outside the range of a font is passed to an application using that
font. Contrast with break char code point, first char code point, and last
char code point.
em height - The maximum distance above the baseline reached by an uppercase
symbol. Contrast with x height.
external leading - The vertical distance from the bottom of one character to
the top of the character below it. Contrast with internal leading and max
baseline extent.
first char code point - The code point of the first character. All numbers
between the first char code point and the last char code point must
represent a character in the font. Contrast with break char code point,
default char code point, and last char code point.
fixed spacing - The same amount of space separates each character. Contrast
with proportional spacing.
font weight - The line-thickness of a character relative to its size. Contrast
with font width.
font width - The relative width of a character to its height; condensed fonts
are very narrow while expanded fonts are very wide. See also character
increment. Contrast with font weight.
inline direction - The angle of a line of type, increasing clockwise from
horizontal. Contrast with character rotation and character slope.
internal leading - The vertical distance from the top or bottom of a character
to any accent marks that may appear with it. Contrast with external leading.
last char code point - The code point of the last character. All numbers
between the first char code point and the last char code point must
represent a character in the font. Contrast with break char code point,
default char code point, and first char code point.
lowercase ascent - The maximum distance above the baseline reached by any part
of any lowercase character. Contrast with maximum ascender and x height.
lowercase descent - The maximum distance below the baseline reached by any
part of any lowercase character. Contrast with maximum descender.
max baseline extent - The maximum space occupied by the font (typically, the
sum of the maximum ascender and maximum descender). Contrast with external
leading and max char increment.
max char increment - The maximum horizontal distance from the left edge of one
character to the left edge of the next character to the right. Contrast with
average char width and max baseline extent.
maximum ascender - The maximum distance that any part of any character may
extend above the x height of a font. Contrast with lowercase ascent and
maximum descender.
maximum descender - The maximum distance that any part of any character may
extend below the x height of a font. Contrast with lowercase descent and
maximum ascender.
maximum vert point size - The maximum vertical dimensions to which a font can
be resized. Contrast with minimum vert point size and nominal vert point
size.
minimum vert point size - The minimum vertical dimensions to which a font can
be resized. Contrast with maximum vert point size and nominal vert point
size.
nominal vert point size - The normal display size of a font. Contrast with
maximum vert point size and minimum vert point size.
pel - The smallest element of a display surface that can be independently
assigned color and density.
point - Printer's unit of measurement. There are 72 points to an inch
(approximately 3.5 points to a millimeter).
proportional spacing - The space that each character occupies is in proportion
to its width. See also font width. Contrast with fixed spacing.
Registry ID - A code number that Presentation Manager uses to register a font
file as a resource.
space default values - Values that specify the space to be left between
characters. Once defined, they are used for the entire font, and do not have
to be specified for each character. However, they can be changed for
characters that require more or less spacing than the defaults provide, by
giving values for the a Space and the c Space. See also character increment.
strikeout position - The distance of the strikeout character above the
baseline (in pels). See also strikeout size and underscore position.
strikeout size - The size of the strikeout character (in points). See also
strikeout position and underscore size.
subscript position - The distance of a subscript character of a font below the
baseline (in pels). See also subscript size and superscript position.
subscript size - The size of a subscript character (in points). See also
subscript position and superscript size.
superscript position - The distance of a superscript character above the
baseline (in pels). See also subscript position and superscript size.
superscript size - The size of a superscript character (in points). See also
subscript size and superscript position.
target dev resolution X - The number of pels per inch in the horizontal axis
of a display device on which a font is to be displayed. Contrast with target
dev resolution Y.
target dev resolution Y - The number of pels per inch in the vertical axis of
a display device on which a font is to be displayed. Contrast with target
dev resolution X.
underscore position - The distance in pels of the first underscore stroke from
the baseline of a font. Successive strokes below this create a heavier
underscore. See also strikeout position and underscore size.
underscore size - The size of the underscore character measured in single
strikeout strokes. See also strikeout size and underscore position.
x height - The maximum distance above the baseline reached by a lowercase
character. Contrast with em height and lowercase ascent.
ΓòÉΓòÉΓòÉ 5. Graphics Attributes ΓòÉΓòÉΓòÉ
Every graphics presentation space has a set of graphics attributes. A normal
presentation space has a larger set of graphics attributes than a micro or
cached micro presentation space. (Segment-related attributes, for example, do
not apply in micro presentation spaces.) These attributes all have default
values, which means that they always have an effect on graphics, even if you
have not explicitly specified their values. The attributes can be broken into
two general groups. The first group comprises those attributes that form a part
of the picture and that can vary as the picture is drawn. These are:
All primitive attributes
The segment attributes
The primitive tag
The current position
The viewing window
The clipping path
The model and segment transformations
The viewing transformation.
With the exception of the segment attributes and the viewing transformation,
these attributes are reset to their default values at the start of a root
segment, unless the fast-chaining attribute is set. If the fast-chaining
attribute is set, their values cannot be guaranteed. You should, therefore,
explicitly set any attribute values required in the segment. Similarly, the
values of these attributes cannot be guaranteed following a call to:
Any GpiDraw... function
Any GpiCorrelate... function
GpiCallSegmentMatrix
GpiCloseSegment
Therefore, if any of these functions is followed by primitives outside a
segment, you should explicitly set required attribute values. When
GpiCloseSegment is followed by GpiOpenSegment (and also between any two
segments in the chain), the fast-chaining attribute determines what happens to
the current values of these attributes. The viewing transformation and the
segment attributes are unaffected by fast-chaining.
These attributes take effect when graphics are sent to an output device, not
when graphics are defined. For this reason, the calls to GpiQuery... that
retrieve the current values of these attributes are invalid in retain mode.
The majority of the group-one attribute-setting functions cause graphics
orders to be added to the current segment.
The second group of attributes defines the environment in which the picture is
drawn. These attributes do not normally vary as the picture is drawn, but have
an overall effect on the result of any drawing or correlation operation. This
group includes:
The default viewing transformation
The page viewport
The graphics field
The clipping region
The pick-aperture size
The drawing controls.
The functions to GpiQuery... that retrieve the current values of these
attribute are valid in all drawing modes. None of the group-two
attribute-setting functions causes graphics orders to be added to the current
segment.
The following table lists the graphics attributes, identifies the GPI function
or functions that you use to change current settings, and lists the default
value of each one. Note that these default values are the initial settings.
The table also indicates whether the attribute is a group-one or a group-two
attribute.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéGraphics ΓöéGPI Function ΓöéDefault Value ΓöéGroupΓöéGroupΓöé
ΓöéAttribute Γöé Γöé ΓöéOne ΓöéTwo Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéArc parametersΓöéGpiSetArcParams Γöé(1,1,0,0) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground ΓöéGpiSetColor(1) ΓöéCLR_DEFAULT ΓöéYes Γöé Γöé
Γöécolor Γöé Γöé(device-dependent) Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground mixΓöéGpiSetMix(1) ΓöéFM_DEFAULT (overpaint) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground ΓöéGpiSetBackColor(1) ΓöéCLR_DEFAULT ΓöéYes Γöé Γöé
Γöécolor Γöé Γöé(device-dependent) Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground mixΓöéGpiSetBackMix(1) ΓöéBM_DEFAULT (leave-alone) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter ΓöéGpiSetCharAngle(1) Γöé(1,0) ΓöéYes Γöé Γöé
Γöéangle Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter box ΓöéGpiSetCharBox(1) ΓöéDevice-dependent ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter ΓöéGpiSetCharDirection(1) ΓöéCHDIRN_DEFAULT (left to ΓöéYes Γöé Γöé
ΓöéDirection Γöé Γöéright) Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter modeΓöéGpiSetCharMode(1) ΓöéCM_DEFAULT (mode 1) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter set ΓöéGpiSetCharSet(1) ΓöéLCID_DEFAULT (system font) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter ΓöéGpiSetCharShear(1) Γöé(0,1) ΓöéYes Γöé Γöé
Γöéshear Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLine end ΓöéGpiSetLineEnd(1) ΓöéLINEEND_DEFAULT (flat) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLine join ΓöéGpiSetLineJoin(1) ΓöéLINEJOIN_DEFAULT (beveled) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLine type ΓöéGpiSetLineType(1) ΓöéLINETYPE_DEFAULT (solid) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLine width ΓöéGpiSetLineWidth(1) ΓöéLINEWIDTH_DEFAULT (1.0) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGeometric lineΓöéGpiSetLineWidthGeom(1) Γöé1 ΓöéYes Γöé Γöé
Γöéwidth Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMarker ΓöéGpiSetMarker(1) ΓöéMARKSYM_DEFAULT (cross) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMarker box ΓöéGpiSetMarkerBox(1) ΓöéDevice-dependent ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMarker set ΓöéGpiSetMarkerSet(1) ΓöéLCID_DEFAULT (system marker ΓöéYes Γöé Γöé
Γöé Γöé Γöéset) Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern ΓöéGpiSetPattern(1) ΓöéPATSYM_DEFAULT (solid) ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern ΓöéGpiSetPatternRefPoint(1) Γöé(0,0) ΓöéYes Γöé Γöé
Γöéreference Γöé Γöé Γöé Γöé Γöé
Γöépoint Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern set ΓöéGpiSetPatternSet(1) ΓöéLCID_DEFAULT (system pattern ΓöéYes Γöé Γöé
Γöé Γöé Γöéset) Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéModel ΓöéGpiSetModelTransformMatrix ΓöéIdentity ΓöéYes Γöé Γöé
ΓöétransformationΓöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInstance ΓöéGpiCallSegmentMatrix ΓöéIdentity ΓöéYes Γöé Γöé
ΓöétransformationΓöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSegment ΓöéGpiSetSegmentTransformMatrix ΓöéIdentity ΓöéYes Γöé Γöé
ΓöétransformationΓöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéViewing ΓöéGpiSetViewingTransformMatrix ΓöéIdentity ΓöéYes Γöé Γöé
ΓöétransformationΓöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDefault ΓöéGpiSetDefaultViewMatrix ΓöéIdentity Γöé ΓöéYes Γöé
Γöéviewing Γöé Γöé Γöé Γöé Γöé
ΓöétransformationΓöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPage viewport ΓöéGpiSetPageViewport ΓöéDevice-dependent Γöé ΓöéYes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéClipping path ΓöéGpiSetClipPath ΓöéNo clipping ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéViewing windowΓöéGpiSetViewingLimits ΓöéNo clipping ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGraphics fieldΓöéGpiSetGraphicsField ΓöéNo clipping Γöé ΓöéYes Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéClipping ΓöéGpiSetClipRegion ΓöéNo clipping Γöé ΓöéYes Γöé
Γöéregion Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTag ΓöéGpiSetTag Γöé0 ΓöéYes Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSegment ΓöéGpiSetInitialSegmentAttrs ΓöéATTR_DETECTABLE - OFF ΓöéYes Γöé Γöé
Γöéattributes ΓöéGpiSetSegmentAttrs ΓöéATTR_VISIBLE - ON Γöé Γöé Γöé
Γöé Γöé ΓöéATTR_CHAINED - ON Γöé Γöé Γöé
Γöé Γöé ΓöéATTR_DYNAMIC - OFF Γöé Γöé Γöé
Γöé Γöé ΓöéATTR_FASTCHAIN - ON Γöé Γöé Γöé
Γöé Γöé ΓöéATTR_PROP_DETECTABLE - ON Γöé Γöé Γöé
Γöé Γöé ΓöéATTR_PROP_VISIBLE - ON Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPick-aperture ΓöéGpiSetPickAperturePosition ΓöéDevice-dependent Γöé ΓöéYes Γöé
Γöésize Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
│Current │GpiSetCurrentPosition GpiMove¤│(0,0) │Yes │ │
Γöéposition Γöé Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDrawing ΓöéGpiSetDrawControl ΓöéDCTL_ERASE - OFF Γöé ΓöéYes Γöé
Γöécontrols Γöé ΓöéDCTL_DISPLAY - ON Γöé Γöé Γöé
Γöé Γöé ΓöéDCTL_BOUNDARY - OFF Γöé Γöé Γöé
Γöé Γöé ΓöéDCTL_DYNAMIC - OFF Γöé Γöé Γöé
Γöé Γöé ΓöéDCTL_CORRELATE - OFF Γöé Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Notes:
(1). Can also be set using GpiSetAttrs.
(2). Is also updated indirectly by most primitive-drawing functions.
Each of the following functions causes all group-one and group-two graphics
attributes to be set to their default values:
GpiCreatePS
GpiSetPS
GpiResetPS, if GRES_ALL or GRES_SEGMENTS is specified
WinGetPS
WinGetScreenPS
WinBeginPaint, with a NULL presentation space handle.
In specific circumstances, some of the GPI functions modify the group-one
attributes and thus make their values unpredictable. Therefore, when you call
any of these functions, you should respecify attribute values that have a
particular importance to your application. For example, if the current
foreground color is CLR_RED before you call GpiDrawChain you cannot always
rely on the current color remaining CLR_RED when GpiDrawChain completes. If
you want to continue working in red, respecify the color when GpiDrawChain
completes. In general, the functions that affect group-one-attribute values
are those related to the drawing and correlation of retained graphics, and to
the creation, closing, and deletion of graphics segments.
With the exception of the viewing transformation and the segment attributes,
the default values of these attributes apply to all primitive-drawing that
occurs outside a segment bracket.
The following function sets the group-one attributes to their default
values, and in addition sets the current clipping region and page
viewport to their default values.
- GpiAssociate.
Each of the following functions makes the group-one-attribute values
unpredictable:
- GpiCloseSegment
- GpiCorrelateChain
- GpiCorrelateFrom
- GpiCorrelateSegment
- GpiErase
- GpiCallSegmentMatrix
- GpiDrawDynamics
- GpiRemoveDynamics.
Note: In the last two functions here, the foreground-mix value is
always set to FM_XOR, and the background-mix value is always
set to BM_LEAVEALONE.
Each of the following functions makes group-one-attribute values
unpredictable if a segment to be deleted is open when the function is
called:
- GpiDeleteSegments
- GpiDeleteSegment
Each of the following functions makes group-one-attribute values
unpredictable if there is no open segment when the function is called:
- GpiDrawChain
- GpiDrawFrom
- GpiDrawSegment.
If there is an open segment when any of these functions is called, and
that segment was the last one drawn, then group-one-attribute values are
unaffected. If, however, dynamic segments were caused to be redrawn by
the same function, group-one-attribute values are made unpredictable.
This occurs because dynamic segments are always drawn after nondynamic
segments.
ΓòÉΓòÉΓòÉ 6. Line and Arc Primitives ΓòÉΓòÉΓòÉ
Line and arc primitives are graphics building blocks for creating pictures that
consist of objects such as polygons, circles, fillets, ellipses, and other
geometric figures.
The following topics are related to information in this chapter:
Presentation spaces and device contexts
Color and mix attributes
Area primitives
ΓòÉΓòÉΓòÉ 6.1. About Line and Arc Primitives ΓòÉΓòÉΓòÉ
Simple drawing applications use line and arc primitives as drawing tools. They
are useful, for example, in spreadsheet applications for constructing pie
charts, bar charts, and graphs.
Sample Pie Chart Created with Line and Arc Primitives
Following are more illustrations that were drawn using line and arc primitives.
Sample Bar Graph Created with Line and Arc Primitives
Computer-aided-design (CAD) applications combine line and arc primitives to
draw such complex pictures as schematic diagrams for electrical wiring,
blueprints for building sites, and cross-sectional views of machinery.
Sample Blueprint Created with Line and Arc Primitives
Line and arc primitives are actually two families of primitives that contain
many variations of straight lines and curved lines, respectively. They are
presented together in this chapter because all the variations are governed by
the attributes found in the data structure LINEBUNDLE.
An application draws the line and arc primitives by first calling GpiMove or
GpiSetCurrentPosition, either of which sets the current position to a specified
starting point. GpiMove ignores the AM_PRESERVE mode, whereas
GpiSetCurrentPosition saves the current position if the AM_PRESERVE mode is
set. The more sophisticated function, GpiPolyLineDisjoint, contains its own
starting point and does not need to be preceded by GpiMove, or
GpiSetCurrentPosition.
Prior to calling a line or arc function, the current position can be determined
with GpiQueryCurrentPosition.
ΓòÉΓòÉΓòÉ 6.1.1. Attributes of Line and Arc Primitives ΓòÉΓòÉΓòÉ
The attributes of the line and arc primitives contained in LINEBUNDLE are:
Line width
Geometric width
Line type
Line end
Line join
Line color
Line mix
The line end and line join attributes apply only to lines drawn in a primitive
called a path.
When an application creates a presentation space, the line and arc attributes
are set to the default values shown in the following table.
Line Attribute Default Values
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute ΓöéDefault Value ΓöéFunction that Redefines Γöé
Γöé Γöé ΓöéAttribute Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWidth Γöé1.0 ΓöéGpiSetLineWidth Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGeometric widthΓöéNone ΓöéGpiSetLineWidthGeom Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéType ΓöéLINETYPE_SOLIDΓöéGpiSetLineType Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéColor ΓöéCLR_NEUTRAL ΓöéGpiSetAttrs (LBB_COLOR) Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMix attribute ΓöéFM_OVERPAINT ΓöéGpiSetAttrs (LBB_MIX_MODE) Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 6.1.2. Line Width and Geometric Width ΓòÉΓòÉΓòÉ
The operating system defines two types of lines: cosmetic and geometric,
representing two separate concepts.
Cosmetic lines represent the mathematical ideal of a line being an entity with
only one dimension-length. When cosmetic lines are drawn, they usually are only
one pel wide.
The line width attribute provides a visual method of distinguishing different
types of lines. For example, on a map, roads might be drawn thicker than
railroad tracks. The line width attribute defines a multiplier to be applied to
the normal (or default) line width. Your application can determine the cosmetic
line width by calling GpiQueryLineWidth.
There are certain devices that do not define the thickness of cosmetic lines in
terms of a number of pels. The PM interface interprets the specified width for
these devices as shown in the following table:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIdentifer ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEWIDTH_DEFAULT ΓöéThe default width for the device. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEWIDTH_NORMAL ΓöéThe line width equivalent to a Γöé
Γöé Γöémultiplier of 1. Identical to Γöé
Γöé ΓöéLINEWIDTH_DEFAULT unless changed with Γöé
Γöé ΓöéGpiSetDefAttrs. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEWIDTH_THICK ΓöéThe line width equivalent to a Γöé
Γöé Γöémultiplier greater than 1. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Your application can set the cosmetic line width with either a multiplier or an
identifier value using GpiSetLineWidth. Since the line represents a widthless
ideal, the actual drawn width is a fixed value. The line width remains
unchanged when you increase the size of, or zoom in on, a graphics object. The
cosmetic line width is not subject to transformations.
In contrast, geometric lines represent an area whose thickness is equal to the
specified line width. Geometric lines are subject to changes in scale through
transformations, in the same manner as geometric figures.
The width of a geometric line does not have a default value. Width is treated
as a line attribute for programming convenience, but it actually is a geometric
property. A line width is set with GpiSetLineWidthGeom. If a width is already
specified, that width can be determined with GpiQueryLineWidthGeom.
To use geometric line width, the lines are assembled into a path. When you use
a path to define wide lines, you can specify the following:
Geometric width for the lines, using the geometric line width attribute
Style of the line ends, using the line end attribute
Style of the junctions of the lines, using the line join attribute
These three attributes apply only to geometric lines drawn using paths.
ΓòÉΓòÉΓòÉ 6.1.3. Line Types ΓòÉΓòÉΓòÉ
Line type, also called line style, defines the way a line or arc is drawn: as
a solid line, a series of dashes, a series of dots, or a combination of dashes
and dots.
The line type for all subsequent line primitives is selected using
GpiSetLineType. If you want to change the line type to LINETYPE_DOT, for
example, any line or arc primitive subsequently drawn is drawn as a dotted
line. The following table illustrates the nine standard line types provided by
PM.
You cannot define other line types for PM applications.
Standard Line Types
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéType ΓöéIdentifer ΓöéLong Value Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDotted line ΓöéLINETYPE_DOT Γöé1L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéShort-dashed line ΓöéLINETYPE_SHORTDASH Γöé2L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDash-dot line ΓöéLINETYPE_DASHDOT Γöé3L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDouble-dotted line ΓöéLINETYPE_DOUBLEDOT Γöé4L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLong-dashed line ΓöéLINETYPE_LONGDASH Γöé5L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDash-double-dot line ΓöéLINETYPE_DASHDOUBLEDOT Γöé6L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSolid line ΓöéLINETYPE_SOLID Γöé7L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInvisible line ΓöéLINETYPE_INVISIBLE Γöé8L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAlternate pels on ΓöéLINETYPE_ALTERNATE Γöé9L Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The default line type (LINETYPE_DEFAULT) is identical to the LINETYPE_SOLID
type, and has a long value of 0L. The error line type (LINETYPE_ERROR) has a
long value of -1L. The following figure illustrates the nine line types. Your
application can determine the current line type using GpiQueryLineType.
The Nine Line Types
ΓòÉΓòÉΓòÉ 6.1.4. Line Color and Mix Attributes ΓòÉΓòÉΓòÉ
The color attribute defines the color used to draw a primitive or an object.
The mix attribute determines how the color of a primitive or an object is
combined with the color of the drawing surface, or any other objects on the
surface.
The line color defines the color used to draw the output from any of the
operating system's line functions. When a presentation space is created, the
line color initial default is black. Unlike certain other primitives, the line
and arc primitives do not have a background color. The current color of the
drawing surface automatically plays a greater role in the appearance of line
and arc primitives than in those primitives that do have a background color.
Specifically, when an application draws a dotted or dashed line, the color that
appears between the dots or dashes is the current drawing-surface color, as
shown in the following figure.
Line and arc primitives have only a color attribute for the actual line. The
mix attribute controls the combination of line color with drawing surface
color.
Line and Arc Primitives
When a presentation space is created, the line mix attribute initial default is
FM_OVERPAINT. The overpaint mix attribute specifies that the line color is not
modified by the color of the drawing surface. If the line mix attribute is
changed, the line color is mixed with colors that are already on the drawing
surface.
To specify a new color or mix attribute use GpiSetAttrs. This function accepts
as input the type of primitive, for example PRIM_LINE, a list of attributes
that are to be changed, a list of attributes that are to be set to their
default values, and the values for the attributes that are to be changed.
GpiSetAttrs is useful for specifying colors and mix attributes just for a
specific data structure (for example, the LINEBUNDLE structure). GpiSetAttrs
also provides some protection against invalid colors.
To determine the current line color and mix attribute, use GpiQueryAttrs. This
function accepts as input the primitive type and the attributes in question. It
returns as output an array of values for the specifically queried attributes.
To reset the default line color and mix attribute, just as with any other
attribute specified in the LINEBUNDLE data structure, use GpiSetDefAttrs. This
function accepts as input the type of primitive, for example PRIM_LINE, the
attributes to be changed, and the values that will become the new default
values. The changing of default values is important when working with segments.
Changing the default values during a series of drawing functions is not
recommended.
The line color and mix attribute also can be specified with GpiSetColor and
GpiSetMix, respectively. However, those two functions have the disadvantage of
specifying the color and mix attribute for all primitive BUNDLE data structures
that have a component for foreground color and foreground mix attribute. The
queries, GpiQueryColor and GpiQueryMix, determine the color and mix attribute
as specified by GpiSetColor and GpiSetMix. If the line color or mix attribute
is specified individually, the aforementioned queries can return a value
inconsistent with the current line color or mix attribute.
ΓòÉΓòÉΓòÉ 6.1.5. Line Primitive Family ΓòÉΓòÉΓòÉ
The following table describes the three variants of the basic line primitive
and the functions that draw them.
Functions that Draw Straight Lines
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéVariants ΓöéFunction ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLines ΓöéGpiLine ΓöéDraws a single line from the Γöé
Γöé Γöé Γöécurrent position to a specified Γöé
Γöé Γöé Γöépoint. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPolylines ΓöéGpiPolyLine ΓöéDraws a series of connected lines,Γöé
Γöé Γöé Γöéfrom the current position through Γöé
Γöé Γöé Γöésuccessive points. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(series of ΓöéGpiPolyLineDisjoint ΓöéDraws a series of unconnected Γöé
Γöélines) Γöé Γöélines. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBoxes ΓöéGpiBox ΓöéDraws a rectangular box with one Γöé
Γöé Γöé Γöécorner at the current position. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
When the operating system draws a line, it includes the pels at the starting
and ending points of the line. The algorithm used to draw the rest of the line
depends on the device driver. For example, a driver for a raster device might
use a modified Bresenham algorithm to draw a line, but a driver for a vector
device, such as a plotter, simply would connect the starting and ending points
of the line. In all cases, the result is a line primitive that looks the same
from device to device.
ΓòÉΓòÉΓòÉ 6.1.5.1. Lines ΓòÉΓòÉΓòÉ
GpiLine draws a line from the current position to a specified end point, as
shown in the following figure. After drawing the line, the current position is
at the end point specified by GpiLine.
GpiLine
The current position is (4,3), and the specified end point of GpiLine is (9,7).
When the line has been drawn, (9,7) becomes the current position.
To draw a single point, you can use GpiLine with an end point identical to the
current position, as shown in the following figure. The current position can be
determined using GpiQueryCurrentPosition.
GpiLine Used to Draw a Single Point
ΓòÉΓòÉΓòÉ 6.1.5.2. Polylines ΓòÉΓòÉΓòÉ
GpiPolyLine draws a sequence of connected lines, starting at the current
position and passing through a series of specified coordinate positions, as
shown in the following figure. After drawing the series of lines, the current
position is at the end point of the last line specified by GpiPolyLine.
If you are drawing a graph that has five connected lines, you can use
GpiPolyLine once rather than GpiLine five times. GpiPolyLine accepts as input a
number of points and an array of point coordinates.
GpiPolyLine
The starting position is (2,2), and the polyline is drawn through (4,4), (6,4),
(8,6), and (10,3). The new current position is (10,3).
GpiPolyLineDisjoint is a new function that eliminates having to use a series of
GpiMove and GpiLine functions to draw multiple lines that are not connected.
GpiPolyLineDisjoint accepts as input an even number, the number of points, and
an array of point coordinates. The first point in a point-pair is the starting
point; the second, the end point of that line segment. Upon completion, the end
point of the final line becomes the current position. The following figure
shows the results of a GpiPolyLineDisjoint call.
GpiPolyLineDisjoint
A graph with discontinuities.
ΓòÉΓòÉΓòÉ 6.1.5.3. Boxes ΓòÉΓòÉΓòÉ
At its simplest, GpiBox draws a rectangular box with one corner at the current
position and the diagonally-opposite corner at a position that you specify. The
sides of the box are parallel to the x- and y-axes. Like GpiPolyLine, GpiBox
lets you draw a number of connected lines using a single function rather than
four separate GpiLine, functions. The current position is unchanged by GpiBox.
Note: The start and end position of any closed shape are always the same.
Therefore the current position is unchanged after drawing a closed figure. The
GpiBox primitive is shown in the following figure.
The Box
The current position is (3,2) and the corner position is at (8,6). When the
box has been drawn, the current position remains at (3,2).
In addition to the corner position, GpiBox accepts as input an option for
rounded corners and for filled interior. The PM programming interface rounds
the corners of a box by drawing an elliptical section in place of the square
corner. Two GpiBox parameters, IHRound and IVRound, represent the horizontal
and vertical length of the full axis of the ellipse used to round each corner.
If the two values are equal, a quarter-circle is used for the rounding. If the
two values are 0, no rounding is performed. The following figure shows an
example of rounding corners using a quarter-circle. Quarter-Circle Box-Corner
Rounding
The current position is (20,20). GpiBox is called with a corner position of
(65,60) and an identical vertical and horizontal rounding value of 26.
The following figure shows the complete result. The intermediate steps are not
visible to the user of your application.
Box with Rounded Corners
All four corners are rounded with identical values.
Since GpiBox can be used to define a closed figure, it also accepts as input a
long value signifying a filled interior. The long value lControl can be any of
the following:
Value Description
DRO_OUTLINE Draw the box only.
DRO_FILL Fill the box interior only.
DRO_OUTLINEFILL Draw the box and fill its interior.
The pattern that fills the interior and other drawing options are controlled
by the data structure AREABUNDLE. GpiFullArc is the only other line and arc
primitive that can be used to define a closed figure.
ΓòÉΓòÉΓòÉ 6.1.6. Attributes of Arc Primitives ΓòÉΓòÉΓòÉ
The arc primitive shares width, type, and color and mix attributes with line
primitives. For example, if you use GpiSetLineType to change the line type to
LINETYPE_DASHDOT, all subsequent arcs are drawn with a dash-dot line. In
addition to the line attributes defined in the LINEBUNDLE data structure, arc
primitives in the simple-arc family are influenced by the values in the
ARCPARAMS data structure. Arc primitives in the multiple-arc family have a
different method of construction and are not influenced by ARCPARAMS.
In terms of geometrical pictures, the simple arcs contain full or partial:
Circles Closed curves whose center is equidistant from every point on
the curve.
Ellipses Closed curves defined by two fixed points such that the sum of
the distances from any point on the curve to the two fixed
points is constant.
Multiple arcs contain:
Fillets Curves that are tangential to the two lines defined by three
control points.
Splines Curves that, given four control points, are tangent to the
first and last of three intersecting lines.
There are three simple arc operations that begin with a unit circle that lies
at the origin of world coordinate space. This unit circle defines the current
arc on which subsequent full, partial, and 3-point arcs are based. Your
application can define the following attributes of the current arc with
GpiSetArcParams:
Shape
Orientation
Size
Drawing direction
GpiSetArcParams accepts as input an ARCPARAMS data structure that has four
parameters (p, q, r, and s). Of the four:
p scales in the x-direction
q scales in the y-direction
r and s are shear components
The mathematical origins of the parameters are illustrated in the following
figure.
The ARCPARAMS Values in World Coordinates
The values were derived from the major and minor axis of an ellipse.
An application can determine the current arc parameters with
GpiSetDefArcParams which copies the current arc parameters to their
corresponding fields in the supplied ARCPARAMS structure. The application can
set the arc parameters with GpiSetArcParams. This function accepts as input a
copy of the ARCPARAMS structure that contains the new arc parameters. The
default values of p, q, r, and s, unless changed by GpiSetArcParams, define a
unit circle:
p and q are 1
r and s are 0.
The arc parameters define a transformation that is applied to each point on
the perimeter of the unit circle. For any point (x,y) on the perimeter of the
unit circle, there exists a new point (x',y'), as determined by the following
two linear equations:
x' = p x x + r x y
y' = s x x + q x y
These parameters form a 2-by-2 matrix,
Γöî ΓöÉ
Γöé p r Γöé
Γöé s q Γöé
Γöö Γöÿ
that scales and shears simple arcs.
This transformation matrix is not related to the general transformation
functions that move objects through coordinate spaces. It is a special purpose
matrix that transforms the shape and size of the imaginary unit circle. The
transformed unit circle, also called the current arc, is then used to define
the shape and size of the simple arc functions in world coordinates.
After an arc has been described in world coordinates, it can be transformed
with the transformation functions, just as any other primitive can.
A transformation is orthogonal when:
(p x r) + (s x q) = 0
If orthogonal, the line from the origin (0,0) to the point (p,s) is either:
The radius of a circle
Half the major or minor axis of an ellipse;
and, the line from the origin to the point (r,q) is either:
The radius of a circle
Half the minor or major axis of an ellipse.
An orthogonal transformation does not guarantee that the shape of an object as
defined by an application will be the same as the shape of the object on the
output device. For example, if the page units in the application are PU_PELS,
and the pels on the device are rectangular (but not square), calling
GpiFullArc produces an ellipse-not a circle- even when the arc parameters are
set to their default values.
The product of the 2-by-2 matrix multiplication influences the direction of
any arc based on the current arc, except a 3-point arc. The following table
illustrates this directional influence.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIf... ΓöéGpiFullArc and GpiPartialArc Γöé
Γöé Γöé... Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(p x q) is greater than (r x ΓöéDraw the ellipse Γöé
Γöés) Γöécounterclockwise. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(p x q) is less than (r x s) ΓöéDraw the ellipse clockwise. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(p x q) equals (r x s) ΓöéDraw a straight line rather Γöé
Γöé Γöéthan an ellipse. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 6.1.7. Simple-Arc Primitive Family ΓòÉΓòÉΓòÉ
The following table describes the three variants of a simple-arc primitive and
the functions that draw them. All are defined, to some extent, by the current
arc parameters. As with line primitives, an application draws simple-arcs by
first using GpiMove or GpiSetCurrentPosition to set the current position.
Functions that Draw Simple Arcs
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéVariants ΓöéFunction ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFull arcs ΓöéGpiFullArc ΓöéDraws a circle or an ellipse. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPartial arcsΓöéGpiPartialArc ΓöéDraws a straight line followed by Γöé
Γöé Γöé Γöéa section of a circle or ellipse. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé3-point arcsΓöéGpiPointArc ΓöéDraws an arc through three points.Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 6.1.7.1. Full Arcs ΓòÉΓòÉΓòÉ
GpiFullArc draws a complete circle or ellipse with its center at the current
position. The current position remains unchanged. Whether GpiFullArc draws a
circle or an ellipse depends on the current arc parameters. When the current
arc is a circle, GpiFullArc draws a circle; when it is an ellipse, GpiFullArc
draws an ellipse.
ΓòÉΓòÉΓòÉ 6.1.7.1.1. Defining an Ellipse ΓòÉΓòÉΓòÉ
To define an ellipse as the current arc, use GpiSetArcParams where the values
(p,s) and (r,q) are the world coordinates of the end points of the major and
minor axes of the ellipse. For example, current arc parameters of (18,0) and
(0,10) define an ellipse with a major axis of 36 coordinate units and a minor
axis of 20 coordinate units. The resultant ellipse is shown in the following
figure.
The Ellipse
For maximum accuracy, create the axes of an ellipse so that they are at
right-angles to each other. You can check this by ensuring that the following
equation is always true:
p x r + s x q = 0
So, to check the above example:
0 x 18 + 10 x 0 = 0
You also can define a tilted ellipse as the current arc. None of the current
arc parameters for a tilted ellipse will be 0, though you should still ensure
that the axes of the ellipse are at right-angles to each other. The following
figure shows a tilted ellipse defined with current arc parameters of (8,6) and
(-3,4).
Tilted Ellipse
ΓòÉΓòÉΓòÉ 6.1.7.1.2. Defining a Circle ΓòÉΓòÉΓòÉ
To define a circle as the current arc, (r,q) and (p,s) can be any such value
that they lie on a circle. For example, if (r,q) and (p,s) are set to (-4, 3)
(3,4), the current arc is a circle with a radius of 5 coordinate units. For
simplicity, a circle can be defined by specifying current arc parameters where
p is the radius of the circle, and p = q, r = 0, and s = 0. For example, to
define a circle centered on the origin and with a radius of 10 world-coordinate
units, use GpiSetArcParams with the values (0,10) (10,0).
The default values of the current arc parameters are (0,1) (1,0), which define
a circle with a radius of one world-coordinate unit (a unit circle).
GpiFullArc Input Parameters
GpiFullArc accepts as input a multiplier value, so that the size of the full
arc is increased or decreased in relation to the current arc. For example, if
the current arc parameters define an ellipse whose major axis is 20 coordinate
units and whose minor axis is 8 coordinate units, a multiplier of 2 in
GpiFullArc creates an ellipse whose major axis is 40 coordinate units and whose
minor axis is 16 coordinate units.
Because the arc parameters are integers when a fraction is required, for
example when rotating an ellipse, greater precision can be obtained by scaling
up the required arc parameter values as much as possible, then using a
multiplier smaller than 1 to scale the ellipse back down to the required size.
With the default arc parameters defining a circle of 1 world coordinate unit,
you can draw a circle of any size by allowing the arc parameters to default,
then specifying the radius of the circle with the GpiFullArc multiplier. For
example, to draw a circle with a radius of 12 coordinate units, call GpiFullArc
with a multiplier of 12 and allow the GpiSetArcParams to default. Since
GpiFullArc, like GpiBox, can be used to define a closed figure, it also accepts
as input a long value signifying a filled interior. The long value, IControl,
can be:
Value Description
DRO_OUTLINE Draw the arc only.
DRO_FILL Fill the arc interior only.
DRO_OUTLINEFILL Draw the arc and fill its interior.
The pattern that fills the interior and other drawing options are controlled
by the data structure AREABUNDLE. See Area and Polygon Primitives for detailed
information on using areas.
The Full Arc
(a) is a tilted ellipse that is defined by the current arc parameters. (b) is
drawn using GpiFullArc with:
A multiplier value that reduces the size of the arc relative to the
current arc
An IControl value filling the interior with the current area-fill
pattern, but not drawing the arc's outline.
ΓòÉΓòÉΓòÉ 6.1.7.2. Partial Arcs ΓòÉΓòÉΓòÉ
A partial arc is a section of a full arc defined by the current arc parameters.
To draw a partial arc, use GpiPartialArc, which draws two separate figures. The
first figure is a straight line from the current position to the starting point
of a partial arc, and the second figure is the partial arc itself. When the arc
has been drawn, the new current position is at the end point of the partial
arc.
GpiPartialArc accepts as input the center of the current full arc, of which the
partial arc is a part, specified in world coordinates. You also can specify a
multiplier value to increase or decrease the size of the partial arc in
relation to the current full arc.
You also must specify two positive fixed values: a start angle and a sweep
angle. If the current full arc is a circle, the start angle is measured
counterclockwise from the x-axis of the circle. The intersection of the start
angle with the full arc, adjusted by the multiplier value, defines the starting
point of the partial arc.
The sweep angle continues the counterclockwise measurement, beginning where the
start angle left off. The intersection of the sweep angle with the full arc,
adjusted by the multiplier value, defines the partial arc.
If the current arc is not a circle, the start and sweep angle are skewed to the
same degree that the ellipse is a skewed circle. The following figure shows how
the partial arc is constructed.
The Partial Arc
A is the start angle; B, the sweep angle. C is the center point; D, the
current position. Arc.EF is the partial arc. F is the new current position.
The inner circle in the previous figure is the arc defined by the current arc
parameters. A multiplier has been specified with GpiPartialArc, so the partial
arc is based on the full arc described by the outer circle. Point C is the
center point specified on GpiPartialArc. Angle A is the start angle, and angle
B is the sweep angle. GpiPartialArc therefore, draws a line from the current
position (point D) to the start of the partial arc (point E). It also draws arc
EF. Point F is the new current position. The arc is drawn counterclockwise
because the current arc parameters define a counterclockwise circle. You can
join points F and D with GpiLine. This line is drawn automatically if you
define the partial arc within a GpiBeginArea and GpiEndArea bracket.
ΓòÉΓòÉΓòÉ 6.1.7.3. 3-Point Arcs ΓòÉΓòÉΓòÉ
GpiPointArc draws an arc from the current position through an intermediate
point to an end point. When the arc is drawn, the current position is at the
end point of the arc. You specify both the intermediate point and the end
point, and these values determine both the size of the arc and the direction in
which it is drawn. The shape and the orientation of a 3-point arc are
determined by the current arc parameters. The following figure shows how a
3-point arc is constructed.
The 3-Point Arc
If the current arc parameters define an ellipse, that ellipse is scaled up or
down to fit the three points of the arc.
When you want the three points of the arc to be points on a circle, allow the
current arc parameters to default so they define a unit circle. You do not need
to use the values p and q to specify the radius of the circle, because the
radius is determined by the relative positions of the three points of the arc.
ΓòÉΓòÉΓòÉ 6.1.8. Multiple-Arc Primitive Family ΓòÉΓòÉΓòÉ
The following table describes the three variants of the simple-arc primitive
and the functions that draw them. As with line primitives, an application draws
simple arcs by first using GpiMove or GpiSetCurrentPosition to set the current
position. The multiple arcs are the most sophisticated of the arc primitives
and their construction does not depend on the current arc parameters.
Functions that Draw Multiple Arcs
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéVariants ΓöéFunction ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFillets ΓöéGpiPolyFillet ΓöéDraws one or more fillets. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé ΓöéGpiPolyFilletSharp ΓöéDraws one or more fillets with Γöé
Γöé Γöé Γöévarying degrees of sharpness. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSplines ΓöéGpiPolySpline ΓöéDraws one or more splines. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 6.1.8.1. Fillets ΓòÉΓòÉΓòÉ
GpiPolyFillet constructs a fillet (a curved line) made up of one or more arcs,
each of which touches a different straight line. You specify the end points of
these straight lines with GpiPolyFillet. The lines are not drawn but are used
to construct the curve.
The fillet starts at the current position and finishes at the end point of the
last line. On the way from the start point to the end point, the fillet is
tangential to all intermediate lines at their midpoints. When the fillet is
drawn, the current position is at the end point of the last construction line.
The following figure is an example of how a fillet is constructed.
The Fillet
The fillet starts at (2,6) and ends at (5,1). The fillet is tangential to the
midpoints of the lines from (2,8) to (6,9), from (6,9) to (9,5), and from (9,5)
to (5,3).
When you supply only two points, the construction lines of the fillet are drawn
from the current position to the first point, and from the first point to the
second point. The fillet is drawn from the current position to the second
point, and is tangential to the construction lines at those same points.
GpiPolyFilletSharp creates a fillet on a series of connected construction
lines. The first fillet in the series is built using two construction lines:
one drawn from the current position to point 1 (the control point), and one
drawn from point 1 to point 2 (the end point). The fillet is drawn from the
current position to the end point, and is tangential to the two construction
lines at those points.
GpiPolyFilletSharp also accepts as input a sharpness value. Sharpness is a
measure of the distance between the fillet and the control point. It is
calculated as shown in the following figure.
Fillet with Sharpness Specified
Point A is the current position, point B is the control point, and point C is
the end point. W is the midpoint of the notional line AC. D is the point at
which the fillet crosses the notional line WB.
The sharpness of the fillet is the value WD / DB. The line WD is 10 coordinate
units, and the line DB is 5 coordinate units; therefore the sharpness value is
2. The sharpness value defines the type of arc. This is shown in the following
table.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéA sharpness value of... ΓöéDefines... Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGreater than 1.0 ΓöéA hyperbola Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEqual to 1.0 ΓöéA parabola Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLess than 1.0 ΓöéAn ellipse Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Subsequent fillets start from the end point of the previous fillet, and are
constructed using the next two lines in the sequence in exactly the same way.
For each fillet you define one control point, one end point, and one sharpness
value. Upon completion, the current position is at the end point of the final
construction line in the sequence.
There might be discontinuity of gradient between multiple fillets drawn with
GpiPolyFilletSharp. To avoid this, ensure that points B and C of one fillet are
on the same construction line as points A and B of the next fillet in the
sequence. This concept is illustrated in connection with the spline primitive
in the figure that follows the next figure. Discontinuity of gradient between
fillets does not occur when the fillets are drawn with GpiPolyFillet.
ΓòÉΓòÉΓòÉ 6.1.8.2. Splines ΓòÉΓòÉΓòÉ
GpiPolySpline creates a succession of one or more Bezier splines. The spline
also is a curve, but its construction method is different from that of the
fillet. As input to this function, you supply three construction points for
each spline. The first spline starts from the current position and ends at the
third specified point. The two intermediate points are control points for the
curve. Subsequent splines start at the end point of the previous spline, have
two intermediary control points, and end at the third control point. The
following figure shows the construction method for the spline.
The Spline
Points (1) and (2) are the control points of the spline, and point (3) is the
end point.
To avoid discontinuity of gradient between the end of one spline and the start
of the next, ensure that the last two construction points of the first spline
and the first two construction points of the second spline are positioned along
a single construction line. This concept is shown in the following figure.
Spline with No Discontinuity of Gradient
The last two points of the first spline (points 2 and 3) are positioned along
the same construction line as the first two points (current position and point
1) of the second spline.
ΓòÉΓòÉΓòÉ 6.2. Using Line and Arc Primitives ΓòÉΓòÉΓòÉ
This section explains how to:
Draw a straight line
Create a "rubber-banding" effect with straight lines or arcs
Draw a circle, ellipse, fillet, or spline
ΓòÉΓòÉΓòÉ 6.2.1. Drawing a Straight Line ΓòÉΓòÉΓòÉ
To draw a straight line, set the current position with GpiMove or
GpiSetCurrentPosition. Set the end point of the line by filling in a POINTL
structure, then draw the line with GpiLine. The following figure shows how to
draw a straight line in a PM application.
#include <os2.h>
BOOL DrawLine(HPS hps, LONG xStart, LONG yStart, LONG xEnd, LONG yEnd){
POINTL ptl; /* Point structure */
ptl.x = xStart; /* Loads starting x-coordinate */
ptl.y = yStart; /* Loads starting y-coordinate */
GpiMove(hps, &ptl); /* Sets current position */
ptl.x = xEnd; /* Loads ending x-coordinate */
ptl.y = yEnd; /* Loads ending y-coordinate */
if (GpiLine(hps, &ptl) == GPI_OK){
return TRUE; /* Draw Line. */
} /* if */
else return FALSE;
} /* DrawLine */
The second argument of GpiMove is the address of a POINTL structure that
contains coordinates of the line's starting point. The second argument of
GpiLine is the address of another POINTL structure that contains the
coordinates of the last point on the line.
ΓòÉΓòÉΓòÉ 6.2.2. Creating a Rubber-Banding Effect with a Straight Line ΓòÉΓòÉΓòÉ
When lines are drawn with a rubber-banding effect, two things happen: the
original line (if one exists) is erased, and a new line is drawn in its place.
This process typically takes place each time the mouse is dragged and continues
until the mouse button is released. The quickest way to erase the original line
(having ensured that it was drawn using mix attribute FM_XOR) is to redraw it
using mix attribute FM_XOR. The following figure shows how to create this
effect.
#define INCL_WININPUT
#define INCL_GPITRANSFORMS
#define INCL_GPIPRIMITIVES
#include <os2.h>
HPS hps; /* Presentation-space handle */
LONG curr_color;
MRESULT EXPENTRY wpGeneric(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
static POINTL ptlStart; /* Starting point of line */
static POINTL ptlNew; /* Ending point of line */
static POINTL ptlPrev; /* Previous end point of line */
static BOOL fDraw; /* Line-drawing flag */
switch (msg) {
case WM_BUTTON1DOWN: /* User begins drawing */
GpiSetColor(hps, CLR_GREEN);
ptlStart.x = (LONG) (LOUSHORT(mp1));
ptlStart.y = (LONG) (HIUSHORT(mp1));
GpiConvert(hps, CVTC_DEVICE, CVTC_WORLD, 1L,
&ptlStart);
ptlPrev.x = ptlStart.x;
ptlPrev.y = ptlStart.y;
GpiMove(hps, &ptlStart);
fDraw = TRUE;
return ((MRESULT) TRUE);
case WM_MOUSEMOVE: /* User draws line */
if (fDraw) {
ptlNew.x = (LONG) (LOUSHORT(mp1));
ptlNew.y = (LONG) (HIUSHORT(mp1));
GpiConvert(hps, CVTC_DEVICE, CVTC_WORLD, 1L, &ptlNew);
curr_color = GpiQueryColor(hps);
GpiSetMix(hps, FM_XOR);
if ((ptlStart.x != ptlPrev.x)
|| (ptlStart.y != ptlPrev.y)) {
GpiMove(hps, &ptlStart);
GpiLine(hps, &ptlPrev);
} /* if */
if ((ptlStart.x != ptlNew.x)
|| (ptlStart.y != ptlNew.y)) {
GpiMove(hps, &ptlStart);
GpiLine(hps, &ptlNew);
ptlPrev.x = ptlNew.x;
ptlPrev.y = ptlNew.y;
} /* if */
GpiSetMix(hps, FM_OVERPAINT);
} /* if */
return ((MRESULT) TRUE);
case WM_BUTTON1UP: /* User stops drawing */
fDraw = FALSE;
return ((MRESULT) TRUE);
} /* switch */
} /* wpGeneric */
ΓòÉΓòÉΓòÉ 6.2.3. Drawing a Circle ΓòÉΓòÉΓòÉ
When drawing a circle, all the transformations between the world, model, page,
and device spaces must maintain square units. This means that your application
should select metric, English, or arbitrary page units instead of pels. On most
devices, pels are rectangular, but not necessarily square. This also means that
the Sx and Sy scaling factors should be equal. If the transformations maintain
square units and the arc parameters are set to their default values, GpiFullArc
produces a circle.
In the example shown in the following figure, if the page units are
PU_LOENGLISH and the default transformations are set, a circle with a radius of
1/2 inch is drawn.
#define INCL_GPIPRIMITIVES
#include <os2.h>
HPS hps; /* Presentation-space handle */
MRESULT EXPENTRY wpClient (HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
ARCPARAMS arcp; /* Structure for arc parameters */
POINTL ptlPos; /* Structure for current position */
FIXED fxMult; /* Multiplier for circle */
arcp.lP = 1;
arcp.lQ = 1;
arcp.lR = 0;
arcp.lS = 0;
GpiSetArcParams(hps, &arcp); /* Sets parameters to default */
ptlPos.x = 100; /* Loads x-coordinate */
ptlPos.y = 100; /* Loads y-coordinate */
GpiMove(hps, &ptlPos); /* Sets current position */
fxMult = MAKEFIXED(50, 0); /* Sets multiplier */
GpiFullArc(hps, DRO_OUTLINE, fxMult); /* Draws circle */
} /* wpClient */
The second argument to GpiFullArc DRO_OUTLINE, specifies that the operating
system should draw only the outline of the circle-rather than filling the
interior with the current fill pattern. The third argument, fxMult, specifies
that the operating system should multiply the size of the circle by 50 units.
Because the page units are PU_LOENGLISH and the default transformations are
set, 50 units is equivalent to 1/2 inch.
ΓòÉΓòÉΓòÉ 6.2.4. Drawing an Ellipse ΓòÉΓòÉΓòÉ
If you set the world, model, page, and device transformations so that they
maintain square units, you can use the arc parameters to transform the shape of
the unit circle to an ellipse, and draw this with GpiFullArc. The example in
the following figure alters the arc parameter, p, by doubling its value, making
the ellipse twice as wide horizontally as it is vertically.
In the example shown in the following figure, if the page units are
PU_LOENGLISH and the default transformations are set, an ellipse with a 2-inch
major axis (parallel to the x-axis) and a 1-inch minor axis (parallel to the
y-axis) is drawn.
#define INCL_GPIPRIMITIVES
#include <os2.h>
HPS hps; /* Presentation-space handle */
MRESULT EXPENTRY wpClient (HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
POINTL ptlPos; /* Structure for current position */
FIXED fxMult; /* Multiplier for ellipse */
ARCPARAMS arcp; /* Structure for arc parameters */
arcp.lP = 2;
arcp.lQ = 1;
arcp.lR = 0;
arcp.lS = 0;
GpiSetArcParams(hps, &arcp); /* Sets parameters to default */
ptlPos.x = 200; /* Loads x-coordinate */
ptlPos.y = 100; /* Loads y-coordinate */
GpiMove(hps, &ptlPos); /* Sets current position */
fxMult = MAKEFIXED(50, 0); /* Sets multiplier */
GpiFullArc(hps, DRO_OUTLINE, fxMult); /* Draws circle */
} /* wpClient */
Because the arc-parameter fields, lP and lQ, are set to 2 and 1, the operating
system creates an ellipse with a major axis that is twice as long as the minor
axis.
ΓòÉΓòÉΓòÉ 6.2.5. Drawing a Pie Slice ΓòÉΓòÉΓòÉ
The following steps describe how to use GpiPartialArc to draw a closed shape
bounded by a chord and an arc:
1. Set the current line type to LINETYPE_INVISIBLE with GpiSetLineType.
2. Call GpiPartialArc with the start angle equal to angle B, and the sweep
angle equal to 0. This effectively moves the current position to a point
on the current arc, and thereby defines one end of the chord.
3. Select a visible line type with GpiSetLineType
4. Call GpiPartialArc with the start angle equal to angle A, and the sweep
angle equal to angle B - angle A. Angle B must be greater than angle A.
The center point is the same on both GpiPartialArc calls.
To fill this partial arc with the current area-fill pattern, you can bracket
the GpiPartialArc call of step 4 with GpiBeginArea and GpiEndArea. You should
not call GpiBeginArea before step 2.
The effect of this sequence is shown in the following figure.
Closed Figure Bounded by Chord and Arc
The circle in the preceding figure is defined by the current arc parameters.
Point F is the current position, and point C is the center of the arc as
specified with the first GpiPartialArc call. The first GpiPartialArc call-with
the line type set to LINETYPE_INVISIBLE-moves the current position to point D.
The second GpiPartialArc call-with the line type set to LINETYPE_SOLID- draws
the chord from the current position (point D) to the start point of the arc
(point E), and draws arc ED.
The partial arc has been defined within an area and has been filled with the
current area-fill pattern.
The following figure shows how to draw a "pie slice". like the one drawn in
the previous figure.
#define INCL_GPIPRIMITIVES
#include <os2.h>
void Figure_516(){
HPS hps;
POINTL ptlCenter = {2L, 2L}; /* Coordinates of the center point */
FIXED fxAngleA = 20L; /* Angle A in degrees */
FIXED fxAngleB = 130L; /* Angle B in degrees */
GpiSetLineType(hps, LINETYPE_INVISIBLE);
/* Set position to start drawing the arc at angle B. */
GpiPartialArc(hps, &ptlCenter, MAKEFIXED(1, 0), fxAngleB, 0L);
GpiSetLineType(hps, LINETYPE_ID);
GpiBeginArea(hps, BA_BOUNDARY | BA_ALTERNATE); /* Fill the area */
GpiPartialArc(hps, &ptlCenter, MAKEFIXED(1, 0), fxAngleA, fxAngleB-fxAngleA);
GpiEndArea(hps); /* Cancel area-fill */
}
ΓòÉΓòÉΓòÉ 6.2.6. Drawing a Fillet ΓòÉΓòÉΓòÉ
A fillet is tangential to two lines. The curve of the fillet is always
tangential to a line drawn between its start and control points and a line
drawn between its end and control points.
The following figure shows an example of how to draw a single curve, using the
current position and two control points.
#include <os2.h>
HPS hps; /* Presentation-space handle */
MRESULT EXPENTRY wpClient(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
POINTL aptl[2]; /* Structure for control points */
aptl[0].x = 50; /* Loads x-coord. of first control point */
aptl[0].y = 50; /* Loads y-coord. of first control point */
GpiMove(hps, aptl); /* Sets current position */
aptl[0].x = 75; /* Loads x-coord. of second control point */
aptl[0].y = 75; /* Loads y-coord. of second control point */
aptl[1].x = 100; /* Loads x-coord. of third control point */
aptl[1].y = 50; /* Loads y-coord. of third control point */
GpiPolyFillet(hps, 2, aptl); /* Draws fillet */
} /* wpClient */
When you draw a sharp fillet, the sharpness value controls the shape of the
curve, as shown in a previous table.
The following figure shows an example of using a sharpness value of 3, which
creates a hyperbolic curve.
#include <os2.h>
HPS hps; /* Presentation-space handle */
MRESULT EXPENTRY wpClient(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
POINTL aptl[2]; /* Structure for control points */
FIXED fxSharpness; /* Sharpness value */
aptl[0].x = 50; /* Loads x-coord. of first control point */
aptl[0].y = 50; /* Loads y-coord. of first control point */
GpiMove(hps, aptl); /* Sets current position */
aptl[0].x = 75; /* Loads x-coord. of second control point */
aptl[0].y = 75; /* Loads y-coord. of second control point */
aptl[1].x = 100; /* Loads x-coord. of third control point */
aptl[1].y = 50; /* Loads y-coord. of third control point */
fxSharpness = MAKEFIXED(3, 0); /* Sets sharpness value */
GpiPolyFilletSharp(hps, /* Draws fillet */
2L, aptl, &fxSharpness);
} /* wpClient */
ΓòÉΓòÉΓòÉ 6.2.7. Drawing a Spline ΓòÉΓòÉΓòÉ
When you use GpiPolySpline to draw a spline, each curve is tangential to the
first and last of three connected lines. The following figure shows how to draw
a spline.
#include <os2.h>
HPS hps; /* Presentation-space handle */
MRESULT EXPENTRY wpClient(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
POINTL aptl[3]; /* Structure for control points */
aptl[0].x = 50; /* Loads x-coord. of first control point */
aptl[0].y = 100; /* Loads y-coord. of first control point */
GpiMove(hps, aptl); /* Sets current position */
aptl[0].x = 75; /* Loads x-coord. of second control point */
aptl[0].y = 200; /* Loads y-coord. of second control point */
aptl[1].x = 100; /* Loads x-coord. of third control point */
aptl[1].y = 0; /* Loads y-coord. of third control point */
aptl[2].x = 125; /* Loads x-coord. of fourth control point */
aptl[2].y = 100; /* Loads y-coord. of fourth control point */
GpiPolySpline(hps, 3L, aptl); /* Draws spline */
} /* wpClient */
ΓòÉΓòÉΓòÉ 7. Marker Primitives ΓòÉΓòÉΓòÉ
Marker primitives are graphics objects-such as stars, dots, or crosses-that are
used, for example, to indicate the plotted points on a line graph. The
following topics are related to the information in this chapter:
Presentation spaces
Line and arc primitives
Color and mix attributes
Fonts
ΓòÉΓòÉΓòÉ 7.1. About Marker Primitives ΓòÉΓòÉΓòÉ
Marker primitives always are drawn centered over a point. In a designated
presentation space, GpiMarker draws a single marker primitive of the current
marker symbol, with its center at a specified position. This position becomes
the new current position when the marker is drawn.
Another marker function, GpiPolyMarker, draws multiple marker primitives in the
designated presentation space. Each marker primitive is centered over a
position specified in an input array to GpiPolyMarker. All marker primitives
drawn by a single call to GpiPolyMarker use the same (current) marker symbol.
When a series of marker primitives is drawn, the current position is the center
point of the last marker in the series. The following figure shows the use of
marker primitives in a line graph.
Marker Primitives
This example shows a sequence of diamond-shaped marker primitives drawn on a
line graph at (1,2), (3,4), (4,3), (7,5), (8,4), (9,8), (10,6), and (11,6). The
new current position is at (11,6). The marker portion of this example could
have been drawn with a single call to GpiPolyMarker or with eight separate
GpiMarker calls.
ΓòÉΓòÉΓòÉ 7.1.1. Attributes of Marker Primitives ΓòÉΓòÉΓòÉ
Marker primitive attributes are contained in a data structure called
MARKERBUNDLE. Following is a list of these attributes:
Marker symbol
Marker box
Marker set
Foreground color
Background color
Foreground mix attribute
Background mix attribute
When an application creates a presentation space, the marker attributes are
set to the default values shown in the following table.
Marker Attribute Default Values
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute ΓöéDefault Value ΓöéFunction that Redefines Γöé
Γöé Γöé ΓöéAttribute Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMarker symbol ΓöéCross ΓöéGpiSetMarker Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMarker box ΓöéDevice dependent; ΓöéGpiSetMarkerBox Γöé
Γöé Γöéequal to the size Γöé Γöé
Γöé Γöéof one character Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMarker set ΓöéLCID_DEFAULT ΓöéGpiSetMarkerSet Γöé
Γöé Γöé ΓöéNote: If this default is Γöé
Γöé Γöé Γöéchanged, the base marker Γöé
Γöé Γöé Γöéset cannot be reselected Γöé
Γöé Γöé Γöéwith GpiSetMarkerSet. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground colorΓöéBlack ΓöéGpiSetAttrs (MBB_COLOR) Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground colorΓöéClear ΓöéGpiSetAttrs Γöé
Γöé Γöé Γöé(MBB_BACK_COLOR) Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground mix ΓöéOverpaint ΓöéGpiSetAttrs (MBB_MIX_MODE)Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground mix ΓöéLeave alone ΓöéGpiSetAttrs Γöé
Γöé Γöé Γöé(MBB_BACK_MIX_MODE) Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 7.1.2. Marker Symbols ΓòÉΓòÉΓòÉ
The current marker symbol is selected from the current marker set using
GpiSetMarker. The marker symbol selected for the specified presentation space
is used for all subsequent GpiMarker and GpiPolyMarker calls until a new symbol
is selected.
The following table describes the marker symbols provided by the PM in a base
marker set. These symbols are not necessarily available from other marker sets.
The Base Marker Set
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéSymbol ΓöéIdentifier ΓöéLong ValueΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCross ΓöéMARKSYM_CROSS Γöé1L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPlus sign ΓöéMARKSYM_PLUS Γöé2L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDiamond ΓöéMARKSYM_DIAMOND Γöé3L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSquare ΓöéMARKSYM_SQUARE Γöé4L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSix-point star ΓöéMARKSYM_SIXPOINTSTAR Γöé5L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEight-point star ΓöéMARKSYM_EIGHTPOINTSTAR Γöé6L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSolid diamond ΓöéMARKSYM_SOLIDDIAMOND Γöé7L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSolid square ΓöéMARKSYM_SOLIDSQUARE Γöé8L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDot ΓöéMARKSYM_DOT Γöé9L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSmall circle ΓöéMARKSYM_SMALLCIRCLE Γöé10L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBlank, (Often ΓöéMARKSYM_BLANK Γöé64L Γöé
Γöécalled the Γöé Γöé Γöé
Γöéinvisible marker) Γöé Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The default marker symbol (MARKSYM_DEFAULT) is identical to the MARKSYM_CROSS
symbol and has a long value of 0L. The error marker symbol (MARKSYM_ERROR) has
a long value of -1L.
The following figure shows the visible marker symbols from the base marker set.
Your application can determine the marker set with GpiQueryMarkerSet.
The Base Marker Set
ΓòÉΓòÉΓòÉ 7.1.3. Marker Box ΓòÉΓòÉΓòÉ
The marker box is a rectangular boundary that defines the horizontal and
vertical space occupied by the marker symbol. The marker box is used to center
the current marker symbol.
If the current marker set contains vector marker primitives (characters
outlined by using line and arc functions), changing the size of the marker box
changes the size of the marker primitives also. When you change the size of the
marker box, a vector marker symbol is scaled up or down automatically to fit
the box. Image marker primitives, however, cannot be scaled. If the current
marker set contains image characters, the marker box dimensions are fixed,
because you cannot alter the size of image markers.
You can use GpiSetMarkerBox to change the size of the marker box for a
particular presentation space. Set the value of the appropriate SIZEF structure
to the required size. The new size is expressed in world coordinates and should
not contain any fractional values.
The default size of the marker box can be determined using DevQueryCaps. The
values, CAPS_MARKER_WIDTH and CAPS_MARKER_HEIGHT, depend on the currently
associated device and the presentation page. Marker box values set with
GpiSetMarkerBox can be determined using GpiQueryMarkerBox.
GpiSetAttrs also can be used to change the size of the marker box.
GpiSetDefAttrs can be used to change the default size of the marker box.
ΓòÉΓòÉΓòÉ 7.1.4. Marker Set ΓòÉΓòÉΓòÉ
When you create a presentation space, the current marker set, along with other
marker attributes, are set to default. The current marker symbol (the cross
described earlier) is specified from the supplied marker set. The supplied set
of marker primitives contains only image, or raster, marker primitives.
The marker primitives in the default marker set are drawn by setting the color
of the pels in the marker box. Within the marker box, the color of the set pels
defines the foreground color. The default foreground color is neutral- black on
the display screen and on printers.
The color of the pels that are not set defines the background color. The
default background color is the background color on the device-white on the
display screen, and the loaded paper color on printers. The default background
mix is LEAVE_ALONE, or transparent, which means the background color is
irrelevant.
If the default set is changed using GpiSetDefAttrs, its markers are not
accessible. The markers from the default set can be recovered by calling
GpiSetDefAttrs and specifying the value LCID_DEFAULT, (0).
ΓòÉΓòÉΓòÉ 7.1.4.1. Customizing Marker Sets ΓòÉΓòÉΓòÉ
If the current marker set does not contain a symbol that suits your
application, you can load a new marker set and select a marker symbol from that
set. The only way to see the current marker set is to display it on the screen
or view a hardcopy of the symbols. You load a new marker set for a specified
presentation space by creating a logical font. Then you select the font as a
marker set by specifying the logical font identifer (lcid) as an input
parameter to GpiSetMarkerSet. After selecting the marker set, call GpiSetMarker
to select a marker from the set. You can set both values simultaneously, with
GpiSetAttrs.
You can use any font's character set as a marker set and any character within
that marker set as a marker. To determine the value that identifies the current
marker set, call GpiQueryMarkerSet. To determine the value that identifies the
current marker character, call GpiQueryMarker. You can retrieve both values
simultaneously with GpiQueryAttrs. You also can create image marker symbols
using the Font Editor.
ΓòÉΓòÉΓòÉ 7.1.5. Marker Color and Mix Attributes ΓòÉΓòÉΓòÉ
The color attribute defines the color used to draw a primitive or an object.
The mix attribute determines how the color of a primitive or an object is
combined with the color of the drawing surface, or any other objects on the
surface.
The marker color defines the color used to draw the output from any of the IBM
OS/2 marker functions. When a presentation space is created, the marker color
initial default is black. Markers are one of the primitives that have a
foreground and background color, as shown in the following figure.
For image markers, the colors are determined by the setting of pels. For vector
markers, the foreground consists of the arcs and lines that define the marker.
The background color appears between the foreground lines. The marker can be
solid, or filled, in which case the background color does not appear between
the foreground lines.
Marker Primitives
Marker primitives have both a color and background color attribute. The mix
attribute controls the combination of marker color with drawing-surface color,
while the background mix attribute controls the combination of the marker box
color with the drawing-surface color.
When a presentation space is created, the marker mix attribute initial default
is FM_OVERPAINT. The overpaint mix attribute specifies that the marker color is
not to be modified by the color of the drawing surface. If the marker mix
attribute is changed, the marker color is mixed with colors that are already on
the drawing surface.
The marker background color initial default is CLR_BACKGROUND. Usually this is
defined by the application to the same color as the drawing surface. The marker
background mix attribute initial default is BM_LEAVEALONE. The leave-alone mix
background attribute specifies that the marker background color is not drawn.
The box that effectively surrounds the marker appears only if the marker
background mix attribute is changed.
To specify a new color or mix attribute call GpiSetAttrs. This function accepts
as input the type of primitive, for example PRIM_MARKER, a list of attributes
that are to be changed, a list of attributes that are to be set to their
default values, and the values for the attributes that are to be changed.
GpiSetAttrs is useful to specify colors and mix attributes just for a specific
data structure- MARKERBUNDLE, for example. GpiSetAttrs also provides some
protection against invalid colors.
To determine the current marker color and mix attribute call GpiQueryAttrs.
This function accepts as input the primitive type and the attributes in
question. It returns as output an array of values for the specifically queried
attributes.
To reset the default marker color and mix attribute, just as with any other
attribute specified in the MARKERBUNDLE data structure, call GpiSetDefAttrs.
This function accepts as input the type of primitive, for example PRIM_MARKER,
the attributes to be changed, and the values that will become the new default
values. The changing of default values is important when working with segments.
Changing the default values during a series of drawing functions is not
recommended.
The marker color and mix attribute also can be specified with:
GpiSetColor
GpiSetMix
GpiSetBackColor
GpiSetBackMix
However, these functions have the disadvantage of specifying the foreground
and background color or mix attribute for all primitive BUNDLE data structures
that have the respective component.
There are four query functions that determine the color and mix attribute as
specified by GpiSet... functions:
GpiQueryColor
GpiQueryMix
GpiQueryBackColor
GpiQueryBackMix
If the marker color, marker background color, mix attribute, or background mix
attribute were specified individually, the queries can return a value
inconsistent with the current marker attribute.
ΓòÉΓòÉΓòÉ 7.2. Using Marker Primitives ΓòÉΓòÉΓòÉ
You can use marker functions to:
Draw a single marker or a series of markers
Set or determine (query) any combination of the marker bundle attributes
including:
- Determining the lcid for the current marker set
- Selecting a character set as the new marker set
- Determining the value that identifies the current marker
- Selecting a character as the new marker
- Setting or changing the size of the marker box
- Setting or changing the color of a marker
ΓòÉΓòÉΓòÉ 7.2.1. Drawing Marker Primitives ΓòÉΓòÉΓòÉ
You can draw either a single marker or a series of markers using the current
marker symbol. To draw a single marker, set the fields in a POINTL structure to
correspond to the desired position in world coordinates. Then call GpiMarker
passing it the address of the POINTL structure as the second argument.
To draw a series of markers, set the fields in an array of POINTL structures to
correspond to the desired positions in world coordinates. Then call
GpiPolyMarker, passing it the number of points in the array as the second
argument and the name of the array as the third argument.
The following figure shows how to draw a graph with GpiPolyLine and
GpiPolyMarker.
#include <os2.h>
void fncMARK01(void){
HPS hps; /* Presentation-space handle */
POINTL aptl[6]; /* Array of points */
aptl[0].x = 10; aptl[0].y = 15; /* Assigns points */
aptl[1].x = 150; aptl[1].y = 30;
aptl[2].x = 200; aptl[2].y = 32;
aptl[3].x = 250; aptl[3].y = 70;
aptl[4].x = 360; aptl[4].y = 120;
aptl[5].x = 380; aptl[5].y = 98;
GpiPolyMarker(hps, sizeof(aptl) / sizeof(POINTL),aptl);
/* Plots points */
GpiMove(hps, aptl); /* Sets current position */
GpiPolyLine(hps, sizeof(aptl) / sizeof(POINTL),aptl);
/* Draws lines */
} /* fncMARK01 */
ΓòÉΓòÉΓòÉ 7.2.2. Selecting a New Marker ΓòÉΓòÉΓòÉ
The following figure shows how to check whether the default marker primitive
from the default marker set is being used currently, and if so, how to replace
the cross with the six-pointed star.
#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncMARK02(void){
HPS hps;
if ((GpiQueryMarker(hps) == MARKSYM_DEFAULT) &&
(GpiQueryMarkerSet(hps) == LCID_DEFAULT))
GpiSetMarker(hps, MARKSYM_SIXPOINTSTAR);
ΓòÉΓòÉΓòÉ 7.2.3. Selecting a New Marker Set ΓòÉΓòÉΓòÉ
The following figure is an example of how to load a Helvetica** vector font,
select it as the new marker set, and select the uppercase A as the new marker
primitive.
#define INCL_GPILCIDS
#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncMARK03(void){
LONG cHelvFonts, cFonts, lcid, i, j;
HPS hps;
FATTRS fattrs;
FONTMETRICS afm[80];
MARKERBUNDLE mbnd;
cHelvFonts = GpiQueryFonts(hps, QF_PUBLIC, "Helv",
&cFonts, sizeof(FONTMETRICS), (PFONTMETRICS) NULL);
/* Queries the number of Helvetica fonts. */
GpiQueryFonts(hps, QF_PUBLIC, "Helv", &cHelvFonts,
sizeof(FONTMETRICS), afm);
/* Loads the array of FONTMETRICS structures. */
for (i = 0; !(afm[i].fsDefn & FM_DEFN_OUTLINE)
&& i < cHelvFonts; i++);
/* Finds outline font */
fattrs.usRecordLength = sizeof(FATTRS);
fattrs.fsSelection = 0;
fattrs.lMatch = afm[i].lMatch; /* Uses Helvetica outline font */
for (j = 0; j <= sizeof(afm[i].szFacename); j++)
fattrs.szFacename[j] = afm[i].szFacename[j];
fattrs.idRegistry = 0;
fattrs.usCodePage = 850; /* Uses international code page */
fattrs.lMaxBaselineExt = 0;
fattrs.lAveCharWidth = 0;
fattrs.fsType = 0;
fattrs.fsFontUse = FATTR_FONTUSE_TRANSFORMABLE;
GpiCreateLogFont(hps, (PSTR8) NULL, lcid, &fattrs);
mbnd.usSet = lcid; /* Uses font as marker set */
mbnd.usSymbol = 'A'; /* Uses capital A as primitive */
GpiSetAttrs(hps, PRIM_MARKER, MBB_SYMBOL | MBB_SET, 0, &mbnd);
} /* fncMARK03 */
ΓòÉΓòÉΓòÉ 7.2.4. Changing the Marker Color ΓòÉΓòÉΓòÉ
The following figure shows how to set the marker foreground color to green.
#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncMARK04(void){
HPS hps;
MARKERBUNDLE mbnd;
mbnd.lColor = CLR_GREEN;
GpiSetAttrs(hps, PRIM_MARKER, MBB_COLOR, 0L, &mbnd);
} /* fncMARK04 */
ΓòÉΓòÉΓòÉ 8. Matrix Multiplication ΓòÉΓòÉΓòÉ
To show how matrix multiplication is implemented, here are two matrixes:
Γöî ΓöÉ Γöî ΓöÉ
Γöé a b c Γöé Γöé j k l Γöé
Γöé d e f Γöé * Γöé m n o Γöé
Γöé g h i Γöé Γöé p q r Γöé
Γöö Γöÿ Γöö Γöÿ
The multiplication of these two matrixes produces a value for each of the nine
elements of the resulting matrix:
Γöî ΓöÉ
Γöé element1 element2 element3 Γöé
Γöé element4 element5 element6 Γöé
Γöé element7 element8 element9 Γöé
Γöö Γöÿ
To produce element 1 of the matrix, element a is multiplied by element j,
element b is multiplied by element m, and element c is multiplied by element p.
That is:
element1 = (a x j) + (b x m) + (c x p)
To produce element 2 of the matrix, element a is multiplied by element k,
element b is multiplied by element n, and element c is multiplied by element q.
To produce element 3 of the matrix, elements a, b, and c are multiplied by
their corresponding elements (l, o, and r) in the third vertical line of the
second matrix. To produce element 4 of the matrix, you move down a row in the
first matrix. That is, element d is multiplied by element j, element e is
multiplied by element m, and element f is multiplied by element p. You continue
the multiplication in this way until each of the nine elements has a value. The
complete workings for this example are as follows:
element1 = (a x j) + (b x m) + (c x p)
element2 = (a x k) + (b x n) + (c x q)
element3 = (a x l) + (b x o) + (c x r)
element4 = (d x j) + (e x m) + (f x p)
element5 = (d x k) + (e x n) + (f x q)
element6 = (d x l) + (e x o) + (f x r)
element7 = (g x j) + (h x m) + (i x p)
element8 = (g x k) + (h x n) + (i x q)
element9 = (g x l) + (h x o) + (i x r)
Note that if the order of the two matrixes is reversed, the results of the
multiplication are different.
Here is a simple example in which an object is scaled by a factor of 3, and
then translated by (5,4):
Γöî ΓöÉ Γöî ΓöÉ Γöî ΓöÉ
Γöé 3 0 0 Γöé Γöé 1 0 0 Γöé Γöé 3 0 0 Γöé
Γöé 0 3 0 Γöé * Γöé 0 1 0 Γöé = Γöé 0 3 0 Γöé
Γöé 0 0 1 Γöé Γöé 5 4 1 Γöé Γöé 5 4 1 Γöé
Γöö Γöÿ Γöö Γöÿ Γöö Γöÿ
You can multiply together as many transformation matrixes as you require.
ΓòÉΓòÉΓòÉ 9. Metafiles ΓòÉΓòÉΓòÉ
A metafile is a graphics object that, like a segment, contains the GPI
instructions that contribute to the final version of a picture. Unlike a
segment, a metafile also contains a header, with state information, and all
resources necessary to identically create the picture. Because pictures that
are displayed when a graphics application is executed are lost when the
application finishes, metafiles provide a method of retaining pictures beyond a
single execution of an application.
The following topics are related to the information in this chapter:
Presentation spaces and device contexts
Line primitives
Marker primitives
Area primitives
Character string primitives
Color and mix attributes
Paths
Regions
Fonts
Bit maps
Coordinate spaces and transformations
Print job submission and manipulation
ΓòÉΓòÉΓòÉ 9.1. About Metafiles ΓòÉΓòÉΓòÉ
Metafiles can exist in three distinct forms. A metafile that has just been
created is called a memory metafile because it exists in memory managed by the
Presentation Manager on behalf of the application that created it. A metafile
that is transferred to disk storage as a file with the default extension of
.MET is called a disk metafile. A metafile that is loaded into an application's
memory is editable by the application.
Metafiles save resources in the following ways:
Metafiles can be created and used in draw mode by a single application.
Therefore, an application that is not retaining segments in a segment
store can retain graphics in a metafile.
Metafiles remain available while the owning application is running,
regardless of the number of presentation spaces the application obtains
or defines.
Given the same starting conditions in each presentation space, you can
produce an identical picture each time the metafile contents are
executed.
Different threads or processes within an application can display a
picture stored as a metafile without each having to own the metafile.
If your organization has common graphical resources, such as a company
logo, those resources can be stored in a metafile. This avoids the
overhead of re-creating the resources each time they are needed.
Because the metafile is a device-independent format, it is useful for
transferring pictures that are to be printed when the printer-type is
unknown.
PM applications can exchange graphical information by using metafiles,
either by using the clipboard or by transferring them over a network.
Your application can also exchange graphics data with non-PM applications
that support the Mixed Object Document Content Architecture (MO:DCA)
interchange standard.
Unlike bit-maps, metafiles offer some device-independence. Bit maps store
picture information on a pel-by-pel basis. Metafiles store picture information
in the form of low-level graphics commands that the operating system uses to
construct the pictures.
Note: Metafiles can contain bit maps or other graphics information that is in
device-dependent format.
The graphics commands, called "graphics orders", represent graphics functions
that create a picture. These include drawing instructions, as well as
attribute-setting instructions (for example, color tables and logical fonts)
and anything that describes the structure of the picture. The contents of a
metafile, therefore, are similar to those of the graphics presentation space
in which the picture is drawn. The Presentation Manager automatically records
the environmental detail of the presentation space in which a picture is drawn
in the metafile.
Note: A metafile can contain data generated from GPI functions only. Any
non-graphical data included in a metafile is ignored.
An application can re-create a picture from a metafile and display it in a
window on the screen or print it by "playing" the metafile. When an
application displays the contents of a metafile, it can use the color table,
font, fill pattern, and transformations that are stored in the metafile, or it
can use the logical color table, logical font, fill pattern, and
transformations that are set for the current presentation space. The
appearance of the picture stored in the metafile can, therefore, be changed by
editing the current presentation space before playing the metafile.
An application can save metafiles to a disk to be loaded later by any
application that chooses to access the metafile. Disk metafiles loaded into
application memory can also be edited in the same manner as elements in
graphics segments are edited.
They contain both primitives and attributes.
ΓòÉΓòÉΓòÉ 9.1.1. Contents of a Metafile ΓòÉΓòÉΓòÉ
Every graphic function can be represented by one or more graphics orders. The
operating system defines graphics orders for:
Areas
Bit maps (for fill patterns) and pattern-reference points
Character output and attribute
Colors and mix modes (foreground and background)
Lines and arcs and line and arc attributes (including GpiBox)
Paths (including clip paths)
Position (for example, GpiMove)
Saving and resetting attributes (including GpiPop)
Transformations (in model space)
Viewing Limits
Editing Retained Graphics and Graphics Segments also describes orders and how
to edit them.
When a picture is drawn in a presentation space associated with a metafile
device context, the operating system converts the primitive attributes and
drawing functions into graphics orders and stores them in the metafile.
The operating system stores the effects of region and other operations that
are not permitted as escape orders in the metafile. When an application
finishes playing a metafile, the system restores any regions that were defined
for the presentation space prior to calling GpiPlayMetaFile.
An application can use any of the query functions while creating a metafile,
but the system will not store those query functions in the metafile.
Similarly, an application can set a value by using a mathematical operator,
but the system will store only the result of the operation in the metafile.
For example, if an application determines the end point of a line by
subtracting 100 from the x- and y-coordinates of the upper-right corner of a
window, the system records the end point, not the relative distance, in the
metafile.
Because the output of bit map functions is dependent upon the capabilities of
the output device, Gpi bit map functions might produce unexpected results when
they are used in a metafile. If the pel dimensions of the output device are
different from the pel dimensions of the device on which the metafile was
created, the bit map will be distorted. If the output device is a plotter, the
bit map functions will not work at all.
Most of the escape functions used by the DevEscape function can be used in
metafiles. The escape functions that the system does not save in metafiles are
DEVESC_QUERYESCSUPPORT and DEVESC_GETSCALINGFACTOR.
ΓòÉΓòÉΓòÉ 9.1.1.1. Metafile Content Restrictions ΓòÉΓòÉΓòÉ
Like areas and paths, not all functions and attributes can be represented in a
metafile. Metafile content is mainly dependent upon the drawing mode in which
the metafile is to be played. If the metafile is to be played when the current
drawing-mode parameter is DM_DRAW (and in no other drawing mode), the metafile
content is restricted as shown in Draw-Mode Restrictions. If the metafile is to
be played when the current drawing-mode parameter is DM_RETAIN or
DM_DRAWANDRETAIN, or if the file is to conform to SAA* guidelines, the metafile
content is restricted as shown in Creating Metafiles for Interchange.
ΓòÉΓòÉΓòÉ 9.1.1.1.1. Draw-Mode Restrictions ΓòÉΓòÉΓòÉ
The following restrictions apply if the metafile is to be played when the
current drawing mode parameter is DM_DRAW:
If the DCTL_DISPLAY flag of GpiSetDrawControl is OFF when you are sending
graphics to a metafile, the graphics will not be visible when the
metafile is played. Their effects on the current position and on current
attribute settings are recorded.
Region functions are not recorded in a metafile. The effects of the
following functions, however, are recorded:
- GpiSetClipRegion
- GpiIntersectClipRectangle
- GpiExcludeClipRectangle
- GpiOffsetClipRegion
- GpiPaintRegion
When the metafile is played into a presentation space, temporary regions
are created. Upon completion of GpiPlayMetaFile, these temporary regions
are automatically deleted, and the clipping region that was current
before the metafile was played is restored.
In general, escape functions identified by reserved escape codes (that
is, escape codes in the range of 0 through 32767) are recorded in a
metafile. However, the DevEscape functions DEVESC_QUERYESCSUPPORT (escape
code 0) and DEVESC_GETSCALINGFACTOR (escape code 1) are not stored in the
metafile.
The effect of GpiErase, including close-segment processing, is recorded
in a metafile.
The following functions can produce unexpected effects if the metafile
contents are displayed on a different device from the one they were
created for:
- GpiBitBlt
- GpiSetPel
- GpiSetClipRegion
- GpiOffsetClipRegion
- GpiPaintRegion
- GpiIntersectClipRectangle
- GpiExcludeClipRectangle
The reason for the unexpected effects is because the pel resolutions of
the devices might differ. Raster operations (for example, GpiBitBlt) do
not work on plotters.
You can associate the metafile device context with a different
presentation space while creating the metafile, but the new presentation
space must have the same format as the original.
ΓòÉΓòÉΓòÉ 9.1.1.1.2. Creating Metafiles for Interchange ΓòÉΓòÉΓòÉ
The following restrictions apply if the metafile is to be played when the
current drawing-mode parameter is DM_DRAWANDRETAIN or DM_RETAIN, or if the
metafile is to conform to SAA guidelines:
Before you issue the first drawing instruction to a graphics presentation
space that has been associated with a metafile device context, you must
establish (or default) the following:
- The graphics field (use GpiSetGraphicsField)
- The color table (use GpiCreateLogColorTable)
- The code page for the default character set (use GpiSetCp)
- The default viewing transformation (use GpiSetDefaultViewMatrix)
- The settings of the drawing controls (use GpiSetDrawControl;
DCTL_DISPLAY must be set on)
- The default values of attributes (use GpiSetDefAttrs)
- The default viewing limits (use GpiSetDefViewingLimits)
- The primitive tag (use GpiSetDefTag)
- The default arc parameters (use GpiSetDefArcParams)
You must not specify a graphics field if the metafile is to conform to
SAA guidelines. If a graphics field is specified, you can play the
metafile in DM_RETAIN or DM_DRAWANDRETAIN mode, but the graphics field
must be specified before the first drawing instruction is issued to the
metafile. The effect of the graphics field in the target presentation
space when playing the metafile is controlled by the PMF_LOADTYPE option
of GpiPlayMetaFile.
You can define logical fonts and identify bit maps to be used as
area-fill patterns at any time. You must not, however, issue
GpiDeleteSetId against these resources after they have been established.
Once assigned, therefore, lcids cannot be reused.
The size of the logical-color-table data must not exceed 31KB.
You must not use clipping regions. Therefore, none of the following
functions are supported:
- GpiSetClipRegion
- GpiExcludeClipRectangle
- GpiIntersectClipRectangle
- GpiOffsetClipRegion
You must not reassociate the metafile device context.
When you use a bit map as the source of a GpiWCBitBlt operation or as an
area-fill pattern, it must not be modified.
Only the following foreground mixes can be used:
- FM_DEFAULT
- FM_OR
- FM_OVERPAINT
- FM_LEAVEALONE
Only the following background mixes can be used:
- BM_DEFAULT
- BM_OVERPAINT
- BM_LEAVEALONE
The following functions are not supported:
- GpiBitBlt
- GpiSetPel
- GpiSetPS
- GpiResetPS
- GpiErase
- GpiPaintRegion
- DevEscape
ΓòÉΓòÉΓòÉ 9.1.1.1.3. Micro Presentation Space Restrictions ΓòÉΓòÉΓòÉ
When you create a metafile from a micro presentation space, or play the
metafile through a micro presentation space, the contents of the metafile are
restricted to those GPI functions that are valid in a micro presentation space.
In this case, the application must use GpiDestroyPS instead of GpiAssociate
before issuing DevCloseDC. GpiAssociate is not permitted in a micro
presentation space.
ΓòÉΓòÉΓòÉ 9.1.1.1.4. Query Restrictions ΓòÉΓòÉΓòÉ
Query functions can be issued, with the usual restrictions, unless the metafile
device context was created using the no query option, OD_METAFILE_NOQUERY.
ΓòÉΓòÉΓòÉ 9.1.1.1.5. Segment Restrictions ΓòÉΓòÉΓòÉ
Chained and unchained segments invoked by any GpiDraw... command are written to
the metafile. Primitives outside segments are recorded automatically as zero
segments. If the metafile is subsequently played in DM_RETAIN mode, all
graphics are directed to the segment store.
Chained dynamic segments cannot be recorded in a metafile. GpiRemoveDynamics
and GpiDrawDynamics cause an error condition to be raised when the presentation
space is associated with a metafile device context. Unchained dynamic segments
are recorded as zero segments. To draw an unchained dynamic segment, use
GpiDrawSegment.
ΓòÉΓòÉΓòÉ 9.1.1.1.6. Asynchronous Drawing Thread Restrictions ΓòÉΓòÉΓòÉ
If the metafile is being created on an asynchronous drawing thread and the
thread is suspended by GpiSetStopDraw, an unusable metafile results.
ΓòÉΓòÉΓòÉ 9.1.2. Metafile Functions ΓòÉΓòÉΓòÉ
The OS/2 operating system provides a set of functions that allow you to:
Create a metafile
Store pictures in a metafile
Play a metafile
Save a metafile
Load a metafile
Edit a metafile
Copy a metafile
Delete a metafile
How these functions are used to create and manipulate metafiles in
relationship to applications and components of the operating system is
illustrated in the following figure.
Metafile Functions
ΓòÉΓòÉΓòÉ 9.1.2.1. Creating a Metafile ΓòÉΓòÉΓòÉ
Pictures are drawn in presentation spaces associated with device contexts. PM
considers a metafile to be an output device or destination, in the same manner
as a window or printer. This means that to record a picture in a metafile, a
metafile device context must be created and associated with a presentation
space.
A metafile device context is created by calling DevOpenDC and specifying the
type of device context as:
OD_METAFILE
OD_METAFILE_NOQUERY.
OD_METAFILE is generally used to specify a metafile device context, although
OD_METAFILE_NOQUERY provides better recording performance. OD_METAFILE_NOQUERY
does not support attribute queries, for example, GpiQueryCurrentPosition, or
GpiQueryColor.
The device driver for the device that the metafile device context is
associated with is specified in the DEVOPENSTRUC data structure required for
DevOpenDC. DEVOPENSTRUC is described in Print Job Submission and Manipulation.
A metafile device context can be associated with a newly-created presentation
space by calling GpiCreatePS and specifying the handle to the metafile device
context returned from the call to DevOpenDC. A metafile device context can
also be associated with an existing, normal presentation space by calling
GpiAssociate and specifying the handle to the metafile device context returned
from the call to DevOpenDC.
ΓòÉΓòÉΓòÉ 9.1.2.2. Storing Pictures in a Metafile ΓòÉΓòÉΓòÉ
When a metafile device context is associated with a presentation space,
presentation space resources (such as the current logical color table) and
environmental settings (such as the presentation-page format) are copied
automatically into the metafile. These items must be established before the
presentation space is associated with the metafile device context.
Loading of additional resources (such as fonts) and adjustments to the
environment (such as modifying the default viewing transform) should be made
before you begin drawing. Attribute settings, segment-creation requests, and
primitive-drawing requests that contribute to the picture are directed to the
metafile after its device context has been associated with a presentation
space.
If an application calls GpiSetDrawControl, specifying DCTL_DISPLAY and
DCTL_OFF, before drawing graphics into a metafile, the graphics are not visible
when the metafile is played. However, the metafile records any changes made to
the current position or presentation-space attributes.
When the metafile device context has been associated with a graphics
presentation space, the metafile is ready to receive graphical data. Just as
with any other output destination, whether the picture is sent directly to the
metafile is controlled by the current drawing mode, as shown in the following
table.
Drawing Mode Dependencies When Recording Metafiles
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDrawing Mode ΓöéEffect Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw mode ΓöéGraphics go directly to the metafile. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRetain mode ΓöéGraphics go to the segment store of Γöé
Γöé Γöéthe presentation space. They are not Γöé
Γöé Γöédirected to the metafile until the Γöé
Γöé Γöéapplication issues an appropriate Γöé
Γöé ΓöéGpiDraw... request (GpiDrawChain, Γöé
Γöé ΓöéGpiDrawFrom, GpiDrawSegment). Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw-and-retain mode ΓöéGraphics go directly to the metafile, Γöé
Γöé Γöéand also to the segment store of the Γöé
Γöé Γöépresentation space. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The drawing mode can be changed at any time while the metafile device context
remains open by calling GpiSetDrawingMode.
As long as the metafile device context remains open, you can continue drawing.
A metafile can only contain data generated from GPI functions. Any nongraphical
data included in a metafile is ignored. The following list describes items
found in a metafile:
Picture
Logical color table
Logical font
Fill pattern
Viewing transformation
Page units
Page dimensions
When an application finishes drawing in a metafile, it must disassociate the
metafile device context from the presentation space by calling GpiAssociate.
If the metafile is associated with or through a micro presentation space, call
GpiDestroyPS to perform an implicit disassociation.
When you have finished drawing in the metafile, and the presentation space has
been disassociated, the application can close the metafile device context and
obtain a handle to the metafile by calling DevCloseDC. A closed metafile
cannot be reopened; therefore, additional drawing in the metafile is not
possible. A closed metafile can be referenced by the metafile handle. The
metafile handle is used to reference the metafile for subsequent operations on
the metafile. Use the metafile handle to:
Transfer a metafile to application memory
Transfer a metafile from application memory
Save a metafile on disk
Play a metafile into presentation space
Edit a metafile
Copy a metafile
Delete a metafile
Because each metafile can be distinctly identified, your application can work
with more than one metafile at a time. However, because metafiles can be very
large files, you must make maximum use of the metafile handles to avoid
duplicating the actual metafiles in memory.
ΓòÉΓòÉΓòÉ 9.1.2.3. Playing a Metafile ΓòÉΓòÉΓòÉ
An application can redraw a picture stored in a metafile by executing the
contents of metafile. This is known as playing a metafile into a graphics
presentation space. How a picture is redrawn (that is, how the metafile is
replayed) depends on the current drawing-mode of the target presentation space.
The following table describes these dependencies.
Drawing Mode Dependencies When Playing Metafiles
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDrawing Mode ΓöéResult ΓöéIf the metafile Γöé
Γöé Γöé Γöécontains a segment Γöé
Γöé Γöé Γöéchain... Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDM_DRAW ΓöéThe metafile contentsΓöéThe contents of the Γöé
Γöé Γöéare executed, and theΓöésegments in the chainΓöé
Γöé Γöépicture is directed Γöérepresent the pictureΓöé
Γöé Γöéto the current outputΓöéoutput that is Γöé
Γöé Γöédevice. Γöédirected at the Γöé
Γöé Γöé Γöétarget output device.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDM_RETAIN ΓöéThe metafile contentsΓöéThe chain is added toΓöé
Γöé Γöéare retained in the Γöéthe end of any chain Γöé
Γöé Γöéapplication's segmentΓöéthat may already be Γöé
Γöé Γöéstore. The picture Γöéin the segment store.Γöé
Γöé Γöédefined in the ΓöéIf any segment in theΓöé
Γöé Γöémetafile is not Γöémetafile has the sameΓöé
Γöé Γöédirected to an outputΓöénonzero name as a Γöé
Γöé Γöédevice until the Γöésegment already in Γöé
Γöé Γöéapplication issues anΓöéthe segment store of Γöé
Γöé Γöéappropriate Γöéthe presentation Γöé
Γöé ΓöéGpiDraw... function. Γöéspace, an error Γöé
Γöé Γöé Γöécondition is raised. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDM_DRAWANDRETAIN ΓöéThe metafile contentsΓöéSee above. Γöé
Γöé Γöéare both stored and Γöé Γöé
Γöé Γöéexecuted. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Note: Unchained segments in the metafile are always retained, regardless of
the current drawing-mode parameter.
When the contents of a metafile are retained in the segment store of the target
presentation space, they can be manipulated by the application as if the
application had created them. For example, the segments can be edited, drawn,
correlated, and deleted.
A metafile is "played" by calling GpiPlayMetaFile. A metafile cannot, however,
be "played" within a segment bracket. GpiPlayMetaFile requires a metafile
handle, an option count, an options array, a byte count of a descriptive
record, and the descriptive record.
The GpiPlayMetaFile descriptive record is a natural-language description of the
picture contents. For example, its value might be A House. This description is
provided on input to the DevOpenDC function that defines the metafile device
context. It can be used, for example, in a list box from which a user can
select a picture.
The GpiPlayMetaFile options array specifies how the operating system alters
your application's presentation space before playing the metafile. The options
array determines the display attributes of the metafile. The array fields and
their respective attributes, as numbered consecutively in the array, are shown
in the following table.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéOption ΓöéAttribute Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_SEGBASE ΓöéReserved, must be 0. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_LOADTYPE ΓöéViewing transform, graphics. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_RESOLVE ΓöéReserved, must be 0. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_LCIDS ΓöéFont and local bit map local Γöé
Γöé Γöéidentifiers. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_RESET ΓöéDrawing attributes. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_SUPPRESS ΓöéActual playing of the Γöé
Γöé Γöémetafile. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_COLORTABLES ΓöéColor tables, color palettes. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_COLORREALIZABLE ΓöéRealization of metafile color Γöé
Γöé Γöétable. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_DEFAULTS ΓöéDrawing defaults values. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 9.1.2.3.1. PMF_RESET Option ΓòÉΓòÉΓòÉ
The PMF_RESET option, more so than the other array options, controls the
effects of other array options. This option allows a total reset of the
presentation space and provides further control of the following presentation
space environmental attributes:
Page units (device transform)
Page dimensions
Default viewing transform
Warning: If the metafile page units, page dimensions and page coordinate
format do not match those in the presentation space, playing the metafile will
cause an error.
The PMF_RESET option can have one of the values shown in the following table.
PMF_RESET Options for GpiPlayMetaFile
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRES_RESET ΓöéAllows the presentation space to be Γöé
Γöé Γöécompletely reset, just as if it were newly Γöé
Γöé Γöécreated, and the values of the Γöé
Γöé Γöéaforementioned environmental attributes to Γöé
Γöé Γöébe specified from the metafile into the Γöé
Γöé Γöépresentation space. Γöé
Γöé Γöé Γöé
Γöé ΓöéThis option is equivalent to specifying Γöé
Γöé ΓöéGRES_ALL on GpiResetPS. If this option is Γöé
Γöé Γöéused, the target presentation page is Γöé
Γöé Γöéredefined so that it is the same size, and Γöé
Γöé Γöédefined in the same units, as the metafile. Γöé
Γöé ΓöéIt also ensures that the physical size of Γöé
Γöé Γöéthe metafile picture is preserved if the Γöé
Γöé Γöépresentation page is defined in units other Γöé
Γöé Γöéthan pels, or arbitrary units. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRES_NORESET ΓöéPrevents resetting of the presentation Γöé
ΓöéRES_DEFAULT Γöéspace. The existing presentation space Γöé
Γöé Γöévalues of the environmental attributes will Γöé
Γöé Γöébe preserved, and their values in the Γöé
Γöé Γöémetafile will be discarded. Γöé
Γöé Γöé Γöé
Γöé ΓöéIf this option is used, ensure that the Γöé
Γöé Γöépresentation-page units of the target Γöé
Γöé Γöépresentation space are the same as those Γöé
Γöé Γöéwith which the metafile was generated, Γöé
Γöé Γöébefore you play a metafile into the Γöé
Γöé Γöépresentation space. For example, if the Γöé
Γöé Γöéoriginal presentation page is defined in Γöé
Γöé Γöéincrements of 0.1 mm, the target Γöé
Γöé Γöépresentation page must be defined in the Γöé
Γöé Γöésame way. Γöé
Γöé Γöé Γöé
Γöé ΓöéTo change the format of the target Γöé
Γöé Γöépresentation page, if the presentation-page Γöé
Γöé Γöéformats do not match, issue GpiSetPS, but Γöé
Γöé Γöéonly if you know the metafile Γöé
Γöé Γöépresentation-page units. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
If you are certain that the settings of the current presentation space are
appropriate for the metafile, then you can play the metafile with the NO_RESET
option. To reset some or all of the current values in the target presentation
space, without redefining the presentation page, call:
1. GpiResetPS, with the GRES_ATTRS or GRES_SEGMENTS option
2. GpiPlayMetaFile, with the NO_RESET option.
The PMF_LCID option may be used to append or replace fonts from the metafile
to the fonts in the presentation space. The PMF_COLORTABLES option may be used
to append or replace color table entries in the presentation space from the
metafile. Other options (PMF_LOADTYPE, PMF_DEFAULTS, and so on) can be used to
selectively replace settings in the presentation space from the metafile.
Like the PMF_RESET option, other options, except for PMF_SUPPRESS, either:
Allow the values in the presentation space to be preserved and those in
the metafile to be discarded, or
Allow the presentation space to be loaded using the values in the
metafile.
If the first choice is used with RES_RESET, then the items controlled by the
PMF_options will be left set to their default reset state, otherwise it will
occur as described in the first choice above.
If the second choice is used with RES_RESET, then the items controlled by the
PMF_options are as described above. If it is used with RES_NORESET, then the
fonts and color tables in the metafile can append to the existing color tables
and fonts in the presentation space. Existing presentation space color table
entries and fonts, such as viewing transform will be replaced if respecified
in the metafile.
Note: If your application uses the attributes from the metafile, the
attributes that were specified in the presentation space before the metafile
was played are overwritten.
ΓòÉΓòÉΓòÉ 9.1.2.3.2. PMF_SUPPRESS Option ΓòÉΓòÉΓòÉ
The PMF_SUPPRESS option allows you to control the playing of the metafile. The
PMF_SUPPRESS option can have one of the values shown in the following table.
PMF_SUPPRESS Options for GpiPlayMetaFile
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSUP_SUPPRESS ΓöéThe operating system does not draw the Γöé
Γöé Γöémetafile on the device associated with the Γöé
Γöé Γöépresentation space. This option is useful ifΓöé
Γöé Γöéyou need to alter the presentation space Γöé
Γöé Γöébefore drawing it on an output device. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSUP_NOSUPPRESS ΓöéThe operating system draws the metafile on Γöé
ΓöéSUP_DEFAULT Γöéthe device associated with the presentation Γöé
Γöé Γöéspace. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
You can use the RES_RESET option to reinitialize the presentation space and
modify certain resources or presentation space environmental attributes from
the application before playing the remainder of the metafile by:
1. Saving the current state of the presentation space by calling GpiSavePS.
Use this function only if you wish to restore the previous state of the
presentation space after playing the metafile.
2. Calling GpiPlayMetaFile and specifying:
The PMF_RESET option with the value RES_RESET
The PMF_SUPPRESS option with the value SUP_SUPPRESS
This causes GpiPlayMetaFile to set the presentation space to the
specifications recorded in the metafile but not to play the picture in
the metafile.
3. Making any required changes to the presentation space.
4. Calling GpiPlayMetaFile and specifying:
The PMF_RESET option with the value RES_NORESET
The PMF_SUPPRESS option with the value SUP_NOSUPPRESS
This causes the picture to play.
5. Restoring the state of the presentation space after playing the metafile
by calling GpiRestorePS.
ΓòÉΓòÉΓòÉ 9.1.2.3.3. PMF_LOADTYPE Option ΓòÉΓòÉΓòÉ
The PMF_LOADTYPE option of GpiPlayMetaFile determines which viewing
transformations and graphics fields affect the metafile picture. The
PMF_LOADTYPE option can have one of the values shown in the following table.
PMF_LOADTYPE Options for GpiPlayMetaFile
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLT_ORIGINALVIEW ΓöéViewing transformations recorded in the Γöé
Γöé Γöémetafile are used in the target presentationΓöé
Γöé Γöéspace. Γöé
Γöé Γöé Γöé
Γöé ΓöéIf changes to the graphics field are Γöé
Γöé Γöérecorded in the metafile, the graphics fieldΓöé
Γöé Γöéin the target presentation space is updated,Γöé
Γöé Γöéand the picture is clipped to that graphics Γöé
Γöé Γöéfield. Γöé
Γöé Γöé Γöé
Γöé ΓöéChanges to the default viewing Γöé
Γöé Γöétransformation recorded in the metafile are Γöé
Γöé Γöéused to update the default viewing Γöé
Γöé Γöétransformation in the target presentation Γöé
Γöé Γöéspace. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLT_NOMODIFY ΓöéAny viewing transformations recorded in the Γöé
ΓöéLT_DEFAULT Γöémetafile are ignored. The metafile contents Γöé
Γöé Γöéare drawn in accordance with the current Γöé
Γöé Γöéviewing transformation in the target Γöé
Γöé Γöépresentation space. (Note that, if you also Γöé
Γöé Γöéspecify RES_RESET, the current viewing Γöé
Γöé Γöétransformation is reset to its default Γöé
Γöé Γöévalue.) Γöé
Γöé Γöé Γöé
Γöé ΓöéThe picture is clipped to any graphics fieldΓöé
Γöé Γöédefined in the target presentation space, Γöé
Γöé Γöéand any graphics field recorded in the Γöé
Γöé Γöémetafile is ignored. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The PMF_RESET option RES_RESET changes values in the target presentation space.
Therefore, the effect of the PMF_LOADTYPE option should always be considered in
conjunction with the PMF_RESET option. For example, if you specify both
RES_RESET and LT_NOMODIFY, the default viewing transformation in the target
presentation space is updated with that from the metafile, even though
LT_NOMODIFY means that such values should be ignored.
ΓòÉΓòÉΓòÉ 9.1.2.3.4. PMF_LCIDS Option ΓòÉΓòÉΓòÉ
The PMF_LCIDS option of GpiPlayMetaFile controls whether logical resources
referenced by a local identifier (lcid) are loaded from the metafile. Logical
resources include logical fonts and bit maps used as area-fill patterns. The
PMF_LCIDS option can have one of the values shown in the following table.
PMF_LCIDS Options for GpiPlayMetaFile
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLC_LOADDISC ΓöéLoads lcid-referenced resources from the Γöé
Γöé Γöémetafile. Γöé
Γöé Γöé Γöé
Γöé ΓöéIf the lcids of those resources are already Γöé
Γöé Γöéin use in the target presentation space, theΓöé
Γöé Γöéresources currently identified by those lcidΓöé
Γöé Γöés are deleted and their lcids are freed Γöé
Γöé Γöébefore the metafile contents are loaded. TheΓöé
Γöé Γöénew fonts and bit maps replace the existing Γöé
Γöé Γöéones in the presentation space. (If the Γöé
Γöé Γöéoperating system uses a local identifier Γöé
Γöé Γöéthat the application has already defined, Γöé
Γöé ΓöéGpiPlayMetaFile deletes the existing Γöé
Γöé Γöéidentifier before using it for the metafile Γöé
Γöé Γöéresource.) Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLC_NOLOAD ΓöéThe operating system uses the presentation Γöé
ΓöéLC_DEFAULTS Γöéspace's logical font and custom fill Γöé
Γöé Γöépattern; it will ignore any logical font or Γöé
Γöé Γöécustom fill pattern in the metafile. Γöé
Γöé Γöé Γöé
Γöé ΓöéAn application can use GpiSavePS and Γöé
Γöé ΓöéGpiRestorePS to maintain the local Γöé
Γöé Γöéidentifiers it has already defined. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 9.1.2.3.5. PMF_COLORTABLE Option ΓòÉΓòÉΓòÉ
The PMF_COLORTABLES option may be used to append or replace color table entries
in the presentation space from the metafile. The PMF_COLORTABLES option can
have one of the values shown in the following table.
PMF_COLORTABLES Options for GpiPlayMetaFile
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCTAB_REPLACE ΓöéReplaces the logical color table in the Γöé
Γöé Γöépresentation space with the color table Γöé
Γöé Γöéin the metafile. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCTAB_REPLACEPALETTE ΓöéReplaces the current palette, if it Γöé
Γöé Γöéexists, in the presentation space with Γöé
Γöé Γöéthe palette in the metafile. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCTAB_NOMODIFY ΓöéMaintains the logical color table in theΓöé
ΓöéCTAB_DEFAULT Γöépresentation space. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 9.1.2.3.6. PMF_COLORREALIZABLE Option ΓòÉΓòÉΓòÉ
The PMF_COLORREALIZABLE option may be used to select whether color table from
the metafile is realized upon loading. The PMF_COLORREALIZEABLE option can have
one of the values shown in the following table.
PMF_COLORREALIZABLE Options for GpiPlayMetaFile
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCREA_DOREALIZE ΓöéSets the realizable option when loading Γöé
Γöé Γöéthe color table. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCREA_NOREALIZE ΓöéDoes not set the realizable option when Γöé
ΓöéCREA_DEFAULT Γöéloading the color table. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 9.1.2.3.7. PMF_DEFAULTS Option ΓòÉΓòÉΓòÉ
The PMF_DEFAULTS option can have one of the values shown in the following
table.
PMF_DEFAULTS Options for GpiPlayMetaFile
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue ΓöéDescription Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDDEF_LOADDISC ΓöéReplaces the default attributes, defaultΓöé
Γöé Γöéviewing limits, and default arc Γöé
Γöé Γöéparameters in the presentation space Γöé
Γöé Γöéwith the values specified in the Γöé
Γöé Γöémetafile. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDDEF_IGNORE ΓöéMaintains the default attributes, Γöé
ΓöéDDEF_DEFAULTS Γöédefault viewing limits, and default arc Γöé
Γöé Γöéparameters in the presentation space. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 9.1.2.4. Saving a Metafile ΓòÉΓòÉΓòÉ
A metafile is not a permanent object and, unless it is explicitly saved,
disappears when the application that creates it ends. Metafiles are saved in
disk files by calling GpiSaveMetaFile.
This function accepts as input the metafile handle and the name of the disk
file in which the metafile is to be saved. As the disk file is created by this
function, an error condition is raised if a file with this name already exists.
When you call GpiSaveMetaFile, the memory version of the metafile is deleted.
Its handle is no longer valid, until the file is reloaded from disk.
ΓòÉΓòÉΓòÉ 9.1.2.5. Loading a Metafile ΓòÉΓòÉΓòÉ
A metafile saved on disk has to be reloaded before it can be used. Any
application with access to the disk file can transfer the file from disk
storage to application storage by calling GpiLoadMetaFile. GpiLoadMetaFile
returns a metafile handle, which identifies the metafile after it has been
loaded.
ΓòÉΓòÉΓòÉ 9.1.2.6. Editing a Metafile ΓòÉΓòÉΓòÉ
Metafiles can be edited in a manner similar to editing graphics segments. To
edit graphics orders in a metafile, an application transfers them into
application storage (an array of bytes) by calling GpiQueryMetaFileBits. The
number of graphics orders copied depends on the size of the array that the
application supplies. The application can determine the size of the metafile
(in bytes) by calling GpiQueryMetaFileLength. When the application has finished
editing the graphics orders, it can copy them back into the metafile by calling
GpiSetMetaFileBits.
Edited versions of metafiles can be saved by calling GpiSaveMetaFile. The disk
file that contains the edited version of the metafile cannot have the same name
as the file from which the metafile was originally loaded. GpiSaveMetaFile
raises an error condition if the disk file already exists.
ΓòÉΓòÉΓòÉ 9.1.2.7. Copying a Metafile ΓòÉΓòÉΓòÉ
A copy of a memory metafile can be made by calling GpiCopyMetaFile. PM makes a
copy of the metafile and returns a new handle to the new metafile.
ΓòÉΓòÉΓòÉ 9.1.2.8. Deleting a Metafile ΓòÉΓòÉΓòÉ
A memory metafile is deleted by calling GpiDeleteMetaFile. After the operation
is complete, the handle to the metafile no longer points to a usable object. A
disk file containing the metafile remains untouched by this operation. A disk
metafile is deleted by using operating system commands that delete any other
type of file.
ΓòÉΓòÉΓòÉ 9.1.3. Metafiles and the System Clipboard ΓòÉΓòÉΓòÉ
A metafile that you have created or loaded can be made available to other
applications at the same workstation by placing the handle to the metafile in
the system clipboard. When a resource is passed to the clipboard, it becomes
the property of the system, and is not deleted when the owning application
ends. Any application that can access the clipboard can retrieve the handle to
the metafile. Using the handle to the metafile, the application should copy the
metafile by calling GpiCopyMetaFile before closing the clipboard. The
application can then perform any metafile operation on the metafile.
ΓòÉΓòÉΓòÉ 9.2. Using Metafiles ΓòÉΓòÉΓòÉ
Use metafile functions to:
Create a metafile
Draw into a metafile
Load a metafile to disk
Load a metafile from disk into an application
Play a metafile
Edit a metafile
Copy a metafile
Transfer metafile contents to application memory
Transfer metafile contents from application memory
ΓòÉΓòÉΓòÉ 9.2.1. Creating and Drawing into a Metafile ΓòÉΓòÉΓòÉ
To create a metafile, you must:
1. Create a metafile device context with DevOpenDC.
2. Create a presentation space with GpiCreatePS, and associate the
presentation space with the metafile device context.
3. Draw into the metafile with various Gpi drawing functions.
4. Disassociate the metafile device context from the presentation space with
GpiAssociate.
5. Close the metafile device context with DevCloseDC.
The following figure shows how to create a simple metafile that draws text
within the borders of a three-color box.
#include <os2.h>
void fncMETA01(void){
DEVOPENSTRUC dop;
HDC hdcMeta;
HPS hpsMeta;
HMF hmf;
HAB hab;
SIZEL sizlPage;
POINTL ptl;
dop.pszLogAddress = (PSZ) NULL;
dop.pszDriverName = "DISPLAY";
hdcMeta = DevOpenDC(hab,
OD_METAFILE, /* Metafile device context */
"*", /* Ignores OS2.INI */
2L, /* Uses first two fields */
(PDEVOPENDATA) &dop, /* Device information */
(HDC) NULLHANDLE); /* Compatible device context */
hpsMeta = GpiCreatePS(hab,
hdcMeta, /* Metafile device context */
&sizlPage, /* Page viewport */
PU_PELS | GPIA_ASSOC); /* Device units and associated context */
/* Draw a box in a metafile. */
GpiSetColor(hpsMeta, CLR_CYAN);
ptl.x = 150; ptl.y = 200;
GpiMove(hpsMeta, &ptl);
ptl.x = 300; ptl.y = 275;
GpiBox(hpsMeta, DRO_FILL, &ptl, 0L, 0L);
GpiSetColor(hpsMeta, CLR_GREEN);
ptl.x = 300; ptl.y = 200;
GpiMove(hpsMeta, &ptl);
ptl.x = 390; ptl.y = 275;
GpiBox(hpsMeta, DRO_FILL, &ptl, 0L, 0L);
GpiSetColor(hpsMeta, CLR_YELLOW);
ptl.x = 390; ptl.y = 200;
GpiMove(hpsMeta, &ptl);
ptl.x = 530; ptl.y = 275;
GpiBox(hpsMeta, DRO_FILL, &ptl, 0L, 0L);
ptl.x = 175; ptl.y = 230;
GpiMove(hpsMeta, &ptl);
GpiSetColor(hpsMeta, CLR_PINK);
GpiCharString(hpsMeta, 41,
"METAFILE COPY METAFILE COPY METAFILE COPY");
GpiAssociate(hpsMeta, (HDC) NULLHANDLE);
hmf = DevCloseDC(hdcMeta);
} /* fncMETA01 */
Creating a Metafile
ΓòÉΓòÉΓòÉ 9.2.2. Drawing into a Metafile in Retain Mode ΓòÉΓòÉΓòÉ
To draw into a metafile, set the drawing mode to the appropriate value for your
application and then perform the drawing operations. The following figure shows
an example of how to copy the contents of a segment into a metafile.
#define INCL_GPIMETAFILES
#define INCL_GPICONTROL
#include <os2.h>
void fncMETA02(void){
HDC hdcMeta, hdc;
POINTL ptl;
HMF hmf;
LONG alOpt[10];
HPS hps;
/*
* Open a segment, assign it an identifier of 10,
* and draw some text into it.
*/
GpiSetDrawingMode(hps, DM_RETAIN);
GpiOpenSegment(hps, 10L);
ptl.x = 175; ptl.y = 230;
GpiMove(hps, &ptl);
GpiSetColor(hps, CLR_PINK);
GpiCharString(hps, 41,
"METAFILE COPY METAFILE COPY METAFILE COPY");
GpiCloseSegment(hps);
GpiAssociate(hps, NULLHANDLE); /* Disassociates PS and screen DC */
GpiAssociate(hps, hdcMeta); /* Associates PS and meta DC */
GpiDrawSegment(hps, 10L); /* Draws segment into metafile */
GpiAssociate(hps, NULLHANDLE); /* Disassociates PS and meta DC */
hmf = DevCloseDC(hdcMeta); /* Closes metafile */
GpiAssociate(hps, hdc); /* Associates PS and screen DC */
GpiSetDrawingMode(hps, DM_DRAW); /* Sets drawing mode to DM_DRAW */
/*
* Load the array of options for GpiPlayMetaFile
* with default values.
*/
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_DEFAULT; /* Default transformations */
alOpt[PMF_RESOLVE] = 0; /* Reserved */
alOpt[PMF_LCIDS] = LC_DEFAULT; /* Uses default lcids */
alOpt[PMF_RESET] = RES_DEFAULT; /* Uses default */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Uses default */
alOpt[PMF_COLORTABLES] = CTAB_DEFAULT; /* Uses default */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Uses default */
GpiPlayMetaFile(hps, /* Plays metafile onto screen */
hmf, 8L, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA02 */
Copying a Graphic Segment to a Metafile
If you want to create a simple drawing in a metafile for repeated display, you
can set the drawing mode to DM_DRAW and draw directly into the metafile. The
code in the first code fragment shows an example of how to do this. You can
store named segments in the metafile that you are recording in DM_DRAW mode by
bracketing your output primitive functions between GpiOpenSegment and
GpiCloseSegment.
ΓòÉΓòÉΓòÉ 9.2.3. Copying a Metafile to Disk ΓòÉΓòÉΓòÉ
You can copy a metafile to disk using GpiSaveMetaFile, and you can load the
file back into your application using GpiLoadMetaFile. The following figure
shows an example of how to copy a metafile to a file named META.MET, then load
the same file back into the application and play it.
#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA03(void){
HMF hmf;
HAB hab;
HPS hps;
LONG alOpt[10];
GpiSaveMetaFile(hmf, "meta.met"); /* Saves metafile on disk */
hmf = GpiLoadMetaFile(hab, "meta.met"); /* Loads metafile */
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_DEFAULT; /* Default transformations */
alOpt[PMF_RESOLVE] = 0; /* Reserved */
alOpt[PMF_LCIDS] = LC_DEFAULT; /* Uses default lcids */
alOpt[PMF_RESET] = RES_DEFAULT; /* Uses default */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Uses default */
alOpt[PMF_COLORTABLES] = CTAB_DEFAULT; /* Uses default */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Uses default */
GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA03 */
ΓòÉΓòÉΓòÉ 9.2.4. Playing a Metafile ΓòÉΓòÉΓòÉ
The following figure shows an example of how to play the metafile using the
font, color table, and fill-pattern descriptions in your application's
presentation space.
#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA04(void){
HPS hps;
HMF hmf;
LONG alOpt[10];
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_DEFAULT; /* Viewing transformation in PS */
alOpt[PMF_RESOLVE] = RS_DEFAULT; /* Reserved */
alOpt[PMF_LCIDS] = LC_DEFAULT; /* Font and fill pattern in PS */
alOpt[PMF_RESET] = RES_DEFAULT; /* Page units and dimensions in PS */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Draws metafile into PS */
alOpt[PMF_COLORTABLES] = CTAB_DEFAULT; /* Color table in PS */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Sets realizable option */
GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA04 */
The following figure shows an example of how to play a metafile using the font,
color table, and fill-pattern descriptions in the metafile.
#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA05(void){
HPS hps;
HMF hmf;
LONG alOpt[10];
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_DEFAULT; /* Viewing transformation in PS */
alOpt[PMF_RESOLVE] = RS_DEFAULT; /* Reserved */
alOpt[PMF_LCIDS] = LC_LOADDISC; /* Font and fill pattern in metafile */
alOpt[PMF_RESET] = RES_DEFAULT; /* Page units and dimensions in PS */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Draws metafile into PS */
alOpt[PMF_COLORTABLES] = CTAB_REPLACE; /* Color table in metafile */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Sets realizable option */
GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA05 */
The following figure shows an example of how to play a metafile using the
viewing transformation, page units, and presentation-page dimensions specified
in the metafile.
#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA06(void){
HPS hps;
HMF hmf;
LONG alOpt[10];
alOpt[PMF_SEGBASE] = 0; /* Reserved */
alOpt[PMF_LOADTYPE] = LT_ORIGINALVIEW; /* Viewing transformation */
alOpt[PMF_RESOLVE] = RS_DEFAULT; /* Reserved */
alOpt[PMF_LCIDS] = LC_DEFAULT; /* Font and fill pattern in PS */
alOpt[PMF_RESET] = RES_RESET; /* Page units/dimensions */
alOpt[PMF_SUPPRESS] = SUP_DEFAULT; /* Draws metafile into PS */
alOpt[PMF_COLORTABLES] = CTAB_DEFAULT; /* Uses color table in PS */
alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Sets realizable option */
GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA06 */
ΓòÉΓòÉΓòÉ 10. Print Job Submission and Manipulation ΓòÉΓòÉΓòÉ
The print subsystem of the OS/2 operating system provides a flexible,
high-level interface between your application and an output device. Because
most of the internal workings of the subsystem are shielded from both user and
programmer, this chapter concentrates on the programming process required to
produce hard copy output. Querying of printer resources, working under a
specific user's environment, designing for application-specific requirements,
and manipulation of print jobs also are described.
ΓòÉΓòÉΓòÉ 10.1. About the Print Subsystem ΓòÉΓòÉΓòÉ
This section describes:
The print subsystem components
The print subsystem configuration
Printing data flow
ΓòÉΓòÉΓòÉ 10.1.1. Print Subsystem Components ΓòÉΓòÉΓòÉ
The print subsystem comprises the following software components of the
operating system:
Spooler
Print subsystem user interface
Queue drivers (queue processors)
Printer drivers
File system
Kernel device drivers
ΓòÉΓòÉΓòÉ 10.1.1.1. Spooler ΓòÉΓòÉΓòÉ
The spooler is the central coordinating process for the print subsystem. It
gives the user flexibility in organizing and optimizing the use of the system's
printers. The spooler has a global view of the system's printing resources,
particularly in a server environment and therefore is able to make the best use
of those resources.
The spooler ensures that print output from two separately executing
applications cannot be intermixed on the printer. As an optional
optimization, the spooler can start a printing job before it is
completely queued. Any successive jobs are queued normally.
The spooler can print a job in the background while the user continues to
use the application. Other single-tasking operating systems, such as DOS,
require the user to wait until the print output is sent completely to the
printer.
The spooler can send jobs from PM applications across a network to a
remote server, without the application's knowledge.
Note: The file system handles print jobs from non-PM applications.
Queues within the spooler can be used for various purposes. For example,
one queue could be used for large print jobs that are printed at times
when print demand is low. Another queue could be configured to print jobs
using a special size paper. Print jobs on this queue would be held until
the correct paper is loaded into the printer.
The spooler can support a number of printers simultaneously. It can be
configured so that jobs on a single queue can be shared among all the
printers. This load balancing, which is particularly important in server
environments, can be achieved without the application's knowledge.
Jobs can be prioritized while in the queue. For example, an urgent job
can be given a higher priority than ordinary jobs.
The spooler consists of one or more print queues, one for each printer object
defined by the user. Jobs are created by applications and placed in a queue,
waiting to print. When the previous job is completed, the next job in the
queue is sent to the printer.
ΓòÉΓòÉΓòÉ 10.1.1.1.1. Print Job Formats ΓòÉΓòÉΓòÉ
The print jobs held in a spooler queue are known as spool files. Spool files
contain the following:
Parameters submitted with the print job
Print job data
Print job data is in one of two formats:
PM_Q_STD
Standard output data, PM_Q_STD is spooled as a PM metafile; that is, as a
series of graphics orders stored in a packed binary format. PM_Q_STD
print jobs are created through the GPI.
An advantage of the PM_Q_STD format is that the files are smaller than
PM_Q_RAW format files. The smaller size saves disk space for jobs in the
spooler queue and reduces network traffic when transmitting the data to a
network server.
The content of PM_Q_STD jobs can be viewed using the PICVIEW application.
This is achieved using the job-content menu on a print job in the printer
object. The multi-page spool file can be shown in a device-independent
manner so that the content of the job can be recognized easily.
After a job is spooled and ready to print, the spooler sends the PM_Q_STD
job to the queue driver. The queue driver replays the metafile, through
the GPI, to the appropriate printer driver. The driver, in turn, converts
the data to printer-specific commands, that is, a printer-specific
format.
There are some restrictions on the content of PM_Q_STD jobs that are
related to the restrictions for PM metafiles. PM applications that cannot
deal with these restrictions should enqueue print jobs using PM_Q_RAW,
but there is an increase in required disk space and, possibly, network
traffic.
Print jobs sent to network servers that do not support PM are converted
automatically to the PM_Q_RAW format by the system. The application still
can continue specifying PM_Q_STD.
Note: The effect of converting all PM_Q_STD print jobs to PM_Q_RAW can
be turned on by the user's selecting Printer-specific format in a printer
object settings page.
PM_Q_RAW
Raw data, PM_Q_RAW, is the actual printer command to print the job. For
example, raw data created for an HP** LaserJet** printer contains Printer
Command Language (PCL) commands; and raw data created for a PostScript**
printer contains PostScript commands.
The content of PM_Q_RAW jobs can be viewed with the system editor. This
is achieved using the job content menu on a print job in the printer
object. However, it is not always easy to recognize the content of a job.
For example, PostScript is very hard to understand and get a visual idea
of the actual output.
Print jobs are created by the file system as a result of printing
directly to the physical port using either INT 17 or INT 21 under DOS or
the OS/2 DosOpen API. These print jobs always are queued using PM_Q_RAW.
The actual queue chosen depends on the port used and the configuration of
the print subsystem.
PM applications also can use the PM_Q_RAW format, but the overall
print-job creation process normally is slower because the printer driver
has to perform more work to create the printer-specific format.
If the Print while spooling printer object setting is turned on, the user
can perceive a faster response. In particular for a multi-page document,
the first page starts printing as soon as the printer driver has
completely finished converting the GPI to the printer-specific format.
Note: PM applications always should specify the PM_Q_STD format. The
difference in disk space used can be from a factor of 2 to a factor of 50. The
Printer-specific format and Print while spooling printer object settings can
be used to configure optimal performance for the environment.
Although the base operating system supports the two print job formats
described above, other formats can be supported by providing an appropriate
queue driver.
ΓòÉΓòÉΓòÉ 10.1.1.2. Disabling the Spooler ΓòÉΓòÉΓòÉ
The workplace user interface to control the spooler can be found in the System
Setup folder. For special circumstances or applications, the spooler object can
be used to disable the spooler. Generally, this is not recommended because the
output from two applications can intermix, or one application can be paused
until the first application has finished sending data to the printer.
ΓòÉΓòÉΓòÉ 10.1.1.3. Print Subsystem User Interface ΓòÉΓòÉΓòÉ
The print subsystem user interface is composed of printer objects. The spooler
implements each printer object by using a queue to hold the jobs. The queue is
connected to a logical device that specifies configuration data about the
actual physical device, for example, the port and printer drivers.
The print subsystem user interface performs the following basic functions:
Print job status
Opening a printer object folder displays an icon or detail view of the
print jobs waiting in the spooler queue. Opening the settings on an
individual job displays the parameters that were used when the job was
queued. Some settings, such as the number of copies, can be changed while
the print job is waiting in the queue.
Print job manipulation
Individual print jobs can be held in or released from the queue. Holding
a print job means that it is not printed. Individual or all the print
jobs in a queue can be deleted.
Queue manipulation
Queues also can be held, released, deleted, copied, or created using the
printer object context menu.
Printer object configuration
Opening a printer object settings notebook enables a user to browse and
modify the configuration of a printer object. For example, the printer
driver can be changed if the user just obtained new printer.
ΓòÉΓòÉΓòÉ 10.1.1.4. Queue Driver ΓòÉΓòÉΓòÉ
The queue driver is also called a queue processor. It is used to take print
jobs from a queue and print the data using the printer driver. The print job
data (either PM_Q_STD or PM_Q_RAW format) is passed through the GPI. For
PM_Q_STD jobs, GpiPlayMetaFile is used; and for PM_Q_RAW jobs, the DevEscape
DEVESC_RAWDATA is used.
ΓòÉΓòÉΓòÉ 10.1.1.5. Printer Driver ΓòÉΓòÉΓòÉ
Printer drivers know all details of the printer they support; therefore,
printer drivers are unique for each model of printer supported by the operating
system. The printer driver is responsible for:
Displaying a dialog that enables the user to inform the system how the
physical printer is configured; for example, which paper sizes are
installed.
Displaying a dialog that enables the user to configure an individual
print job; for example, which orientation (portrait or landscape) to use.
Responding to application queries for available printer capabilities such
as color, resolution and forms.
Converting the GPI commands in a print job to the printer-specific
language commands that will produce the expected output. The
printer-specific commands are passed to the file system.
ΓòÉΓòÉΓòÉ 10.1.1.6. Port Drivers ΓòÉΓòÉΓòÉ
Port drivers are dynamic link libraries (DLLs) that contain a set of 32-bit
functions, which provide helper functions for the spooler and Workplace Shell.
For each port driver DLL, there should be a physical port driver (SYS file)
installed in the CONFIG.SYS file. The file type of a port driver is .PDR.
The operating system, by default, provides two port drivers; SERIAL.PDR
supports COM1 - 4, and PARALLEL.PDR supports LPT1 - 3. For any other port, the
supplier of the physical port software is responsible for providing a
Presentation Manager port driver if it is necessary.
The functions exported from a port driver are:
SplPdEnumPort
SplPdGetPortIcon
SplPdInitPort
SplPdInstallPort
SplPdQueryPort
SplPdRemovePort
SplPdSetPort
SplPdTermPort
ΓòÉΓòÉΓòÉ 10.1.1.7. File System ΓòÉΓòÉΓòÉ
The file system is involved in both the spooling process and the printing
process. When non-PM applications create print data, the file system intercepts
the data and places it on a spooler queue. After a printer driver has processed
a print job, the file system sends the data to the appropriate file or device
using a kernel device driver.
ΓòÉΓòÉΓòÉ 10.1.1.8. Kernel Device Driver ΓòÉΓòÉΓòÉ
The system provides device drivers for physical devices. The two most commonly
used by the print subsystem are the parallel device driver and the serial
device driver.
ΓòÉΓòÉΓòÉ 10.1.2. Print Subsystem Configuration ΓòÉΓòÉΓòÉ
From a user's viewpoint, a printer object represents a printer. The user can
specify the printer object settings for configuration; for example, which
printer driver and port to use.
From a programmer's viewpoint, print configuration is more complicated. Each
printer object actually consists of a queue connected to a logical device. The
following figure shows some example configurations. The top-left and top-right
pictures show one printer object; the bottom-left picture shows two printer
objects; the bottom-right picture shows three printer objects.
Example Configurations of Queues, Devices, and Printer Objects
Multiple queues connected to a single device is termed printer sharing. The
advantage of printer sharing is that two queues can have different
configurations or be used for different purposes. For example:
One queue could be used for small jobs that are needed quickly, and the
other could be used for large jobs printed during times of low demand,
such as overnight.
One queue could be used for a normal form such as a letter, and the other
could be for a special form and so, would be held. When the special form
was loaded into the printer, that queue could be released and the normal
form queue could be held.
A single queue connected to multiple devices is termed printer pooling. This
allows print jobs to be shared among printers for load balancing. The spooler
does this by printing a job on the next available printer. For example, one
printer usually reserved exclusively for special forms could be connected to a
normal form queue during peak loads. The special form queue would be held
temporarily.
Note: Configuration of a device without a queue is not allowed by the OS/2
operating system.
The logical device has the following configuration parameters that are
relevant to application programmers:
Name and description
Logical port (for example, LPT1)
List of printer drivers
For example, a logical device representing an HP LaserJet printer with an
installed PostScript option could have both the HP LaserJet printer
driver and the PostScript printer driver in its configuration.
Each printer driver in the list also could have printer properties
associated with it. Printer properties describe the physical
configuration of the printer, such as what size paper is installed.
The queue has the following configuration parameters that are relevant to
application programmers:
Name and description
It is the queue description not the queue name that is used for the
printer object title- that is, the text displayed beneath a printer
object icon.
Printer driver
Default job properties
Job properties describe the parameters that must be used for printing a
specific job. An example of a job property is the orientation. The
queue's job property defaults are used if none are supplied by the
application.
Queue driver
Flags for Printer-specific format and Print while spooling settings
Separator page
Start and stop times
The configuration data for printer objects is stored in the OS2SYS.INI file.
The spooler provides a set of functions that can be used to query and set this
data.
Note: Older PM applications might still use the Profile functions (for
example, PrfQueryProfileString). If so, these applications must be recoded
with the new functions to avoid any dependencies on where and how the system
stores configuration data.
ΓòÉΓòÉΓòÉ 10.1.3. Printing Data Flow ΓòÉΓòÉΓòÉ
The data flow between your application, the printer driver, the spooler, and
the kernel device driver is shown in the following figure. In addition to the
data flow for the printer data stream, the data flow for screen output is
shown. From an application's point of view, creating output for a printer is
conceptually the same as creating screen output.
Overview of the Application Interface and Data Flow
There are three routes that the application's printer data can follow:
Base Printing
Base printing is provided primarily for non-PM programs writing complete
printer data streams, including all printer control codes, directly to a
printer port. It also provides compatibility for applications that run
under DOS or Microsoft** Windows**.
Queued PM Printing
Queued printing is recommended for all PM programs. It provides the most
flexibility, both for the application and the user.
Print jobs created by PM applications are queued on a spooler queue. The
spool files are processed and finally sent to the printer asynchronously
from the application.
Note: If the spooler is disabled, queued print jobs perform as though
they were submitted for PM direct printing.
Direct PM Printing
Conceptually, direct printing is the same as queued printing for the
application interface, but the spooler is bypassed. Therefore, the data
is sent directly to the printer, and the application has to wait until
the printing is finished. Following are some of the reasons for PM
applications to avoid direct printing:
- The print job can interfere with other users whose jobs are destined
for this printer. Print output could be mixed with the other print
jobs
- The spooler allows only one job at a time to print to a particular
port to avoid mixing of print job output. If your application tries
to print directly to the same port while another job is printing,
your user must wait for the current job to complete before the
user's job can begin.
- The printing application loses some of its multitasking advantages
because one job must complete before a second job is submitted.
- The printer device driver does not protect a print job from job
property and printer property mismatches.
- Pictures printed directly can be different from those printed
through a spooler. The default setting for direct printing is to
print pictures their actual size, whereas the default for queue
printing is scaled to fit for the output area.
Direct printing is recommended only for specialized applications that use
dedicated hard copy devices. Print jobs that have a certain degree of
security associated with them, such as a corporate payroll or
confidential documents, might best be handled with direct printing
because files in the spooler can be copied.
Jobs that are very large, that is, over 10MB, that you do not want copied
in the spool file, also might best be printed directly.
ΓòÉΓòÉΓòÉ 10.2. Using the Print Subsystem ΓòÉΓòÉΓòÉ
This section covers the following aspects of using the print subsystem:
Submitting a non-Presentation Manager (base) print job
Submitting a queued Presentation Manager print job
Submitting a direct Presentation Manager print job
Submitting a print job directly to the spooler
Spooler management and configuration
ΓòÉΓòÉΓòÉ 10.2.1. Submitting a Non-Presentation Manager (Base) Print Job ΓòÉΓòÉΓòÉ
A program can create a complete printer data stream including all printer
control codes (called a raw data stream) by using DosOpen, DosWrite, and
DosClose. This is called base printing and it is used by:
OS/2 and DOS Print command
(for example, PRINT CONFIG.SYS /D:LPT2)
OS/2 and DOS Copy command
(for example COPY CONFIG.SYS LPT1:)
OS/2 and DOS Redirected Output
(for example DIR > LPT1: or TYPE C:\CONFIG.SYS > LPT1:)
(full screen hard copy)
All DOS applications
All family applications (applications running under DOS and OS/2)
All Microsoft Windows applications.
Non-PM applications developed under OS/2 2.0 that must generate graphical data
must be able to generate all the necessary Escape Codes, or printer-specific
control sequences. Such applications will be coded differently, depending on
the printer family-for example, Epson**, HP** LaserJet**, LaserPrinter*,
Proprinter*, or PostScript**.
Non-PM applications that successfully drove the printer in the environment for
which they were designed-DOS for example-will continue to do so successfully
under this operating system.
DOS applications that directly access output hardware registers could have
difficulty printing under the operating system. If this is so, these
applications might need to be rewritten.
ΓòÉΓòÉΓòÉ 10.2.2. Submitting a Queued Presentation Manager Print Job ΓòÉΓòÉΓòÉ
There are several stages involved in using the PM programming interface to
print your application data. From a user interface point of view, the following
four dialogs must be provided. The exact order in which these dialogs are used
will govern the order of program execution.
Page setup dialog
The page setup dialog enables the user to specify the form name or size
required. Options on this dialog can include margins on the page, header
and footer strings, and whether duplex formatting is required.
The actual contents of the dialog depend on the type of application. The
important factor is that this page specify formatting options that also
are used to display to a screen.
Printer setup dialog
The printer setup dialog displays a list of queues available to the user.
A Job properties push button on this dialog enables the user to query and
modify the job properties for this job.
Font dialog
Most PM applications must enable the user to specify the font (or fonts)
required. Once the user has chosen a printer, an option on the fonts
dialog enables the user to choose from device fonts as well as system
fonts.
Print dialog
The application should have a Print menu item on the File menu to invoke
an application-specific print dialog. It is recommended that Shift+Print
Screen be used as an accelerator for printing the client area. The
Print-Screen key, unshifted, is used to capture and print a window or the
whole screen.
ΓòÉΓòÉΓòÉ 10.2.2.1. Page Setup Dialog ΓòÉΓòÉΓòÉ
The page setup dialog is concerned with formatting options for the document.
The user must be able to specify the form name, margins, and other
application-specific formatting options such as page duplexing; that is,
different formats for left and right pages in a multi-page document.
Note: The application is responsible for storing the user-defined margins for
the form. The application must not allow the user to specify margins smaller
than those returned by the printer driver.
Application Page Setup Dialog
ΓòÉΓòÉΓòÉ 10.2.2.1.1. Forms Selection ΓòÉΓòÉΓòÉ
If the user has not chosen a specific printer, the application can supply a
list of standard form sizes- for example, Letter, Legal, Ledger, A4, and A3.
The application also must consider, at a minimum, a 0.4 inch (10mm) margin on
the form to be within the hardware clip limits of most printers. See the
following table for the common form sizes.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéForm Name ΓöéSize in inches ΓöéSize in mm Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLetter Γöé8.5 x 11 Γöé216 x 279 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLegal Γöé8.5 x 14 Γöé216 x 356 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLedger Γöé11 x 17 Γöé279 x 432 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéA4 Γöé8.3 x 11.7 Γöé210 x 297 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéA3 Γöé11.7 x 16.5 Γöé297 x 420 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
When a printer is chosen, it must be queried, using DevQueryHardcopyCaps for
the forms it supports and the hardware clip margins. First, however, a device
context must be created. It is recommended that a OD_INFO context be used,
because OD_QUEUED can result in the creation of a print job. See the following
figure for a sample code fragment.
PPRDINFO3 pprd3Device; /* From SplQueryDevice */
PPRQINFO3 pprq3Queue; /* From SplQueryQueue */
PSZ pszTmp; /* Temporary pointer */
HDC hdc; /* Device context handle */
DEVOPENSTRUC dopData; /* DEVOPEN structure */
LONG clForms; /* Number of forms */
/* The device */
PHCINFO pchinfo; /* Forms information */
/* structure */
ULONG ulrc=DEV_OK; /* Return code */
/* Fill in data for devopendata for OD_INFO */
dopData.pszLogAddress = pprd3Device->pszLogAddr;
pszTmp = strchr(pprq3Queue->pszDriverName,'.');
if (pszTmp)
*pszTmp = '\0';
dopData.pszDriverName = pprq3Queue->pszDriverName;
dopData.pdriv = pprq3Queue->pDriverData;
/* Open the information device context */
hdc = DevOpenDC ( (HAB)0,
OD_INFO, /* Type */
"*", /* Default token */
3L, /* Count */
&dopData, /* Pointer to data */
(HDC)0); /* Comp dc */
/* Query number of forms available on the device */
clForms = DevQueryHardcopyCaps(hdc,
0L /* Start at beginning of list */
0L, /* Get number of forms */
NULL);
/* Allocate memory block for forms */
if (DosAllocMem((PPVOID(&pchinfo), clForms*sizeof(HCINFO), fALLOC))
{
DevCloseDC(hdc);
return(DEV_ERROR);
}
/* Query forms data */
ulrc = DevQueryHardcopyCaps(hdc,
0L, /* Start with first form */
clForms, /* Query all forms */
pchinfo); /* Structure to hold returned */
/* data */
/* Close the information device context */
DevCloseDC (hdc); /* Close the information */
/* device context */
/* Now use forms information in pchinfo */
DevQueryHardcopyCaps returns one HCINFO structure for each form. The contents
of the structure are:
ASCIIZ name of the form (for example, Letter)
Width and height (in millimeters) of the paper
Clipping limits (in millimeters) of the paper
Number of pels between clipping limits
Whether this form is the one installed currently on the device, or
whether it is selectable from another paper bin
Then the list of forms can be displayed to the user. The form preselected in
the list should be one of the forms marked with the HCINFO structure flag
HCAPS_CURRENT.
It is recommended that an application indicate to the user which forms are
currently installed in the printer. This is done by including the HCINFO
structure flag HCAPS_SELECTABLE. Then users can decide whether they want a
quick print on a form available from the printer or to install a different
paper tray in the printer.
ΓòÉΓòÉΓòÉ 10.2.2.2. Printer Setup Dialog ΓòÉΓòÉΓòÉ
In a printer setup dialog, an application should offer a list of printer
objects that are available to the user and enable the user to select one. (The
list of printer objects actually is a list of queues.) If none are available,
an appropriate message must be displayed. An application must query the list of
available printer objects each time the printer setup dialog is displayed
because the user might have created or modified the printer configuration while
the application was executing. The following figure is an example of a printer
setup dialog.
Application Printer Setup Dialog
Note: If the document was formatted for a particular device and the user
selects a different printer, the application must ask the user's permission
before reformatting the document for the new printer.
Use SplEnumQueue to query the list of printers (printer objects); printer
objects essentially are spool queues. SplEnumQueue returns both a list of
queues and information about each queue on the local workstation in an array of
PRQINFO3 structures. It also returns information about local workstation queues
that reference network print queues.
Because the number of queues might vary for each use of your application, it is
essential to allocate sufficient storage to hold the data returned by
SplEnumQueue. Usually the application issues the query twice: the first time,
the application determines the necessary size of the information buffer; after
allocating a memory block, the second query actually retrieves the information.
The SplEnumQueue parameter pcTotal contains the number of queues available on
the local system. The application should display an appropriate message box if
the value is 0.
The queue description (returned in the structure PRQINFO3 field name
pszComment) is the printer object title. This is much more familiar to the user
than the queue name, which is displayed only on the view settings page of a
printer object. Therefore, the printer setup dialog should show the queue
descriptions instead of the queue names.
SplEnumQueue returns information about the queue that might influence the
user's or application's decision to print to this queue; for example, the queue
priority, or the number of jobs already in the queue. SplEnumQueue also returns
the default job properties for the queue. This data can be used by the
application for the Job properties push button on the printer setup dialog.
Less sophisticated applications might decide to dispense with the printer setup
dialog and just print to the default queue. The default queue can be queried
using PrfQueryProfileString, with an application name of PM_SPOOLER and a
keyname of QUEUE. The spooler function SplQueryQueue then can be called to
retrieve the default job properties.
ΓòÉΓòÉΓòÉ 10.2.2.3. Job Properties Considerations ΓòÉΓòÉΓòÉ
Job properties are options on a per-job basis- for example, orientation,
resolution, and form selection. The job properties dialog is displayed by the
printer driver. Each driver has a different dialog, depending on the
capabilities of the printer. The job properties are held in a printer
driver-specific format in the abGeneralData field of the DRIVDATA structure.
Note: Job properties from one printer driver should not be given to another
printer driver; the job properties probably will not be understood, and the
printer driver will either return an error or substitute some default job
properties. Then the user will see a change in job properties stored
previously.
The user should be given the opportunity to change the job properties before
the job is printed. This can be achieved by supplying a Job properties push
button on the printer setup dialog.
Changing job properties requires two steps:
Retrieving job properties
Displaying the job properties dialog
ΓòÉΓòÉΓòÉ 10.2.2.3.1. Retrieving Job Properties ΓòÉΓòÉΓòÉ
The application can retrieve job properties from the following:
Previously saved job properties with the document
Current application session job properties
Default job properties from the queue (from pDriverData in the PRQINFO3
data structure)
Printer driver device defaults (from DevPostDeviceModes using the
DPDM_QUERYJOBPROP flag).
If no job properties were saved with the document, then there may be job
properties that are being used by another document that also is to be printed
to the same queue.
If job properties still cannot be found, then the default job properties
stored with the queue can be used. It may be that the user has not set up any
default job properties for the queue. Last, query the printer driver for its
device defaults using DevPostDeviceModes with the DPDM_QUERYJOBPROP flag.
ΓòÉΓòÉΓòÉ 10.2.2.3.2. Displaying Job Properties Dialog ΓòÉΓòÉΓòÉ
The sample code in the following figure shows how to display the job properties
dialog. All the parameters required are available from the PRQINFO3 structure
returned by SplEnumQueue or SplQueryQueue.
In the case of printer pooling, the pszPrinters field of the PRQINFO3 structure
contains a list of device names, separated by commas. It is sufficient to
choose the first printer in the list because the printer object ensures that
the configuration of each spooled printer is the same.
Note: It is possible that the printer driver now uses a larger buffer for the
job properties than the application is expecting. This occurs when a new
version of a printer driver that supports some additional features is
installed. In this case, the application must discard the existing document job
properties, after a confirmation from the user, and query the printer driver
for its device defaults, using the DPDM_QUERYJOBPROPS parameter to
DevPostDeviceModes.
#define INCL_DEV
#define INCL_DOS
#include <os2.h>
#include <memory.h>
{
ULONG ulrc=FALSE;
HAB hab;
PPRQINFO3 pprq3Queue; /* From SplEnumQueue or SplQueryQueue */
PSZ pszDriverName,pszDeviceName,pszTmp;
HDC hdc=NULL;
LONG cbBuf;
/* Use the first device name in the PRQINFO3 structure */
pszTmp = strchr(pprq3Queue->pszPrinters, ',');
if (pszTmp)
*pszTmp = '\0';
/* Use just the driver name from the driver.device string */
pszDeviceName = strchr(pprq3Queue->pszDriverName, '.');
if (pszDeviceName)
{
*pszDeviceName = '\0';
pszDeviceName++;
}
/* Check size of buffer required for job properties */
cbBuf = DevPostDeviceModes( hab,
(PDRIVDATA)NULL,
pprq3Queue->pszDriverName,
pszDeviceName,
pprq3Queue->pszPrinters,
DPDM_POSTJOBPROP
);
/* Return error to caller */
if (cbBuf<=0)
return(cbBuf);
/* Return BUFFER TOO SMALL error to caller */
if (cbBuf > pprq3Queue->pDriverData->cb)
return(DPDM_ERROR);
/* Display job properties dialog & get updated job properties from driver */
ulrc = DevPostDeviceModes( hab,
pprq3Queue->pDriverData,
pprq3Queue->pszDriverName,
pszDeviceName,
pprq3Queue->pszPrinters,
DPDM_POSTJOBPROP
);
return(ulrc);
}
ΓòÉΓòÉΓòÉ 10.2.2.4. Font Dialog and Device Font Considerations ΓòÉΓòÉΓòÉ
There are two types of fonts:
System fonts, which can be used for both displays and printers, and
therefore, are generally more flexible.
Device fonts, which are specific to a particular device. Device fonts for
printers can be built-in or be installed with font cartridges by a user.
Device fonts also can be available on diskette (also termed soft fonts)
and can be downloaded to the printer as required by the printer driver.
The advantage of device fonts is that, usually, they are printed in the
highest resolution of the device and are faster than system fonts.
Note: Some printer drivers, in particular, the HP LaserJet (LASERJET) and the
LaserPrinter (IBM4019) printer drivers provide an intermediate solution. An
option on the job properties dialog enables system fonts to be downloaded to
the printer as soft fonts.
As stated earlier, an application must provide the user with the ability to
choose fonts and, in particular, to choose a device font over a system font to
achieve better performance. A standard font dialog box should be used (see
WinFontDlg).
When an application uses device fonts, and the output mixes text and graphics
pictures, the device fonts are clipped per character. System fonts give more
precise clipping to the pel. The following figure illustrates the results from
clipping two lines of text: one generated in a system font; the other, in a
device font.
Character Clipping Results for Device and System Fonts
The available device fonts can be queried, using GpiQueryFonts, in either an
OD_INFO or an OD_QUEUED device context. Device fonts are returned with
negative lMatch numbers. Then the appropriate logical font can be used after
calling GpiCreateLogFont.
If, during the printing process, a logical font is not created, the printer
driver uses its default font for the printer, which usually is 12-point
Courier.
There are two design choices for device fonts:
Use system fonts for the display. When printing, query the printer driver
and attempt to choose a device font that closely matches the system font.
If no match is found, then print using the system font. A device's font
metrics and character spacing might not match exactly, so the printed
output might not be exactly the same as the display.
Use a printer font if the user selects one. Determine the metrics and
find a system font that shares the same characteristics (for example, a
style such as Courier or Serifed). The character string to be displayed
is sent to the printer driver and the inter-character spacing is
returned, using GpiQueryCharStringPos. The individual character positions
are used when the string is sent to the display, using GpiCharStringPos
with the flOptions parameter of CHS_VECTOR. While the display output can
take longer to display to the screen, true WYSIWYG (What You See Is What
You Get) is achievable.
ΓòÉΓòÉΓòÉ 10.2.2.5. Print Dialog and Print Processing ΓòÉΓòÉΓòÉ
The print menu must display a dialog to enable the user to specify the number
of copies, start page, end page, or any other application-specific print
options. A confirm push button (for example, Print) initiates the print. The
following figure is an example of a print dialog.
Application Printer Setup Dialog
The Printer entry field is the read-only name of the printer object (queue)
that the user chose from the Printer Setup dialog. The Preview checkbox is used
to preview the printed output on the screen. This can be achieved by opening an
OD_MEMORY device context to the printer driver and drawing the picture into the
bit map. A BITBLT (Bit Block Logical Transfer) to the screen shows the
resultant page. System fonts should be used instead of device fonts.
Once the user has initiated the print, a PM application must execute the
following steps.
1. Create a new thread.
Then, on this new thread:
2. Open a device context.
3. Associate a presentation space.
4. Start the print job.
5. Query the device capabilities.
6. Format the page.
7. Start the next page.
Repeat steps 6 through 7 for each page.
8. End the print job.
For another print job, repeat from step 4.
9. Disassociate the presentation space.
10. Close the device context.
The following sections describe each of the above steps in turn.
ΓòÉΓòÉΓòÉ 10.2.2.5.1. Creating a New Thread ΓòÉΓòÉΓòÉ
Once the print process has been confirmed by the user. the application must use
a separate thread to perform the actual printing. This maintains user
responsiveness and avoids displaying the hourglass pointer. While the printing
is in progress, the application should dim certain menu options, such as
drawing. Other options, such as page down, zoom, or help still must be
available.
ΓòÉΓòÉΓòÉ 10.2.2.5.2. Opening a Queued Device Context ΓòÉΓòÉΓòÉ
Before you can send data to a printer using device functions, you must open a
device context with DevOpenDC. The parameters of DevOpenDC are influenced by
the queue and job properties the user has chosen previously.
DevOpenDC accepts the following parameters as input:
hab The anchor-block handle from a WinInitialize call.
lType The type of device context. This always is OD_QUEUED to specify
a queued device context.
pszToken The device-information token. Always use an asterisk (*) for
this parameter to force the system to get device information
from the pdopData parameter.
lCount The number of data elements supplied in the pdopData parameter.
The minimum number of parameters for a queued device context is
4.
pdopData The device-context data area. This is a pointer to a structure
of the type DEVOPENSTRUC. The elements of this structure are
described below.
hdcComp The compatible-device-context handle. This must be NULL for a
device context of type OD_QUEUED.
DevOpenDC returns a device-context handle of type HDC. The handle is used in
other functions beginning with the Dev prefix and for GpiCreatePS and
GpiAssociate.
The DEVOPENSTRUC structure contains all the data needed to define a device
context.
The individual elements of the DEVOPENSTRUC structure are described below. At
least the first four structure members must be provided for queued device
contexts.
pszLogAddress Name of the queue. It is the pszName field of the
PRQINFO3 structure.
Note: For device contexts of type OD_INFO, pszLogAddress
is the port name. This can be retrieved by calling
SplQueryDevice using the pszPrinters device name. The
pszLogAddr field in the PRQINFO3 structure is the port
name.
pszDriverName Character string identifying the printer driver, for
example, LASERJET. The pszDriverName field of the PRQINFO3
structure, associated with the required print queue, gives
the driver and device name, separated by a period, for
example LASERJET.HP LaserJet IIID The pszDriverName field
can contain only the name up to the period, for example
LASERJET.
pdriv This is a pointer to the job properties data returned by
the printer driver from DevPostDeviceModes or the default
job properties from pDriverData in the PRQINFO3 structure.
Note: The DRIVDATA structure contains the particular
device name to be used. Therefore, it is a programming
error to set this parameter to NULL.
pszDataType It is recommended that PM_Q_STD always be used for the
data type.
pszComment Optional character string that the printer object displays
to the user in a job settings notebook. It is recommended
that the application include its own name in this comment
string.
Note: The job title text is derived from the document
name.
pszQueueProcName Queue processor name (optional). The queue processor
(also termed queue driver) name is available from the
pszPrProc field of the PRQINFO3 structure. The default
queue processor provided by the operating system is
PMPRINT. The user also can install a queue processor
(PMPLOT) that is used to provide reverse clipping for
vector devices such as plotters.
For specialized applications, it is possible to use an
alternative queue processor to the default specified for
the queue. The list of installed queue processors is
available from the OS2SYS.INI file using the application
name PM_SPOOLER_QP.
pszQueueProcParams Queue processor parameters (optional). They can include
information such as the number of copies you want to print
and the size of the output area on the printed page. See
PMPRINT/PMPLOT Queue Processor Parameters for details.
pszSpoolerParams Spooler parameters (optional) are separated by spaces.
They are used for scheduling print jobs and are as
follows:
The form names that identify the paper to be used,
for example, FORM=A4,A5,ENV. The form names are
optional, but if they are provided, the spooler is
able to hold off printing the jobs until the required
form is installed in the printer. If the form name is
not provided, the spooler attempts to print the job.
The printer driver recognizes that there is a forms
problem and displays a FORMS MISMATCH message box.
Priority of the print job, for example, PRTY=60. The
priority is specified as an integer in the range 1
through 99; 99 is the highest. The default priority
value is 50. The application can use the spooler
priority parameter to prioritize its own jobs.
However, it is not good practice for an application
always to use priority 99 in an attempt to get its
jobs printed first.
pszNetworkParams Optional parameter that can be used to specify network
options; for example, USER=JOESMITH.
ΓòÉΓòÉΓòÉ 10.2.2.5.3. Associating a Presentation Space ΓòÉΓòÉΓòÉ
In order to print, a device context must be associated with a GPI presentation
space (PS).
In most circumstances, a presentation space already exists for the screen. In
such cases, the PS can be disassociated with the window device context and
associated with the printer device context by using GpiAssociate, as shown in
the following figure.
Reassociating Presentation Space with Device Contexts
If a presentation space does not exist or a different one is to be used, the
application must call GpiCreatePS and use the GPI_ASSOC flag to associate the
printer device context.
Device-Independence Considerations
The operating system supports true WYSIWYG. The same GPI functions the
application used to create the picture or document on the display screen can be
used to create the output on a printer. This is the major advantage of device
independence.
An application must be designed around the options provided by the PM to ensure
device independence, as a display (VGA) typically is 96 dpi, while a printer
typically is 300 dpi.
Following are some application design considerations:
Use DevQueryHardopyCaps to determine the horizontal and vertical width of
the form and the maximum printable area.
Create a presentation space with a presentation page size of 0 to ensure
that the maximum window size and maximum page size are used.
Use device-independent coordinates, such as LO_ENGLISH, or TWIPS. If you
program in pels, transferring your output from screen to hard copy will
compress the image, as shown in the following figure.
An Effect of Programming in Pels
Reassociating a presentation space defined in pels or other device
dependent units can affect the dimension of the picture. If the pels are
not square on the display device, the shape and scale (aspect ratio) will
be different as well.
ΓòÉΓòÉΓòÉ 10.2.2.5.4. Starting a Print Job ΓòÉΓòÉΓòÉ
The application signals the beginning of a print job by using DevEscape with
the escape parameter DEVESC_STARTDOC. The application must specify a document
name; usually this is related to the name of file being printed. Any GPI calls
made before this DevEscape (DEVESC_STARTDOC) are ignored.
ΓòÉΓòÉΓòÉ 10.2.2.5.5. Querying the Device Capabilities ΓòÉΓòÉΓòÉ
DevQueryCaps can be used to provide over 40 pieces of information about a
specific device-for example, default character box size, horizontal and
vertical resolution, or number of device-specific fonts.
Knowing that the device has only 1-bit color support (monochrome) might
influence the application to use line style and patterns instead of colors for
output.
ΓòÉΓòÉΓòÉ 10.2.2.5.6. Formatting the Page ΓòÉΓòÉΓòÉ
Before print processing actually starts, it is recommended that an
application's modal dialog be displayed, showing page progress and enabling the
user to cancel the print job. If the user presses Cancel on this dialog, the
application must call DevEscape with the parameter DEVESC_ABORTDOC. This allows
the spooler and printer driver to clean up. A job is not created in the queue.
Usually the output on a page is generated by a series of GPI calls from the
application. By calculating the size of character strings or graphics written
to the presentation space, the application must be able to decide when to move
to the next page in a multi-page document.
ΓòÉΓòÉΓòÉ 10.2.2.5.7. Starting the Next Page ΓòÉΓòÉΓòÉ
When the application has finished processing a page, it must call DevEscape
with the DEVESC_NEWFRAME parameter. The progress dialog must be updated. The
DevEscape DEVESC_NEWFRAME can be used to generate blank pages. The printer
driver always issues a page eject whenever this DevEscape is received.
Issuing the DEVESC_NEWFRAME escape does not reset any attributes or fonts.
However, the bounds and any clipping regions are reset.
ΓòÉΓòÉΓòÉ 10.2.2.5.8. Ending the Print Job ΓòÉΓòÉΓòÉ
The end of a print document is signalled by the application's calling DevEscape
with the DEVESC_ENDDOC parameter. The spooler returns a job identifier that can
be used for job manipulation.
The following figure shows the processing carried out by a printer driver as it
receives device escapes and graphics from the GPI.
Flow for Device Escapes
Note: Each device-escape pair of DEVESC_STARTDOC and DEVESC_ENDDOC creates one
print job in a spooler queue. If the application needs to create multiple print
jobs, use the following sequence:
DevOpenDC
GpiCreatePS
DevEsape(DEVESC_STARTDOC)
.
.
.
DevEsape(DEVESC_ENDDOC)
DevEsape(DEVESC_STARTDOC)
.
.
.
DevEsape(DEVESC_ENDDOC)
DevCloseDC
ΓòÉΓòÉΓòÉ 10.2.2.5.9. Disassociating the Presentation Space ΓòÉΓòÉΓòÉ
When the print job is complete, the presentation space can be disassociated
with the printer device context using GpiAssociate with a NULL parameter. Then
the presentation space can be reassociated with the display device context.
ΓòÉΓòÉΓòÉ 10.2.2.5.10. Closing the Device Context ΓòÉΓòÉΓòÉ
A device context is closed using DevCloseDC. The print thread must signal print
termination to the main processing loop. The main loop can terminate the print
thread and dismiss the Page Progress message box.
An application can display a message box to the user indicating a successful
print and show the job ID returned by the spooler.
ΓòÉΓòÉΓòÉ 10.2.2.5.11. Print-to-File Considerations ΓòÉΓòÉΓòÉ
Print-to-file means that the print data destined for a printer is stored in a
file instead. The advantage of doing this is that the file can be used later,
possibly on a different machine or different environment, and the data printed
without requiring the original application.
The system provides three ways to print to file:
The user can specify Print to file on the Output settings page of a
printer object. When a print is requested, the system displays a dialog
in which the user can enter a file name.
This method is preferred because the application does not have to be
aware; the user has full control of the system.
The application can specify OD_DIRECT on a DevOpenDC call. The
pszLogAddress field of the DEVOPENSTRUC structure specifies the file name
as shown in the following example:
C:\TMP\MYPRINT.DAT
\\SERVER\DISK1\MYPRINT.DAT -- UNC file name
\\PIPE\PRTPIPE1 -- A pipe
LPT1 -- A port device
The application can create the printer-specific format data and write it
to a file using DosOpen.
ΓòÉΓòÉΓòÉ 10.2.2.5.12. Network Printing Considerations ΓòÉΓòÉΓòÉ
The architecture of PM requires a printer driver during the print job creation
process to deal with queries, such as DevQueryHardcopyCaps, and to provide the
job properties dialog by way of DevPostDeviceModes. To do any printing across a
network, a locally installed printer driver is required. In some cases, such as
when the network server does not run PM, this is an advantage, in that all the
conversion to printer-specific commands can be done on the requestor.
The printer object in the workplace provides seamless access to network
printers; the user need only install the appropriate printer driver.
The application programmer also is helped. A network printer that is accessed
by the user has a hidden shadow on the requestor. The job properties for the
shadow printer object can be altered and are stored on the requestor. This
enables the user to configure one or more variations on the original
configuration without requiring intervention from a system administrator to
create many network printer objects, each with a slightly different default job
property configuration.
The shadow printer object is created on the requestor by creating a local queue
and local device with no port connection. The application can enumerate these
queues using SplEnumQueue, as before. The only difference is in the PRQINFO6
structure; there are two extra fields not in the PRQINFO3 structure. These two
extra fields, named pszRemoteComputerName and pszRemoteQueueName contain the
name of the remote server and the remote queue. The spooler uses these fields
to automatically reroute print data, submitted by an application to the local
shadow, to the appropriate network queue.
The printer object creates a local shadow only when the network printer object
has been used or modified, because there could be a large number of network
printer objects, and the spooler does not know which one the user wants to use.
The local shadow of a network printer object is created in the following cases:
When a file is dragged and dropped on the network printer object
When the network printer object is moved, copied, or shadowed outside its
original server folder
When the printer or job properties are modified
ΓòÉΓòÉΓòÉ 10.2.2.5.13. Drag/Drop Protocol Considerations ΓòÉΓòÉΓòÉ
When an application data file is dropped on a printer object, the application
can receive a DM_PRINTOBJECT message if the application is running currently.
One DM_PRINTOBJECT parameter gives a DRAGITEM structure that describes the
object that was dropped. The other parameter gives a PRINTDEST structure that
contains all the parameters required to call DevPostDeviceModes and DevOpenDC.
The PD_JOB_PROPERTY flag indicates to the application that the user has
requested a job properties dialog before printing. If this flag is not set, the
application must not display the job properties dialog; it must use the job
properties passed in the PRINTDEST structure.
The rest of the printing process follows the procedure described in Submitting
a Queued Presentation Manager Print Job.
ΓòÉΓòÉΓòÉ 10.2.2.5.14. PMPRINT/PMPLOT Queue Processor Parameters ΓòÉΓòÉΓòÉ
How the queue processor processes a print job is controlled by the optional
queue-processor parameters that you can specify in the pdopData parameter of
DevOpenDC. The PM adds these parameter values to the spool file.
The PMPRINT/PMPLOT queue processor parameters enable an application to do the
following:
Specify the number of copies of a print job
Restrict printing to a specific area on the page
Specify which part of a picture is to be printed
Specify color output (if your printer allows this)
Specify the foreground and background colors in a monochrome print
Note: The application need not use queue processor parameters if all that is
required is a single copy of a picture, scaled to fit the page. These are the
default settings of the queue-processor parameters.
The first parameter (COP) is used for all spool-file formats. The remaining
parameters are valid for PM_Q_STD spool files only. Because PM_Q_STD data are
used mainly for graphic data, these parameters are described in relation to
the printing of picture files.
The PMPRINT/PMPLOT queue-processor parameters are separated by spaces and are:
COP=n
The COP parameter specifies the number of copies of the spool file
that you want printed. The value of n must be an integer in the
range of 1 through 999.
The default is COP=1.
ARE=C | w,h,l,t
The ARE parameter determines the size and position of the output
area. This is the area of the physical page to which printing is
restricted.
The default value of ARE=C means that the output area is the whole
page. Note, however, that the printer cannot print outside its own
device clip limits.
To size and position the output area at a specific point on the
page, use ARE=w,h,l,t, where:
w, h are the width and height of the desired output
area
l, t are the offsets of the upper-left corner of the
output area from the left (l) and from the top
(t) of the maximum output area
These four values must be given as percentages of the maximum output
dimensions. The maximum output area is the area within the device
clip limits.
FIT=S | l,t
The FIT parameter determines which part of the picture is to be
printed. You can request the whole of the picture, scaled to fit the
output area; or you can position the picture (actual size) anywhere
within the output area. This could mean that the picture is clipped
at the boundaries of the output area.
The default value of FIT=S causes the output to be scaled until the
larger of the height or width just fits within the defined output
area. The aspect ratio of the picture is maintained.
To print the picture in actual size, use FIT=l,t, where l,t are the
coordinates of the point in the picture that you want positioned at
the center of the output area: l is measured from the left edge of
the picture, and t is measured from the top edge. The coordinates
must be given as percentages of the actual dimensions of the
picture.
XFM=0 | 1
The XFM parameter enables you to override the picture-positioning
and clipping instructions that are provided by the ARE and FIT
parameters, including their defaults.
The default value of XFM= allows the appearance of the output to be
determined by the settings of the ARE and FIT parameters.
A value of XFM=0 yields output as specified in the picture file. For
example, applications that use many different forms can define
different positions on each form for their output.
COL=M | C
The COL parameter enables you to specify color output if you have a
color printer.
A value of COL=M creates monochrome output (black foreground with no
background color). This is supported by all devices.
A value of COL=C creates color output. If you request color output
on a monochrome device, the printer presentation driver tries to
satisfy your request, which can cause problems because the only
color available is black. For example, if the picture file specifies
a red line on a blue background, both are drawn in black.
The default is COL=M when you are addressing a monochrome printer
and COL=C when you are addressing a color printer.
MAP=N | A
The MAP parameter enables you to decide how the neutral colors
(those that are not specified in the picture file) are printed.
The default value of MAP=N yields a normal representation of the
screen picture on a printed page, which means that the page
background is white and the foreground is black.
A value of MAP=A provides the reverse of the normal representation:
the background is black and the foreground is white on the printed
page..
Note:
Pictures from a spool file can be printed differently than those printed when
the spooler is not selected, because the default setting without the spooler
is to print pictures their actual size, whereas the default for the
queue-processor FIT parameter is "scaled to fit" the output area.
The queue-processor parameters must be separated by one or more blank spaces;
for example,
"COP=3 ARE=C FIT=S".
The parameters can be listed in any order. Default values are used for
parameters that are omitted or entered incorrectly.
Bit-map or image data (data constructed by setting pels on or off) is not
affected by the ARE and FIT parameters. Consequently, if your picture contains
bit-map or image data, the printed version will be different from the screen
version if you use these parameters.
ΓòÉΓòÉΓòÉ 10.2.2.5.15. Examples Using the ARE and FIT Parameters ΓòÉΓòÉΓòÉ
The application uses the ARE and FIT parameters to determine which part of the
picture is printed, and where on the physical page it is printed. The following
figure provides practical examples of how to use these parameters.
Examples Using the ARE and FIT Parameters
ΓòÉΓòÉΓòÉ 10.2.3. Submitting a Direct Presentation Manager Print Job ΓòÉΓòÉΓòÉ
PM direct printing is done through a device context of type OD_DIRECT, as
follows:
1. Output from the PM printer driver goes directly to the printer instead of
to the spooler.
2. The application must specify OD_DIRECT in the DevOpenDC function.
3. The pszLogAddress field of the DEVOPENSTRUC structure is a port name (for
example LPT1). The port name is held in the pszLogAddr field of the
PRDINFO3 structure returned by SplEnumDevice or SplQueryDevice.
4. All fields following the pdriv field in the DEVOPENSTRUC structure are
ignored by the system.
The remaining steps in the printing process are the same as those for
OD_QUEUED device contexts.
ΓòÉΓòÉΓòÉ 10.2.4. Submitting a Print Job Directly to the Spooler ΓòÉΓòÉΓòÉ
The spooler provides functions that enable applications to submit print data
directly to a spool queue. Normally, these functions are used by printer
drivers to add a print job to a spool queue. However, this is not a recommended
method unless the application is special-purpose.
The advantage of submitting print data directly to a spool queue is to bypass
the GPI presentation layer. This can be useful, particularly, for sending print
jobs to a network printer that is on a server that does not run the OS/2
operating system. However, there are certain requirements for direct spooling:
Because the data bypasses the printer presentation driver, it must be in
a format the printer can understand. Therefore, the application must be
aware of and send the printer-specific commands.
If the spooler is not active, the print jobs never will be printed.
The following steps are required to create a print job using the spooler
directly:
1. Use SplQmOpen to open the PM. (Functionally, this is similar to using
DevOpenDC, which is detailed in Opening a Queued Device Context.) You
must specify a queue name of PMQOPENDATA for the logical address element,
pszLogAddress. PMQOPENDATA is a data structure, identical to
DEVOPENSTRUC, to be used with the SplQmxxx functions.
2. Use SplQmStartDoc to signal the start of your document. (This is same as
using DevEscape with DEVESC_STARTDOC as used in PM printing.)
3. Use SplQmWrite to write data to the spool file.
4. Use SplQmEndDoc to signal the end of your document. (This is the same as
DevEscape with DEVESC_ENDDOC as used in PM printing.)
5. Use SplQmClose to close the PM. (Functionally, this is similar to
DevCloseDC.)
ΓòÉΓòÉΓòÉ 10.2.5. Spooler Management and Configuration ΓòÉΓòÉΓòÉ
The spooler provides a set of functions that allows management of all aspects
of the print subsystem. There are five categories:
Job querying and manipulation (SplxxxJob)
Queue creation, querying, and manipulation (SplxxxQueue)
Device creation, querying, and manipulation (SplxxxDevice
Listing ports, printer drivers, queue processors (SplEnumyyy)
Listing printers across a network (SplEnumPrinter)
The symbol xxx typically represents Add, Delete, Enum, Query, and Set. For
jobs and queues, xxx also includes Hold and Release. For devices, xxx includes
Control. The symbol yyy is either Port, PrinterDriver, or QueueProcessor.
It is anticipated that most applications will not use any spooler functions at
all except SplEnumQueue, SplQueryQueue, and SplQueryDevice. However, there are
some specialized applications that might use the spooler functions for the
following:
An administrative tool to manage queues and jobs
An automatic printer object configurator
A new printer object can be created by using SplCreateDevice and
SplCreateQueue. The print subsystem recognizes that this has occurred and
puts a printer object directly on the desktop.
When the spooler is disabled, the following spooler functions do not return
any results:
SplControlDevice
SplCopyJob
SplDeleteJob
SplEnumJob
SplQueryJob
SplReleaseJob
SplSetJob
No function is available to enable or disable the spooler under application
control; this is a user decision. It is recommended that the spooler always be
enabled.
ΓòÉΓòÉΓòÉ 10.2.5.1. Print Job Management ΓòÉΓòÉΓòÉ
Some sophisticated applications might need to manipulate jobs in the following
ways after they have been spooled into a queue:
Modify the job parameters (for example, copies); use SplSetJob.
Increase the priority of a particular job; use SplSetJob.
Delete a job because a job based on newer data was created; use
SplDeleteJob.
ΓòÉΓòÉΓòÉ 11. Presentation Spaces and Device Contexts ΓòÉΓòÉΓòÉ
A presentation space is a data structure maintained by the operating system in
which information relevant to the graphic output is stored. The information is
related to both the subsequent drawings (such as colors or line styles) and the
presentation space resources (such as color tables or fonts).
The first task in a graphics application is to define a presentation space,
because so many of the GPI functions must operate within them. A presentation
space is required for each output device currently in use by your application,
including each separate window on the display screen. In almost all cases, the
presentation space is set up to be device-independent, because the requirements
of each possible output device are so different.
Note: In some cases, it is possible to disassociate a presentation space from
one device and associate it with another, thereby allowing the presentation
space to be shared.
To facilitate the device independence of the PM programming interface, all
device-specific information is held in a device context. A device context is a
data structure that identifies a particular instance of an output device and
contains all the device-specific information, such as the logical name of the
device and the presentation driver name. Each separate instance of an output
device that you intend to use must be described in a device context. For
example, if a single application uses more than one window, each of those
windows must have its own window device context.
The applicable device context, then, must be associated with the presentation
space in order to send graphics data to that output device.
This chapter describes presentation spaces and device contexts. The following
topics are related to the information in this chapter:
Graphics primitives
Coordinate spaces and transformations
Graphics segments
ΓòÉΓòÉΓòÉ 11.1. About Presentation Spaces ΓòÉΓòÉΓòÉ
There are three types of presentation spaces:
Standard micro
Cached micro
Normal
ΓòÉΓòÉΓòÉ 11.1.1. Micro Presentation Spaces ΓòÉΓòÉΓòÉ
You need a micro presentation space if your application creates a separate
presentation space for each output device instance and if its output is a
simple drawing.
Although run time memory requirements vary according to the graphics function
an application uses, a typical micro presentation space graphical application
uses 315KB of GPI, engine, and display memory resource (code and data). A micro
presentation space cannot be reassociated with a different device.
ΓòÉΓòÉΓòÉ 11.1.1.1. Standard Micro Presentation Space ΓòÉΓòÉΓòÉ
Use a standard micro presentation space for drawing on any type of output
device, provided the presentation space is not in retain mode or retain and
draw mode.
There are two different functions you can use to access a standard micro
presentation space. The following table lists both functions and their
considerations.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name ΓöéUsage ΓöéClosing Γöé
Γöé Γöé ΓöéFunction Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreatePS ΓöéAccepts an anchor handle, a ΓöéGpiDestroyPS Γöé
Γöé Γöédevice-context handle, and a Γöédestroys a Γöé
Γöé Γöépresentation space size as Γöépresentation Γöé
Γöé Γöéparameters. Creates both Γöéspace and Γöé
Γöé Γöénormal presentation spaces andΓöéreleases all Γöé
Γöé Γöémicro presentation spaces. Γöéresources ownedΓöé
Γöé Γöé Γöéby the Γöé
Γöé Γöé Γöépresentation Γöé
Γöé Γöé Γöéspace. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinGetScreenPS ΓöéThe presentation space ΓöéWinReleasePS Γöé
Γöé Γöérepresents the entire display Γöé Γöé
Γöé Γöéscreen. Warning: Exercise Γöé Γöé
Γöé Γöécaution when using this Γöé Γöé
Γöé Γöéfunction as the graphic outputΓöé Γöé
Γöé Γöécan overlap individual Γöé Γöé
Γöé Γöéwindows. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 11.1.1.2. Cached Micro Presentation Space ΓòÉΓòÉΓòÉ
The window manager maintains a cache of micro presentation spaces for windows
on a display screen. The cache is provided for applications that use a large
number of windows, and where each window requires a temporary
presentation-space device-context pair for a short sequence of output
operations. These presentation spaces belong to the system rather than to your
application and are allocated only on a temporary basis.
Cached micro presentation spaces are provided by the window system rather than
by the GPI. Their use is synchronized with other window activities. For
example, you need not associate a cached micro presentation space with the
display screen. The window manager does this for you.
Cached micro presentation spaces offer the best system performance because,
unlike normal presentation spaces and standard micro presentation spaces, they
are not permanently allocated to an application. However, cached micro
presentation spaces can be cumbersome to use because all the attributes must be
initialized continually.
Use a cached micro presentation space to send output only to a window on the
display device. There are three different functions you can use to access a
cached micro presentation space, each with its own considerations. These
functions are listed in the following table.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name ΓöéUsage ΓöéClosing Γöé
Γöé Γöé ΓöéFunction Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinBeginPaint ΓöéAccepts a NULL presentation ΓöéWinEndPaint Γöé
Γöé Γöéspace handle for a cached Γöéautomatically Γöé
Γöé Γöémicro presentation space. The Γöéreleases the Γöé
Γöé Γöépresentation space created by Γöépresentation Γöé
Γöé Γöéthis function is already Γöéspace, no Γöé
Γöé Γöépreassociated with the window Γöématter what Γöé
Γöé Γöédevice context, making this Γöétype. Γöé
Γöé Γöéthe easiest function to use. Γöé Γöé
Γöé ΓöéUsually this type of creation Γöé Γöé
Γöé Γöéis in response to a WM_PAINT Γöé Γöé
Γöé Γöémessage. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinGetScreenPS ΓöéThe presentation space ΓöéWinReleasePS Γöé
Γöé Γöérepresents the entire display Γöé Γöé
Γöé Γöéscreen. Γöé Γöé
Γöé ΓöéWarning: Exercise caution Γöé Γöé
Γöé Γöéwhen using this function as Γöé Γöé
Γöé Γöéthe graphic output can overlapΓöé Γöé
Γöé Γöéindividual windows. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinGetPS ΓöéThe presentation space can ΓöéWinReleasePS Γöé
Γöé Γöérepresent the entire desktop, Γöé Γöé
Γöé Γöéor any other window. Γöé Γöé
Γöé ΓöéThe presentation space can be Γöé Γöé
Γöé Γöéused to process any message, Γöé Γöé
Γöé Γöébut it must be returned to theΓöé Γöé
Γöé Γöécache when message processing Γöé Γöé
Γöé Γöéis complete. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
In general, use a cached micro presentation space to process a single paint
message when no presentation space information needs to be remembered between
messages. The presentation space must be both obtained and released during the
processing of that message. All application information stored in a cached
micro presentation space is lost as soon as it is released to the cache.
You must provide a window handle on input to WinBeginPaint and WinGetPS. The
resulting presentation space is defined specifically for that window, and
cannot be reassociated.
The cached micro presentation space is always:
Defined in pels-although you can change the units using GpiSetPS
Formatted GPIF_LONG
Given a suitable size by the system.
When you finish using a cached micro presentation space, you do not have to
disassociate it from the window device context because WinReleasePS or
WinEndPaint performs the disassociation. This makes the cached micro
presentation space available for use in other windows. The presentation space
itself cannot be deleted.
Cached micro presentation spaces are used serially. The next time you need a
cached presentation space, access a new one using the appropriate function.
Each time you get a cached micro presentation space, graphics attributes are
reset to their default values.
ΓòÉΓòÉΓòÉ 11.1.2. Normal Presentation Spaces ΓòÉΓòÉΓòÉ
You must use a normal presentation space if you require your application to use
the same presentation space to send output to multiple devices (a display
screen and printer, for example), or if it uses the segment and
retained-drawing functions to generate complex drawings.
There is only one function you can use to create a normal presentation space:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name ΓöéUsage ΓöéClosing Γöé
Γöé Γöé ΓöéFunction Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreatePS ΓöéAccepts an anchor handle, a ΓöéGpiDestroyPS Γöé
Γöé Γöédevice-context handle, and a Γöédestroys a Γöé
Γöé Γöépresentation space size as Γöépresentation Γöé
Γöé Γöéparameters. Creates both Γöéspace and Γöé
Γöé Γöénormal presentation spaces andΓöéreleases Γöé
Γöé Γöémicro presentation spaces. Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
If a normal presentation space is used, or if metafiling is carried out, more
run time memory is used than if a micro presentation space was used. A normal
presentation space requires 114KB more than a micro presentation space.
ΓòÉΓòÉΓòÉ 11.1.3. Modal Graphic Systems ΓòÉΓòÉΓòÉ
The graphic output sent to the presentation space is created by graphic
primitives, such as straight or curved lines. How those primitives appear
depends in part on the mode of the presentation space.
In modal systems, certain information that modifies a graphic primitive is
established before you use the instruction to draw the primitive. The following
figure is an example of a red, solid line being drawn from (4,3) to (9,7). With
PM's modal interface, the only value you need to supply to GpiLine is the end
point (9,7).
Line Drawn with GpiLine
The line is drawn automatically with the current color, red, in the current
line type, solid, and starting from the current position, (4,3). There are
separate functions for specifying the current color, line type, and position.
In nonmodal graphics systems, you supply information relevant to an instruction
when you use that instruction. For example, you could use a line-drawing
instruction in which you would specify that the line is to be green, dotted,
and drawn from point a to point b. Those values or attributes are bound to a
particular drawing instruction, and affect no other. If you are going to
continue the line from point b to point c, you must again specify "green",
"dotted", "point b", and finally, "point c".
For the PM programming interface, the default values for the graphics
primitives (or current values if the defaults have been modified) are stored in
the presentation space along with the current position. While at first it might
seem like many functions are necessary to perform one step, such as drawing a
line, a modal graphics system actually saves resources. After you perform the
first line draw, chances are that if you draw a second or third line, the line
attributes are not likely to change; that is, the mode of the presentation
space remains the same. Thus, the constant repetition of attributes in a
nonmodal graphics system actually uses more resources if the desired output
requires more than one or two graphics functions.
It is possible to define graphics, and store their definitions, without sending
them to a screen or a printer. In these situations, the concept of attribute
currentness becomes relevant. The color of a line on a screen, for example, is
the color that was current when you defined the line. This is not always the
color that is current when the line is drawn.
ΓòÉΓòÉΓòÉ 11.1.4. Current Position ΓòÉΓòÉΓòÉ
The current position is the world-coordinate space position at which the next
drawing request begins. It is part of the data stored in the presentation
space. When you create or obtain a presentation space, the current position is
set to the origin (0,0). The current position also is reset to (0,0) whenever a
presentation space is associated with a different device context.
Most drawing requests update the current position. If you draw a line from the
origin to (3,5), for example, the current position is updated to (3,5). The
current position also can be updated explicitly by GpiSetCurrentPosition or
GpiMove. If you do not want the first drawing in a presentation space to start
at (0,0), call GpiSetCurrentPosition first.
ΓòÉΓòÉΓòÉ 11.1.5. Primitive Attributes ΓòÉΓòÉΓòÉ
The graphics primitives and the functions that draw them are discussed in Line
and Arc Primitives through Fonts. The primitive's function allows the
attributes of the primitive to be set for all subsequent use of that primitive.
The attributes are stored in data structures called bundles. There are
functions that allow you to set the attributes of the primitives before the
drawing of any primitive is performed. GpiSetAttrs allows you to not only
specify the primitive for which the attributes are going to be set, but also,
the settings for the specific attributes. GpiQueryAttrs returns the current
values of specified attributes for specified primitives.
Two other functions, GpiSetAttrMode and GpiQueryAttrMode, enable you to define
or query the attribute mode settings, AM_PRESERVE and AM_NOPRESERVE. The
AM_PRESERVE setting preserves the value of an attribute any time that attribute
is changed. The previous value can be recovered easily if, for example, you
need six dotted lines, one solid line, then six more dotted lines. The
AM_NOPRESERVE setting discards the previous value of an attribute once the
value is changed. The values of the attributes are presentation space
resources.
ΓòÉΓòÉΓòÉ 11.2. Using Presentation Spaces ΓòÉΓòÉΓòÉ
You can use presentation-space functions to:
Create a normal, micro, or cached micro presentation space
Delete, save, or restore a presentation space
Define or determine the presentation space attributes
ΓòÉΓòÉΓòÉ 11.2.1. Obtaining and Creating a Presentation Space ΓòÉΓòÉΓòÉ
Normal presentation spaces and micro presentation spaces are created using
GpiCreatePS. Cached micro presentation spaces are created using WinBeginPaint
or WinGetPS.
ΓòÉΓòÉΓòÉ 11.2.2. Deleting a Presentation Space ΓòÉΓòÉΓòÉ
A presentation space consumes a considerable amount of memory, so you should
delete it when your application no longer requires it. Use GpiDestroyPS to
delete either a normal or micro presentation space.
When you finish using a cached micro presentation space that you accessed with
WinGetPS, release it with WinReleasePS. You need not delete a presentation
space that you accessed with WinBeginPaint. PM does this for you when you call
WinEndPaint.
ΓòÉΓòÉΓòÉ 11.2.3. Saving and Restoring a Presentation Space ΓòÉΓòÉΓòÉ
You can save certain attributes and resources of a presentation space, modify
its fields, draw in the modified presentation space, then restore it with
GpiSavePS and GpiRestorePS. When you call GpiSavePS, the graphics engine copies
the following items from the current presentation space onto a special stack:
Primitive attributes
Transformation matrixes
Viewing limit
Clip path
Clip region
Current position
Loaded logical color table
Loaded logical font
You can push the contents of a presentation space on the stack as many times
as is necessary. GpiRestorePS pops the contents of a presentation space off
the stack.
ΓòÉΓòÉΓòÉ 11.2.4. Presentation Spaces Review ΓòÉΓòÉΓòÉ
The following table summarizes the features and restrictions of each type of
presentation space.
Presentation Space Features and Restrictions
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFeature/Restriction ΓöéNormal ΓöéStandard ΓöéCached Micro Γöé
Γöé Γöé ΓöéMicro Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevice types ΓöéAny device ΓöéAny device ΓöéVideo-display Γöé
Γöésupported Γöé Γöé Γöéwindow only Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéNumber of supported ΓöéMultiple ΓöéOne ΓöéOne Γöé
Γöédevices Γöé Γöé Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAssociation ΓöéAssociate andΓöéAssociate at ΓöéN/A. Γöé
Γöé Γöédisassociate Γöécreation; Γöé Γöé
Γöé Γöéas required. Γöécannot Γöé Γöé
Γöé Γöé Γöédisassociate.Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRetained graphics ΓöéYes ΓöéNo ΓöéNo Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAvailable GPI ΓöéAll functionsΓöéAll except ΓöéAll except Γöé
Γöéfunctions Γöé Γöésegment Γöésegment Γöé
Γöé Γöé Γöéfunctions Γöéfunctions Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMemory ΓöéHighest ΓöéMedium memoryΓöéQuickest Γöé
Γöéconsiderations Γöémemory usage Γöéusage Γöéallocation Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 11.3. About Device Contexts ΓòÉΓòÉΓòÉ
Device contexts link presentation spaces to devices by converting
device-independent presentation space information into device-dependent
information. This conversion occurs in the presentation driver, a low-level
program that is transparent to the application. A presentation driver is
device-driver code that converts the application commands into output commands
specific for each output device.
After creating a device context, it must be associated with a presentation
space before the drawing (or primitives) can be printed or displayed. When a
presentation space and a device context are associated with each other, any
output you direct to the presentation space is directed automatically at the
device context and displayed on the physical device. For example, before you
can draw a picture in a display window, the picture's graphics presentation
space must be associated with the window's device context.
Device contexts also give applications access to important device information
such as screen dimensions or printer capabilities.
As with presentation spaces, there are three types of device contexts:
Cached
Window
Normal
ΓòÉΓòÉΓòÉ 11.3.1. Cached Device Contexts ΓòÉΓòÉΓòÉ
A cached device context is one that already is associated with a cached
presentation space when that space is obtained from the cache.
ΓòÉΓòÉΓòÉ 11.3.2. Window Device Contexts ΓòÉΓòÉΓòÉ
Window device contexts are a special type, in that they are the only device
contexts obtained with WinOpenWindowDC. As their name implies, the output
device they represent is a display window. WinOpenWindowDC accepts a window
handle as input and returns the window device context handle. The window device
context handle can then be associated with a standard micro presentation space
or a normal presentation space.
The window device context is closed automatically when its associated window is
deleted.
ΓòÉΓòÉΓòÉ 11.3.3. Normal Device Contexts ΓòÉΓòÉΓòÉ
A normal device context (also called a standard or noncached device context)
links a presentation space with any nonwindow output device. Use DevOpenDC to
obtain a device context handle to one of the six normal device contexts listed
in the following table. Each of the six normal device contexts must be closed
by DevCloseDC before your application is closed.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDC Type ΓöéPurpose ΓöéUsage Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéQueued ΓöéLinks a presentationΓöéApplications use Γöé
Γöé Γöéspace with a printerΓöéqueued device Γöé
Γöé Γöéor plotter shared byΓöécontexts to offload Γöé
Γöé Γöémultiple Γöéprinting control Γöé
Γöé Γöéapplications sendingΓöéfrom the Γöé
Γöé Γöéspooled print jobs Γöéapplication. Γöé
Γöé Γöéto the print queue. Γöé Γöé
Γöé ΓöéQueued device Γöé Γöé
Γöé Γöécontexts store printΓöé Γöé
Γöé Γöéjobs by using a Γöé Γöé
Γöé Γöéprogram called printΓöé Γöé
Γöé Γöéspooler, which keepsΓöé Γöé
Γöé Γöétrack of the order Γöé Γöé
Γöé Γöéin which the jobs Γöé Γöé
Γöé Γöéarrive at the Γöé Γöé
Γöé Γöéprinter and in whichΓöé Γöé
Γöé Γöéthey are printed. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDirect ΓöéLinks a presentationΓöéApplications Γöé
Γöé Γöéspace with a printerΓöénormally do not use Γöé
Γöé Γöéor plotter, directlyΓöédirect device Γöé
Γöé Γöébypassing the Γöécontexts, unless Γöé
Γöé Γöéspooler and print Γöéthey are avoiding Γöé
Γöé Γöéqueue. A direct Γöéthe queue (for Γöé
Γöé Γöédevice context is Γöésecurity reasons) orΓöé
Γöé Γöéused by the spooler Γöégoing directly to a Γöé
Γöé Γöéto process jobs as Γöédedicated machine. Γöé
Γöé Γöéthey are removed Γöé Γöé
Γöé Γöéfrom the print Γöé Γöé
Γöé Γöéqueue. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInformation ΓöéLinks a presentationΓöéAn application can Γöé
Γöé Γöéspace with a printerΓöéuse an information Γöé
Γöé Γöéor plotter, directlyΓöédevice context with Γöé
Γöé Γöéenabling device Γöélower memory Γöé
Γöé Γöéinformation to be Γöéoverhead, rather Γöé
Γöé Γöéqueried, but Γöéthan use a direct Γöé
Γöé Γöéproducing no output Γöédevice context, Γöé
Γöé Γöéon the device. Γöéwhich could provide Γöé
Γöé Γöé Γöéthe same Γöé
Γöé Γöé Γöéinformation. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMemory ΓöéLinks a presentationΓöéApplications use Γöé
Γöé Γöéspace with a bit Γöémemory device Γöé
Γöé Γöémap. Γöécontexts for drawingΓöé
Γöé Γöé Γöéto the bit map and Γöé
Γöé Γöé Γöéusing it as a sourceΓöé
Γöé Γöé Γöéor target of BitBlt Γöé
Γöé Γöé Γöéoperations. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMetafile ΓöéA special device ΓöéOnly applications Γöé
Γöé Γöécontext that enablesΓöéthat use metafiles Γöé
Γöé Γöéa picture output to Γöéuse metafile device Γöé
Γöé Γöéits associated Γöécontexts. Γöé
Γöé Γöépresentation space Γöé Γöé
Γöé Γöéto be recorded in a Γöé Γöé
Γöé Γöémetafile for Γöé Γöé
Γöé Γöéinterchange for Γöé Γöé
Γöé Γöéfuture use. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMetafile_NoQuery ΓöéFunctionally ΓöéIf attributes of theΓöé
Γöé Γöéidentical to Γöépresentation space Γöé
Γöé Γöémetafile; however, Γöéare not to be Γöé
Γöé Γöéquerying of Γöéqueried, this deviceΓöé
Γöé Γöépresentation space Γöécontext offers Γöé
Γöé Γöéattributes is not Γöéimproved performanceΓöé
Γöé Γöéallowed. Γöéover metafile. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 11.4. Using Device Contexts ΓòÉΓòÉΓòÉ
In addition to associating or disassociating presentation spaces with device
contexts, you can use device context functions to:
Obtain or create a device context
Associate a device context with a presentation space
Close a device context
Retrieve information about a device's capabilities
ΓòÉΓòÉΓòÉ 11.4.1. Creating a Device Context ΓòÉΓòÉΓòÉ
You can create a normal device context by calling DevOpenDC. This function
requires that you specify one of the six normal types. It also requires that
you pass certain device-initialization data, including a logical address, the
device-driver name, device-driver data, a description of the device type, and
information about the queue (if the device is a queued device). The
device-initialization data is passed in a DEVOPENSTRUC structure.
The following figure is an example of this structure.
typedef struct _DEVOPENSTRUC { /* dop */
PSZ pszLogAddress /* Logical-device address */
PSZ pszDriverName /* Device-driver name */
PDRIVDATA pdriv /* Pointer to extra driver data */
PSZ pszDataType /* Type of queued data */
PSZ pszComment /* Optional spooler info */
PSZ pszQueueProcName /* Queue-processor name */
PSZ pszQueueProcParams /* Queue-processor arguments */
PSZ pszSpoolerParams /* Spooler arguments */
PSZ pszNetworkParams /* Network arguments */
} DEVOPENSTRUC;
The last four fields in this structure apply only to queued devices.
The following figure shows how to create a nondisplay device context for a
printer.
HDC hdcPrinter; /* Handle of printer device context */
HAB hab; /* Anchor-block handle */
DEVOPENSTRUC dop; /* Device information */
dop.pszLogAddress = "lpt1"; /* Logical-device address */
dop.pszDriverName = "EPSON"; /* Device-driver name */
dop.pdriv = (PDRIVDATA) NULL; /* Pointer to driver data */
dop.pszDataType = "PM_Q_STD"; /* Standard queued data */
hdcPrinter = DevOpenDC(hab,
OD_DIRECT, /* Direct device type */
"*", /* No data in OS2.INI */
4, /* Use first 4 fields in dop structure */
(PDEVOPENDATA) &dop,
(HDC) NULL);
The following figure is an example of how to create a standard device context
for a metafile.
HDC hdcMeta; /* Handles of metafile */
/* and window DCs */
HAB hab; /* Anchor-block handle */
DEVOPENSTRUC dop; /* Device information */
dop.pszLogAddress = NULL; /* Logical-device address */
dop.pszDriverName = "DISPLAY"; /* Device-driver name */
hdcMeta = DevOpenDC(hab,
OD_METAFILE, /* Metafile DC */
"*", /* No data in OS2.INI */
2, /* Use first 2 fields in dop */
(PDEVOPENDATA) &dop, /* Structure for system info */
NULL) /* Compatible with screen */
ΓòÉΓòÉΓòÉ 11.4.2. Associating Presentation Spaces with Device Contexts ΓòÉΓòÉΓòÉ
Drawing graphic objects requires a presentation space and a device context to
direct output to a specific instance of an output device, such as a display
window or a printer. This association enables the device context to identify
the output device for that presentation space. Further, the device context
identifies the particular instance of the output device, such as a printer or
display window.
A presentation space can be associated with only one device context at a time.
The reverse is also true: a device context can be associated with only one
presentation space at a time.
The following figure shows how a presentation space is associated with a window
device context. It is then disassociated from the window device context and
associated with a printer device context. It cannot be associated with both
device contexts simultaneously.
WM_Create:
hdcScreen = WinOpenWindowsDC (hwnd);
phs = GpiCreatePS (...GPIA.Assoc);
.
.
.
WM_COMMAND:
Case IDM_File PRINT: /* Device selection */
hdcPrinter = DevOpenDC (...);
GpiAssociate (hps, NULL); /* Disconnect from screen */
GpiAssociate (hps, hdcPrinter); /* Connect to printer */
.
. /* Output */
.
GpiAssociate (hps, NULL); /* Disconnect from print */
GpiAssociate (hps, hdcScreen); /* Reconnect to screen */
.
.
.
WM_PAINT:
WinBeginPaint (hwnd, hps, NULL);
.
. /* Output */
.
The following figure shows how to open a window device context and associate it
with a normal presentation space.
HDC hdcWin; /* Window device-context handle */
HPS hpsWin; /* Normal-presentation-space handle */
HWND hwndClient; /* Client-window handle */
HAB hab; /* Anchor-block handle */
SIZEL sizlPage; /* Presentation page */
hdcWin = WinOpenWindowDC(hwndClient);
hpsWin = GpiCreatePS(hab, hdcWin, &sizlPage,
PU_LOENGLISH | GPIA_ASSOC);
Note: This type of code is used when the device context is defined before the
presentation space.
WinOpenWindowDC can be called only once for a particular window and returns an
error if called a second time. WinQueryWindowDC can be used to obtain a window
device context previously allocated using WinOpenWindowDC. The following figure
shows how to create a presentation space with page units of 0.01 inch
(PU_LOENGLISH) and associate it with a printer device context. As input to
GpiCreatePS, you supply the height and width of the presentation page.
HAB hab; /* Anchor-block handle */
HPS hpsPrinter; /* Presentation-space handle */
HDC hdcPrinter; /* Device-context handle */
SIZEL sizlPage; /* Page structure */
.
.
.
hpsPrinter = GpiCreatePS(hab, hdcPrinter, &sizlPage,
PU_LOENGLISH | GPIA_ASSOC);
ΓòÉΓòÉΓòÉ 11.4.3. Closing a Device Context ΓòÉΓòÉΓòÉ
To close a device context that your application opened with DevOpenDC, call
DevCloseDC. However, you should not try to close a device context that you
opened with WinOpenWindowDC. The operating system does this automatically when
the associated window is deleted.
ΓòÉΓòÉΓòÉ 11.4.4. Determining Device Capabilities ΓòÉΓòÉΓòÉ
Once you have created a device context for a particular output device, you can
determine the capabilities of that device by calling DevQueryCaps. This
function retrieves the following information:
Device technology (whether the device is a raster or vector device)
Maximized window dimensions (if the device is a video display)
Page dimensions (if the device is a printer or plotter)
Character-box dimensions
Marker-box dimensions
Pel resolution
Color capabilities
Mix-mode capabilities
You can use this information, for example, to select fonts, set up the
presentation page, or create a new logical color table.
ΓòÉΓòÉΓòÉ 12. Paths ΓòÉΓòÉΓòÉ
A path is a graphics object composed of one or more figures drawn with graphic
primitives. A path can be used for defining a filled area, a complex clipping
shape, an outline, and for drawing geometric wide lines.
The following topics are related to information in this chapter:
Presentation spaces and device contexts
Line and arc primitives
Area primitives
Color and mix attributes
Regions
Clipping
ΓòÉΓòÉΓòÉ 12.1. About Paths ΓòÉΓòÉΓòÉ
Paths provide several useful drawing techniques including:
An alternate means of generating filled or outlined irregular figures and
nonrectangular shapes
An efficient means of producing hollow text in an outline font
The only means of clipping (restricting the area of interest of a
picture) to circular, elliptical, or other nonrectangular figures
The only means of drawing lines with a thickness that can be transformed
These techniques are respectively illustrated in the following figures:
Drawing Techniques Achieved with Paths
A path is similar to an area, but there are fundamental differences between
the two. The following table describes their similarities and contrasts.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéPaths ΓöéAreas Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFunctions that define a path ΓöéFunctions that define an area Γöé
Γöéare bracketed by GpiBeginPath Γöéare bracketed by GpiBeginArea Γöé
Γöéand GpiEndPath. Γöéand GpiEndArea. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPaths are defined in world ΓöéAreas are defined in world Γöé
Γöécoordinates. Γöécoordinates. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPaths can be modified before ΓöéAreas are displayed Γöé
Γöébeing displayed or used for Γöéimmediately on completion. Γöé
Γöéclipping. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPaths can be used by ΓöéAreas cannot be used as Γöé
Γöéapplications to perform Γöéclipping regions. Γöé
Γöéclipping. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPaths can be converted into ΓöéAreas cannot be converted intoΓöé
Γöégraphics objects called Γöéregions. Γöé
Γöéregions. Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSix operations can be ΓöéOnly two operations can be Γöé
Γöéperformed on paths, each Γöéperformed on areas (specified Γöé
Γöérequiring a separate function:Γöéwith options when creating theΓöé
Γöé Γöéarea): Γöé
ΓöéOutline Γöé Γöé
ΓöéFill ΓöéOutline Γöé
ΓöéModify ΓöéFill Γöé
ΓöéStroke Γöé Γöé
ΓöéConvert to clip path Γöé Γöé
ΓöéConvert to region Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 12.1.1. Path Attributes ΓòÉΓòÉΓòÉ
Paths do not have a separate ...BUNDLE data structure associated with them.
Their attributes are defined by LINEBUNDLE and AREABUNDLE. There are certain
line attributes that apply only to geometric lines, or lines created with some
path operations. Depending on the purpose of a path, only certain path
attributes are in effect. These and the other path attributes are described in
this chapter.
When an application creates a presentation space, the path attributes are set
to the default values shown in the following table.
Path Attribute Default Values
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute ΓöéDefault Value ΓöéFunction that Redefines Γöé
Γöé Γöé ΓöéAttribute Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGeometric width ΓöéNone ΓöéGpiSetLineWidthGeom Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEnd ΓöéLINEEND_FLAT ΓöéGpiSetLineEnd Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéJoin ΓöéLINEJOIN_BEVEL ΓöéGpiSetLineJoin Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWidth Γöé1.0 ΓöéGpiSetLineWidth Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéType ΓöéLINETYPE_SOLID ΓöéGpiSetLineType Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéColor ΓöéCLR_NEUTRAL ΓöéGpiSetAttrs (LBB_COLOR) Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMix mode ΓöéFM_OVERPAINT ΓöéGpiSetAttrs (LBB_MIX_MODE) Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern symbol ΓöéSolid ΓöéGpiSetPattern Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern set ΓöéLCID_DEFAULT ΓöéGpiSetPatternSet Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéReference point Γöé(0,0) ΓöéGpiSetPatternRefPoint Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground colorΓöéCLR_NEUTRAL ΓöéGpiSetAttrs (ABB_COLOR) Γöé
Γöé Γöé(black on most Γöé Γöé
Γöé Γöédevices) Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground colorΓöéCLR_BACKGROUND ΓöéGpiSetAttrs (ABB_BACK_COLOR)Γöé
Γöé Γöé(white on most Γöé Γöé
Γöé Γöédevices) Γöé Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground mix ΓöéFM_OVERPAINT ΓöéGpiSetAttrs (ABB_MIX_MODE) Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground mix ΓöéBM_LEAVEALONE ΓöéGpiSetAttrs Γöé
Γöé Γöé Γöé(ABB_BACK_MIX_MODE) Γöé
Γöé Γöé ΓöéGeometric width, End, and Γöé
Γöé Γöé ΓöéJoin take effect only when aΓöé
Γöé Γöé Γöépath is converted to a Γöé
Γöé Γöé Γöégeometric wide line using Γöé
Γöé Γöé ΓöéGpiStrokePath or Γöé
Γöé Γöé ΓöéGpiModifyPath. Γöé
Γöé Γöé ΓöéWidth, Type, Color, and Mix Γöé
Γöé Γöé Γöémode take effect only when aΓöé
Γöé Γöé Γöépath is outlined using Γöé
Γöé Γöé ΓöéGpiOutlinePath. Γöé
Γöé Γöé ΓöéPattern symbol, Pattern set,Γöé
Γöé Γöé Γöéand Reference point take Γöé
Γöé Γöé Γöéeffect only when a path is Γöé
Γöé Γöé Γöéfilled using GpiFillPath or Γöé
Γöé Γöé ΓöéGpiStrokePath. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 12.1.2. Line Width and Geometric Width for Paths ΓòÉΓòÉΓòÉ
Cosmetic lines represent the mathematical ideal of a one-dimensional line. The
width attribute associated with them is provided only for ease of drawing these
lines larger than one pel.
In contrast, geometric line width is not an attribute; it is a geometric
property. To set the width of a geometric line, an application can use
GpiSetLineWidthGeom. This geometric width takes effect only when a path is
converted to a geometric wide line using GpiStrokePath or GpiModifyPath.
If a geometric line is drawn before the geometric width is specified, the drawn
line is defined by the cosmetic line width-usually 1-which results in the
thinnest possible line for the currently associated device. A geometric line
width has no default in the same way that the sides of a box, drawn with
GpiBox, have no length until specified by the function.
The value specified with GpiSetLineWidthGeom is the thickness of the line in
world coordinates, and it is subject to scaling by the current transformations
in effect at the time GpiModifyPath or GpiStrokePath is called. For example, if
you apply a transform with a scaling factor of 0.5, for an object whose current
geometric line width is four world coordinates, the width of the displayed line
will be halved.
In the floor plan shown in the following figure, the outer walls were drawn
using geometric lines. All of the other objects were drawn using normal lines.
Geometric Lines and Normal Lines
Your application can determine the current geometric width by calling
GpiQueryLineWidthGeom.
ΓòÉΓòÉΓòÉ 12.1.3. Line End ΓòÉΓòÉΓòÉ
The line end attribute specifies the shape of the unattached end of a geometric
line. Lines whose shapes are partially defined by a geometric width have to be
closed, unlike cosmetic lines that simply end. An application can draw
geometric lines with square, flat, or round ends.
Note: The end attribute takes effect only when a path is converted to a
geometric width line using GpiStrokePath or GpiModifyPath.
Set the current geometric line end attribute with GpiSetLineEnd. The attribute
applies to all subsequent unattached lines within the path bracket. The
following table describes the three standard line ends provided by the PM
programming interface; you cannot define your own end types.
Standard Geometric Line End Types
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéType ΓöéIdentifier ΓöéLong Value Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFlat, flush with line end ΓöéLINEEND_FLAT Γöé1L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRound, past line end ΓöéLINEEND_ROUND Γöé2L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFlat, but extends past line end ΓöéLINEEND_SQUARE Γöé3L Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The default line end type (LINEEND_DEFAULT) is identical to the LINEEND_FLAT
type, and has a long value of 0L. The error linetype (LINEEND_ERROR) has a long
value of -1L.
The following figure illustrates these three types of line ends. Your
application can determine the current geometric line end by calling
GpiQueryLineEnd.
Closing Unattached Geometric Lines
A square line end extends the line by a distance that is half the width of the
line. For example, if the line is six coordinate units wide, a square line end
extends it by three coordinate units.
A round line end is constructed by drawing a circle whose radius is half the
width of the line.
ΓòÉΓòÉΓòÉ 12.1.4. Line Join ΓòÉΓòÉΓòÉ
The line join attribute specifies the shape formed by two intersecting
geometric lines. Where one wide line joins another, the nature of the join must
be defined. An application can select a beveled, rounded, or mitred line-join
style.
Note: The join attribute takes effect only when a path is converted to a
geometric wide line using GpiStrokePath or GpiModifyPath.
Set the current geometric line-join attribute with GpiSetLineJoin. The
attribute applies to all subsequent intersection of lines within the path
bracket. The following table describes the three standard line joins provided
by the PM programming interface. You cannot define your own join types.
Standard Geometric Line Join Types
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéType ΓöéIdentifier ΓöéLong Value Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDiagonal corner ΓöéLINEJOIN_BEVEL Γöé1L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRounded corner ΓöéLINEJOIN_ROUND Γöé2L Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé90┬░ angled corner ΓöéLINEJOIN_MITRE Γöé3L Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The default join type (LINEJOIN_DEFAULT) is identical to the LINEJOIN_BEVEL
type, and has a long value of 0L. The error linetype (LINEJOIN_ERROR) has a
long value of -1L. The following figure illustrates these three types of line
joins.
Your application can determine the current geometric line join using
GpiQueryLineJoin.
Joining Wide Lines
ΓòÉΓòÉΓòÉ 12.1.5. Cosmetic Line Attributes for Paths ΓòÉΓòÉΓòÉ
When a path is drawn as a cosmetic line with GpiOutlinePath, the following
attributes are defined by the LINEBUNDLE data structure:
Line width
Line type
Line color
Line mix
These attributes follow the current definitions and appear just as line
primitives do. Since the line primitive has only a foreground color and mix
attribute, the current color of the drawing surface affects the appearance of
these paths more than it does the appearance of paths that define geometric
lines. Those paths follow the area attributes and are affected by background
color and background mix attributes as well.
ΓòÉΓòÉΓòÉ 12.1.6. Area Attributes for Paths ΓòÉΓòÉΓòÉ
When a path is drawn as a geometric line with GpiStrokePath or GpiModifyPath,
the following attributes are defined by the AREABUNDLE data structure:
Pattern symbol
Pattern set
Pattern reference point
Area foreground color
Area background color
Area foreground mix
Area background mix
Area attributes follow the current definitions and appear just as area
primitives do. The operating system uses the pattern symbol to fill the
interior of the path that defines the geometric line. Any alterations to the
fill pattern or reference point affect the appearance of a geometric line just
as it does an area.
ΓòÉΓòÉΓòÉ 12.1.7. Path Color and Mix Attributes ΓòÉΓòÉΓòÉ
The color attribute defines the color used to draw a primitive or an object.
The mix attribute determines how the color of a primitive or an object is
combined with the color of the drawing surface, or any other objects on the
surface. Unlike the color and mix attributes for primitives, and certain other
objects, the path color is defined by different attributes in different
situations, as illustrated in the following figure.
Path Objects
Path colors are determined by the area color, area background color, area mix,
and area background mix attributes if the path is stroked into a wide line. The
cosmetic line path color is determined by the line color and mix attributes.
The line color defines the color used to draw the output from any of the IBM
OS/2 line functions called within the path. The line colors can change within
the path bracket, just as they can within area brackets. The interaction of the
line with the drawing-surface color is controlled by the line mix attribute,
which also can vary within the path bracket.
After the path is closed, the path can be stroked into a geometric (or wide)
line. Depending on the construction options, the geometric line can be filled.
The appearance of the pattern symbol used to fill the path depends on the area
attributes. The definitions of the area color and background color depend on
the pattern symbol.
ΓòÉΓòÉΓòÉ 12.1.8. Path Brackets ΓòÉΓòÉΓòÉ
The functions that create and define the path always are bracketed by the
GpiBeginPath and GpiEndPath functions. Only one path can be defined between
these two functions. However, within the path, there can be any number of
figures.
GpiBeginPath signals the start of a path definition. Each path you define
becomes the current path and replaces any existing path in the presentation
space. The current position is not changed by GpiBeginPath, although it is
updated by any drawing instructions that follow.
GpiBeginPath accepts as input only a path identifier of 1. This identifier is
used by the functions performing path operations to identify the path.
Due to the number of different operations that can be performed on paths, the
path definition can contain both open and closed figures. If a figure does not
start and end at the same coordinate point, it is classified as an open figure.
Unlike an area bracket, if you use GpiSetCurrentPosition or GpiMove within a
path definition, the current figure is not automatically closed.
The PM provides a method of closing figures within a path. GpiCloseFigure
(valid only in path brackets) closes a figure in the path whose start and end
points are not the same, by drawing a straight line from the current position
to the start position of the figure. Use GpiCloseFigure if you want the line
join attribute to be applied between the start and end point of a figure. Do
not use it if you want the line end attributes to be used as the start and end
points for a geometric wide line.
If the path definition contains full arc or box primitives, however, you must
not close them using GpiCloseFigure. GpiBox and GpiFullArc generate completely
closed figures and must not be used within another figure definition.
To signal the end of the current path definition, use GpiEndPath. The path
definition is constructed in the currently associated presentation space. The
current position always is updated to the end point of the last line drawn.
The functions that generate a path are enclosed in a path bracket. Applications
can use the functions in the following list within a path bracket.
GpiBeginElement
GpiBox
GpiCallSegmentMatrix
GpiCharString
GpiCharStringAt
GpiCharStringPos
GpiCharStringPosAt
GpiCloseFigure
GpiComment
GpiCreateLogFont
GpiDeleteSetId
GpiElement
GpiEndElement
GpiEndPath
GpiFullArc
GpiGetData
GpiLabel
GpiLine
GpiMarker
GpiMove
GpiOffsetElementPointer
GpiPartialArc
GpiPointArc
GpiPolyFillet
GpiPolyFilletSharp
GpiPolyLine
GpiPolyMarker
GpiPolySpline
GpiPop
GpiPutData
GpiQueryArcParams
GpiQueryAttrMode
GpiQueryCurrentPosition
GpiSetArcParams
GpiSetAttrMode
GpiSetAttrs
GpiSetCharAngle
GpiSetCharBox
GpiSetCharDirection
GpiSetCharMode
GpiSetCharSet
GpiSetCharShear
GpiSetColor
GpiSetCp
GpiSetCurrentPosition
GpiSetEditMode
GpiSetLineEnd
GpiSetLineJoin
GpiSetLineType
GpiSetLineWidth
GpiSetMarker
GpiSetMarkerBox
GpiSetMarkerSet
GpiSetMix
GpiSetModelTransformMatrix
Warning. Some GPI functions cannot be used while an open path definition
exists. In particular, you cannot include image or area primitives in a path
definition.
ΓòÉΓòÉΓòÉ 12.1.9. Path Operations ΓòÉΓòÉΓòÉ
The operations performed on a path determine which of the path attributes
become applicable. Unlike specifying area brackets, the variety of operations
also calls for separate functions instead of specifying options with
GpiBeginPath. Specifically, the following six operations can be performed on a
path:
Outline
Fill
Modify
Stroke
Convert to clip path
Convert to region
There are other graphics operations provided by the PM -for example,
transformations- that can apply to entities other than paths.
Upon completion, GpiFillPath, GpiOutlinePath, GpiStrokePath, and
GpiPathToRegion delete the current path definition. This path is not available
for any subsequent operations.
GpiModifyPath does not delete the current path definition. An application can
modify a path before using one of the aforementioned functions.
The first time your application calls GpiSetClipPath, the current path
definition is converted into the current clip path. GpiSetClipPath deletes the
path definition upon completion but not the clip path definition.
A path definition can be stored in a graphics segment and, if that segment is
retained, the path can be re-created as required. Segments are discussed in
Creating and Drawing Retained Graphics.
ΓòÉΓòÉΓòÉ 12.1.10. Path Outline ΓòÉΓòÉΓòÉ
To draw the outline of the current path, use GpiOutlinePath. This function
accepts a path identifier (which must be 1) as input. GpiOutlinePath does not
create a geometric line; therefore, the cosmetic line attributes are used.
GpiOutlinePath normally has the same effect as though the lines and arcs used
to create the path were drawn without actually being part of the path. Any open
figures within the path are not closed automatically. If the path contains
character strings that use an outline font, the characters are not filled.
The following functional sequence is recommended for drawing outline text or
outline figures:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name ΓöéEffect Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBeginPath ΓöéStarts the path definition. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiMove ΓöéMoves to the starting point ofΓöé
Γöé Γöéthe first figure. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharString, GpiFullArc ΓöéUses an outline font to Γöé
Γöé Γöéspecify text or define the Γöé
Γöé Γöélines in a figure. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiEndPath ΓöéEnds the path. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiOutlinePath ΓöéDraws the text or figure Γöé
Γöé Γöéoutlines. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
If you are drawing a complex path, consisting of several character strings that
use an outline font, it can take quite some time to produce. If you want to
create a only rough draft, you might find it quicker to draw an outline instead
of the filled path. This improves performance and might be acceptable for small
characters. When they are small enough, hollow characters can look like filled
characters.
You can create hollow characters in either of two ways:
Outside a path, call GpiCreateLogFont.
This enables you to define an outline font that uses hollow characters.
Inside a path, draw the characters, then display the path with
GpiOutlinePath.
Only the character outlines contribute to the path definition even if the
font is not hollow. (This might cause ambiguous results.)
Using outlined paths to create character outlines also can be used to define a
clip path in the shape of a letter or word.
ΓòÉΓòÉΓòÉ 12.1.11. Path Fill ΓòÉΓòÉΓòÉ
To draw the current path and fill its interior using the current pattern
symbol, use GpiFillPath. The path is deleted after the interior is filled. The
boundary lines are considered part of the path interior and are drawn with this
function. Any open figures in the path definition are closed automatically by
GpiFillPath.
This function accepts the path identifier (which must be 1) as input, and
either of two construction options:
FPATH_ALTERNATE (the default)
FPATH_WINDING (must be selected if the path has been modified).
Paths, like area primitives, can be filled in alternate mode or winding mode.
If the path consists of multiple, intersecting figures, the path-fill mode
affects the final appearance of the path.
The following figure shows two identical paths that were filled, each using
one of the two modes. Each path consists of a triangle drawn within a
rectangle. The path on the left was filled using the alternate mode. The path
on the right was filled using the winding mode.
Alternate and Winding Fill Modes
ΓòÉΓòÉΓòÉ 12.1.11.1. Paths in Alternate Mode ΓòÉΓòÉΓòÉ
For paths drawn in alternate mode (as with area primitives), the following is
true:
If you have to cross an odd number of boundaries in the path when drawing
an imaginary line parallel to the x-axis, a point is included in the
filled path from that point to positive infinity.
If you have to cross an even number of boundaries in the path when
drawing an imaginary line parallel to the x-axis, a point is not included
in the filled path from that point to positive infinity.
The following figure shows how the operating system determines the filled
portion for the path shown in the previous figure. The path outside the
triangle, but inside the rectangle, is filled, because the imaginary lines
drawn from those points in the positive x-direction intersect the path
boundaries an odd number of times.
Calculating Filled Paths Constructed in Alternate Mode
Parts of the path with odd tallys are filled; parts with even tallys are not
filled.
ΓòÉΓòÉΓòÉ 12.1.11.2. Paths in Winding Mode ΓòÉΓòÉΓòÉ
For paths drawn in winding mode (also like area primitives), the direction the
boundaries in the path are drawn in determines whether a given point is
included in the filled path. The drawn direction of a boundary line depends on
both the graphics functions used to draw it and the world coordinates that
define it.
For box primitives, for example, if the specified diagonal corner is to the
right, to the top, or both, of the current position, the box is drawn
counterclockwise. If the specified diagonal corner is to the left, to the
bottom, but not both, the box is drawn clockwise.
For a polyline primitive, the direction of the boundary depends on the relative
values of the start and end points of each line. For a polygon primitive, the
direction of the boundary depends on the relative values of the specified
vertices.
To determine whether a given point is included in the filled path, count the
number of boundary lines to be crossed to move from that point to infinity. For
each boundary line drawn in one direction add one to the tally. For each
boundary line drawn in the opposite direction, subtract one from the tally. A
point is within the area if the result is nonzero. As with the alternate mode,
the imaginary determining line is drawn in the positive x-direction from the
point in question toward infinity.
The following figure shows how the operating system determines the filled
portion for the path shown in the figure before the previous one. Assume that
both the rectangle and triangle were drawn in the same direction, whether
clockwise or counterclockwise is immaterial. Both figures are filled, because
the number of times the imaginary lines drawn from those points in the positive
x-direction intersect the path boundaries is continuously summed. There is
never a subtraction of a boundary tally to reduce the total to 0.
Paths Constructed in the Same Direction in Winding Mode
Parts of the path with nonzero tallys are filled; parts with zero tallys are
not filled.
If two figures, for example in the following figure, are drawn in different
directions, the tally for the inner triangle is 0 and the area looks exactly as
it does in alternate mode.
Paths Constructed in Different Directions in Winding Mode
Parts of the path with nonzero tallys are filled; parts with zero tallys are
not filled.
ΓòÉΓòÉΓòÉ 12.1.12. Path Modification ΓòÉΓòÉΓòÉ
To convert the current path to one that describes the envelope of a geometric
wide line, use GpiModifyPath. The current geometric line attributes are then
applied to the figures within the path. The line end, line join, and geometric
line width attributes all must be set before modify-path or stroke-path
operations begin, because it is during those times that the attributes are
applied. Cosmetic line attributes of width and type have no effect on geometric
lines.
GpiModifyPath accepts the path identifier (which must be 1) and the
modification option MPATH_STROKE as input.
Subsequently, the modified path can be filled to display the geometric wide
line, but only in winding mode. Alternatively, the modified path can be
converted into a clip path, but again, only in winding mode.
Open figures within the path are not closed automatically. Figures not
explicitly closed with GpiCloseFigure are drawn with line ends rather than line
joins at their start and end points. If the figures within the path overlap,
the geometric width envelope compensates so that the overlap portion is not
drawn blank in XOR or exclusive-OR mode.
Now the geometric lines can be scaled.
Note: The current transforms are applied to the primitives inside a path
bracket when the path is defined. This binds the path definition in device
coordinates at that time. The path is unaffected by subsequent transformations,
except for those (such as scaling) that affect the width of geometric (wide)
lines. Since the geometric line width attribute is not applied until the path
is converted into a wide line by GpiModifyPath or GpiStrokePath, the width of
geometric lines is unaffected by earlier transformations directed at the path
definition.
After creating a path bracket, geometric wide lines can be constructed by
either:
Stroking the path (GpiStrokePath),
Modifying the path (GpiModifyPath), then filling the path (GpiFillPath).
GpiStrokePath is slightly more efficient, but GpiModifyPath and GpiFillPath
offer more flexibility (by way of the fill options). After drawing the lines
no alterations can be made.
ΓòÉΓòÉΓòÉ 12.1.13. Path-Stroking ΓòÉΓòÉΓòÉ
To modify and fill the current path in a single operation, use GpiStrokePath.
Then the path is drawn immediately to the output device, with the current
geometric line attributes applied to the figures within the path. Certain
device drivers can use this function to optimize storage.
GpiStrokePath automatically fills the path in winding mode with the current
area pattern symbol. When GpiStrokePath is complete, the path definition is
deleted from the device context.
GpiStrokePath is subject to the same constraints as functions that perform
simple line modification:
The line end, line join, and geometric line width attributes all must be
set before stroke operations.
Cosmetic line attributes of width and type have no effect.
Any open figures within the path are not closed automatically.
If figures are not explicitly closed with GpiCloseFigure, they are drawn
with line ends rather than line joins at their start and end points.
If the figures within the path overlap, the geometric width envelope
compensates so that the overlap portion is not drawn blank when drawn in
XOR (exclusive-OR) mode.
This function accepts as input both the path identifier (which must be 1) and
the stroke option (which must be 0L).
When the operating system strokes a path, it draws a geometric line of
specified width along the original figure that defined the path and then fills
the wide line. If the original figure is not a closed shape, the operating
system does not automatically close it before filling the path. The following
figure shows the effects of GpiStrokePath on a box originally defined with
normal (cosmetic) lines.
Defining Lines with a Geometric Width
The broken line is the figure defined within the path. The solid lines show
the path after it has been converted. Each line has a geometric width of n
coordinate units, and the line joins have been defined as beveled.
After setting these attributes, the application can draw the line with
GpiStrokePath. After the lines are drawn, an application can scale stroked
paths with a scaling transformation.
As an alternative to the GpiStrokePath, you can convert the path using
GpiModifyPath, which does not draw the path on the current output device. To
draw a modified path, use GpiFillPath, which draws the path and fills it with
the current area-fill pattern in winding mode. A modified path cannot be
filled in alternate mode.
On some devices, it might be that the GpiStrokePath method works better than
GpiModifyPath, followed by GpiFillPath.
ΓòÉΓòÉΓòÉ 12.1.14. Path Conversion to Clip Path ΓòÉΓòÉΓòÉ
Clipping is the process an application uses to limit graphics output to a
specific area (called the clipping area) of the display or page.
There are several clipping functions provided by the PM. However, if your
application requires an irregular complex shape for a clipping area, it must
define the shape with a path. To convert the path into a clipping boundary, use
GpiSetClipPath. The clip path, as defined by this operation, becomes the
current clip path for all subsequent drawing.
This function accepts a path identifier and one of two construction options as
input:
SCP_ALTERNATE (default)
SCP_WINDING (must be selected if the path has been modified)
Unlike the path operations described previously, GpiSetClipPath accepts two
different path identifiers:
1
0 (default).
The default path identifier of 0 (SCP_RESET) resets the clip path to infinity,
which displays the picture without clipping. If this value is selected, the
current clip path definition is discarded instead of stored.
For GpiSetClipPath, a path identifier of 1 (SCP_AND) causes the clip path to
be redefined as the mathematical intersection of the stored clip path and the
current path definition. For all other path operations, an identifier of 1
specifies the current path as the recipient of the operation. The only method
of specifying the clip path as the current path, after GpiSetClipPath has been
called, is to call GpiSetClipPath again: the first call with a path identifier
of 0; the second, with a path identifier of 1. The path identifiers and the
construction mode can be ORed together for certain effects.
Any open figures within a path are closed automatically. The boundaries of the
path are considered part of the interior, so any point on the boundary is not
clipped. The following figure shows the result of clipping text with a
triangular clip path. Triangular Clip Path
ΓòÉΓòÉΓòÉ 12.1.15. Path Conversion to Region ΓòÉΓòÉΓòÉ
To convert the current path to a region, use GpiPathToRegion. Then the new
region can be modified using any of the region functions that allow the
creation of irregular shaped regions.
Any open figures in the path definition are closed automatically by
GpiPathToRegion. Upon conversion, the current path definition is discarded just
like it is when being converted to a clip path. When GpiPathToRegion is
complete, the path definition is deleted automatically.
This function accepts the path identifier (which must be 1) and one of two
construction options as input:
FPATH_ALTERNATE (default)
FPATH_WINDING (must be selected if the path has been modified)
ΓòÉΓòÉΓòÉ 12.2. Using Paths ΓòÉΓòÉΓòÉ
You can use path functions to:
Draw geometric lines and filled polygons
Draw outline text
Create a triangular clip path
ΓòÉΓòÉΓòÉ 12.2.1. Drawing a Geometric (Wide) Line ΓòÉΓòÉΓòÉ
The following figure is an example of how to draw a straight line, 10 units
wide with rounded ends.
#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncPATH01(void){
POINTL ptl;
HPS hps;
GpiSetLineWidthGeom(hps, 10L); /* Sets line width to ten */
GpiSetLineEnd(hps, LINEEND_ROUND); /* Sets line end to round */
GpiBeginPath(hps, 1L); /* Begins path */
ptl.x = 7;
ptl.y = 15;
GpiMove(hps, &ptl); /* Sets current position */
ptl.x = 450;
ptl.y = 15;
GpiLine(hps, &ptl); /* Draws line */
GpiEndPath(hps); /* Ends path */
GpiStrokePath(hps, 1L, 0L); /* Draws geometric line */
} /* fncPATH01 */
ΓòÉΓòÉΓòÉ 12.2.2. Drawing Filled Polygons ΓòÉΓòÉΓòÉ
The following figure is an example of how to draw an empty triangle within a
solid rectangle.
#define INCL_GPIPATHS
#include <os2.h>
void fncPATH02(void){
HPS hps;
POINTL aptl1[4] = { /* Array of points for triangle */
50, 50,
100, 100,
150, 50,
50, 50 };
POINTL aptl2[5] = { /* Array of points for rectangle */
25, 25,
25, 200,
200, 200,
200, 25,
25, 25 };
GpiBeginPath(hps, 1L); /* Begins path */
GpiMove(hps, aptl1); /* Sets current position */
GpiPolyLine(hps, 4L, aptl1); /* Plots points for triangle */
GpiMove(hps, aptl2); /* Sets current position */
GpiPolyLine(hps, 5L, aptl2); /* Plots points for rectangle */
GpiEndPath(hps); /* Ends path */
GpiFillPath(hps, 1L, FPATH_ALTERNATE); /* Draws triangle and rectangle */
} /* fncPATH02 */
ΓòÉΓòÉΓòÉ 12.2.3. Drawing Outline Text ΓòÉΓòÉΓòÉ
The following figure shows an example of how to draw text from an outline font
with GpiOutlinePath.
#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncPATH03(void){
LONG lcid = 1; /* Identifier for font */
FATTRS fattrs; /* Structure for font attributes */
SIZEF sizfx; /* Structure for character box */
POINTL ptl; /* Structure for starting point */
HPS hpsWin;
fattrs.usRecordLength = sizeof(FATTRS);
fattrs.fsSelection = FATTR_SEL_OUTLINE; /* Specifies outline font */
fattrs.lMatch = 0; /* System determines font */
fattrs.szFacename[0] = 0;
fattrs.idRegistry = 0;
fattrs.usCodePage = 0;
fattrs.lMaxBaselineExt = 0;
fattrs.lAveCharWidth = 0;
fattrs.fsType = 0;
fattrs.fsFontUse = FATTR_FONTUSE_OUTLINE; /* Specifies outline font */
GpiCreateLogFont(hpsWin,(PSTR8) NULL, lcid, &fattrs);
GpiSetCharSet(hpsWin, lcid); /* Sets logical font */
sizfx.cx = MAKEFIXED(30, 0); /* Width of character box */
sizfx.cy = MAKEFIXED(30, 0); /* Height of character box */
GpiSetCharBox(hpsWin, &sizfx) /* Sets size of character box */
GpiBeginPath(hpsWin, 1L); /* Begins path */
ptl.x = 100;
ptl.y = 200;
GpiMove(hpsWin, &ptl); /* Sets current position */
GpiCharString(hpsWin, 7L, "Outline"); /* Establishes char. string */
GpiEndPath(hpsWin); /* Ends path */
GpiOutlinePath(hpsWin, 1L, 0L); /* Draws character string */
} /* fncPATH03 */
ΓòÉΓòÉΓòÉ 12.2.4. Creating a Triangular Clip Path ΓòÉΓòÉΓòÉ
The following figure shows an example of how to create a triangular clip path
and then write text into it.
#define INCL_GPIPATHS
#include <os2.h>
void fncPATH04(void){
POINTL ptlStart;
HPS hps;
LONG i;
POINTL aptl[4] = { /* Array of points for triangle */
35, 45,
100, 100,
200, 45,
35, 45 };
GpiBeginPath(hps, 1L); /* Begins path bracket */
GpiMove(hps, aptl); /* Sets current position */
GpiPolyLine(hps, 4L, aptl); /* Plots points for triangle */
GpiEndPath(hps) /* Ends path bracket */
GpiSetClipPath(hps, 1L, SCP_ALTERNATE | SCP_AND);
/* Write a block of text. */
ptlStart.x = 50;
for (i = 50L; i < 110L; i += 10L) {
ptlStart.y = i;
GpiCharStringAt(hps, &ptlStart, 18L, "String of text!");
} /* for */
} /* fncPATH04 */
ΓòÉΓòÉΓòÉ 13. Regions ΓòÉΓòÉΓòÉ
A region is a graphics object usually composed of one or more rectangles.
Converted to clip regions, they are used mainly to define a clipping boundary,
in device coordinates, for multiple intersecting rectangles. Clip regions
provide the required clipping in an update region during WM_PAINT processing
when it is necessary to repaint part of a window. Regions also can be used for
area fill.
The following topics are related to the information in this chapter:
Presentation spaces and device contexts
Area primitives
Color and mix modes
Coordinate spaces and transformations
Clipping
ΓòÉΓòÉΓòÉ 13.1. About Regions ΓòÉΓòÉΓòÉ
A region consists of one or more overlapping or separate rectangles in an
application's device space. The sides of the rectangles are parallel to the x-
and y-axes in the device coordinate space. An irregular, nonrectangular path
can be converted into a region. However, unless otherwise specified, the
assumption of this chapter is that a region is rectangular.
If a region consists of intersecting rectangles, the intersecting sides are
always perpendicular. If the rectangles have no common elements, the region is
defined as separate rectangles.
Unlike areas and paths, which are defined in world coordinates, regions are
device-dependent and, so, are defined in device coordinates. The device
coordinates are inclusive (inside the rectangle) at the bottom and left
coordinate boundaries, and exclusive (outside the rectangle and clipped) at the
top and right boundaries.
Each region is created for the device that currently is associated with a
presentation space. Also, after creation, regions are available for various
operations; a region handle identifies the region for subsequent operations.
The following figure shows a region that consists of two intersecting
rectangles. An application defined the region by passing an array containing
the coordinates for the two rectangles to GpiCreateRegion. The application then
drew the region with GpiPaintRegion.
Defining a Region
This region comprises two overlapping rectangles.
ΓòÉΓòÉΓòÉ 13.1.1. System Implementation ΓòÉΓòÉΓòÉ
Regions are device-dependent objects and, therefore, are associated with a
particular device. For this reason, when an application specifies a
presentation space as input to one of the region functions, that presentation
space must be associated with a device context. The associated device context
serves to identify the device. Because a region is specific to the device for
which it was created, a region should not be created for one device and then
used for another.
If the device is a printer, a metafile can be used to store region functions as
escapes, and the resulting metafile can be displayed on any device. The
appearance of the result of any region function is affected by differences in
the pel:aspect ratio and device resolution on different printers.
Most of the region-oriented functions use the RECTL structure to define the
device-space coordinates of the rectangle. When an application creates a
rectangle in a device space and passes its coordinates to a region function,
the operating system excludes the top and rightmost edges of the rectangle.
This means that an application must add 1 to the values in the xRight and yTop
fields of the RECTL structure to obtain the desired dimensions. For example, if
an application requires a region that measures 100-by-100 device units, with a
lower-left corner at (10,10), xRight and yTop should be set to 111 instead of
110.
ΓòÉΓòÉΓòÉ 13.1.2. Region Attributes ΓòÉΓòÉΓòÉ
Regions do not have a distinct ...BUNDLE data structure associated with them.
Unlike primitives or even paths, the purpose of regions is to provide a
definition for an operation-not visual output. However, there are two functions
that present the region as a visible entity.
GpiPaintRegion paints a region in the presentation space. This function accepts
only the region handle as input. GpiPaintRegion does not cause graphics orders
to be added to the current segment. (Graphics orders are the smallest, most
complete portions of a segment.) Therefore, in retain or draw-and-retain modes,
you are advised to use paths or areas rather than regions to ensure the desired
effect.
GpiFrameRegion draws a frame around a region by tracing the inner perimeter
with a rectangle of a specified size. This function accepts the region handle
and the desired frame thickness as input.
A region's visible output is controlled by the following AREABUNDLE attributes:
Pattern symbol
Pattern set
Pattern reference point
Area foreground color
Area background color
Area foreground mix
These attributes follow the current definitions and appear just as area
primitives do. The operating system uses the pattern symbol to fill the
interior of the region. Any alterations to the fill pattern or reference point
affects the appearance of a region, just as it does in an area.
Because neither the painted region nor the region frame have boundary lines,
no LINEBUNDLE attributes influence the appearance of a region resulting from
GpiPaintRegion or GpiFrameRegion.
ΓòÉΓòÉΓòÉ 13.1.3. Region Creation ΓòÉΓòÉΓòÉ
Areas and paths are created and defined within a bracket. Regions are defined
by a single function, GpiCreateRegion. As input to GpiCreateRegion, supply the
total number of, and the coordinates for, each rectangle that contributes to
the region. The following applies to region coordinates:
They define the bottom left and top right coordinates of each rectangle
that makes up the region.
They must be in the range -32768 through +32767.
They always are device coordinates, because regions always are created
and drawn in an application's device space.
The output from GpiCreateRegion is the region handle, which identifies the
region for subsequent operations. Because each region can be distinctly
identified, the region functions allow applications to work with more than one
region at a time.
For example, an application can combine two regions with GpiCombineRegion or
compare two regions with GpiEqualRegion. GpiQueryRegionRects retrieves the
coordinates of the rectangles that make up a region, enabling an application
to create a copy of that region. To create the copy, you supply, as input to a
new GpiCreateRegion, the exact rectangles returned from GpiQueryRegionRects.
ΓòÉΓòÉΓòÉ 13.1.4. Region Operations ΓòÉΓòÉΓòÉ
The following operations can be performed on a region:
Creating Regions
Drawing Regions
Moving Regions
Determining Region Characteristics
Converting a Path to a Region
Converting a Region to a Clip Region
Deleting Regions
ΓòÉΓòÉΓòÉ 13.1.4.1. Creating Regions ΓòÉΓòÉΓòÉ
To create a rectangular region, call GpiCreateRegion. This function accepts, as
input, the number of rectangles to be ORed into a single region and the
coordinates of those rectangles. If the number of rectangles is 0, an empty
region is created.
To create a new region from regions that already exist, call GpiCombineRegion.
This function accepts, as input, a region handle for the target region, a
region handle for each of the two source regions, and an options flag that
specifies the way the two source regions are combined.
Note: The destination region can be either of the two source regions, in which
case, that region is replaced by the new region.
The rectangles are differentiated by one region's being distinctly "the first
source rectangle" and the other region labeled "the second source rectangle".
The order of the source rectangles affects the way GpiCombineRegion combines
them. You can use GpiCombineRegion an indefinite number of times to form
complex polygons. However, the function is limited to combining only two
regions each time it is called. The two source regions must be created for the
same type of device.
Following are the five ways in which two regions can be combined:
Option Result
CRGN_OR Union of the two source regions
CRGN_XOR Symmetric difference of the two source regions
CRGN_COPY Source region 1 only; source region 2 is ignored
CRGN_AND Intersection of the two source regions
CRGN_DIFF Source region 1 minus source region 2
The effects of these different combining operations on overlapping regions are
shown in The effects of these different combining operations on overlapping
regions are shown in the following figure. Their effects on separate regions
are shown in Their effects on separate regions are shown in the figure after
the following figure.
Combining Overlapping Regions
The source regions are two overlapping rectangles. The regions that result
from the various combine operations are shown as shaded areas.
Output from GpiCombineRegion tells you whether the resulting region is a NULL
region, rectangular region, or complex region. A complex region is any region
defined by two or more rectangles.
To change the definition of a region while keeping the same region handle,
call GpiSetRegion. This function accepts, as input, the number and dimensions
of the rectangles that now define the region, just as GpiCreateRegion does.
However, GpiSetRegion also accepts the handle of the region to be updated.
GpiSetRegion, like GpiCreateRegion, takes a region definition to be the union
of a sequence of rectangles (that are effectively ORed together). In the case
of GpiCreateRegion, a new region is created and its handle returned. In the
case of GpiSetRegion, the previous definition is discarded and replaced by the
new definition that is associated with the existing region handle.
Combining Disjoint Regions
The two source regions do not overlap. The regions that result from the
various combine operations are shown as shaded areas. The result from a
CRGN_AND combining of separate regions is a NULL region.
ΓòÉΓòÉΓòÉ 13.1.4.2. Moving a Region ΓòÉΓòÉΓòÉ
To move a region, call GpiOffsetRegion. This function accepts, as input, the
region handle and an offset value that is added to every coordinate point of
the region.
GpiOffsetRegion moves a region by a specific number of device coordinates. By
specifying positive or negative x- and y-values an application can move a
region in any direction, relative to its current position.
ΓòÉΓòÉΓòÉ 13.1.4.3. Determining Region Characteristics ΓòÉΓòÉΓòÉ
Regions are used in many operations. There are several functions that determine
the characteristics of regions because these characteristics influence the
outcome of the operation being performed.
To determine whether two regions are identical, call GpiEqualRegion. This
function accepts, as input, the two region handles. Regions are identical if
the only difference between them is an empty region. For example, a rectangular
region whose lower-left corner is at 10,10 is not identical to a region whose
lower-left corner is at 50,50, even if the regions have exactly the same
dimensions. The two regions also must be of the same device class to be
considered identical.
To determine the rectangles that compose a region, call GpiQueryRegionRects,
which retrieves the coordinates of a series of rectangles that, when ORed
together, define the shape of the regions.
Note: The individual regions returned may differ in size and number from those
originally used to specify the region.
GpiQueryRegionRects accepts, as input, the region handle and the maximum
number of rectangles that can be returned. The division of the region into
multiple rectangles is handled automatically by the PM.
It is not necessary for an application to retrieve all the rectangles in a
single function. Your application can call GpiQueryRegionRects any number of
times. Therefore, the application must specify the maximum number of
rectangles and the rectangle number to start from in each function.
No assumptions can be made about the number and coordinates of rectangles
returned except that they will define the specified region precisely. The
purpose of specifying the number of rectangles in the query is to ensure that
the system does not return more coordinates than can fit in the RECTL array.
To determine whether a point is inside the borders of a region, call
GpiPtInRegion. This function is especially useful in applications that must
determine whether the mouse pointer is over a region. The particular point
must be expressed in device coordinates.
To determine whether any part of a specified rectangle lies within a region,
call GpiRectInRegion. This function accepts, as input, the region handle and
the rectangle as specified in device coordinates.
To determine the coordinates of the smallest rectangle that encloses a region,
call GpiQueryRegionBox. This function accepts the region handle as input. The
output from this function tells you whether the bounding region is
rectangular, NULL, or complex.
ΓòÉΓòÉΓòÉ 13.1.4.4. Converting a Region to a Clip Region ΓòÉΓòÉΓòÉ
Clipping is the process an application uses to limit graphics output to a
specific area (called the clipping area) of the display or page.
There are several clipping functions provided by the PM. However, if your
application requires a clipping boundary in device coordinates, it must define
the boundary with a region. To convert the region into a clipping boundary,
call GpiSetClipRegion. The clip region, as defined by this operation, becomes
the current clip region of all subsequent drawing operations.
GpiSetClipRegion accepts, as input, the region handle. A NULL region handle
sets the clip region to infinity, effectively performing no clipping.
Unlike clip paths, the region that is no longer the current clip region is not
deleted. It retains the effects of any changes made to it while it was a clip
region, and it can be used with the other region functions, including being
reselected as the clip region with GpiSetClipRegion.
You do not have to deselect the current clip region before selecting another.
Each selected clip region automatically replaces the one before it. If there is
an existing clip region when you call GpiSetClipRegion, it reverts to a normal
region, and its handle is returned.
When you have selected the current clip region, none of the region functions
described thus far can be used for that region. The following functions can be
used with the current clip region:
GpiQueryClipBox
GpiIntersectClipRectangle
GpiExcludeClipRectangle
GpiOffsetClipRegion
GpiPtVisible
GpiRectVisible
These functions are described in Clipping and Boundary Determination. All of
these functions work in world coordinates, rather than device coordinates, and
therefore, are subject to current transformations.
GpiPtVisible and GpiRectVisible do not apply exclusively to clip regions.
When the screen contents are altered (for example, when a window is sized),
you have to be able to repair the part of the screen image affected by the
change. The following figure illustrates the necessary region.
Repairing the Screen with Clip Regions
To improve performance of the drawing operation, you can restrict the
redrawing and repair work to the affected parts of the screen.
Use WinQueryUpdateRegion to determine whether graphics objects are totally
outside the update region and need not be drawn at all. Graphics objects that
are within, or are partly outside, the update region should be drawn, and the
system will perform the required clipping automatically.
Define a clipping region using the dimensions of the update region. Then call
an appropriate GPI drawing request, such as GpiDrawChain, to redraw the screen
contents. Any drawing that would occur outside the clip region is discarded
according to the standard clipping rules. Only those graphics within the clip
region are redrawn.
ΓòÉΓòÉΓòÉ 13.1.4.5. Deleting a Region ΓòÉΓòÉΓòÉ
To delete a region, call GpiDestroyRegion. This function accepts, as input, the
region handle. If the region is the current clip region, it cannot be deleted.
To delete a current clip region, first call GpiSetClipRegion and specify a NULL
region handle. The region is no longer the current clip region and can be
deleted.
ΓòÉΓòÉΓòÉ 13.2. Using Regions ΓòÉΓòÉΓòÉ
You can use the region functions to:
Create or delete a region
Combine regions
Compare regions
Move a region
Paint and frame a region
Locate a point with respect to a region
Determine the coordinates of region rectangles
ΓòÉΓòÉΓòÉ 13.2.1. Creating and Deleting a Region ΓòÉΓòÉΓòÉ
To create a region:
1. Create an array of RECTL structures containing the dimensions of the
rectangles that will compose the region.
2. Call GpiCreateRegion to create the region. (This function returns a
handle that identifies the region.)
To delete a region, pass the handle returned by the GpiCreateRegion function
to GpiDestroyRegion.
The following figure shows how to create and delete a region.
#include <os2.h>
void fncREGN01(void){
HPS hps; /* Presentation-space handle */
HRGN hrgn; /* Region handle */
RECTL arcl[] = {
25, 50, /* Rectangle 1 */
75, 100,
50, 75, /* Rectangle 2 */
100, 150,
75, 125, /* Rectangle 3 */
200, 175,
150, 75, /* Rectangle 4 */
250, 150 };
hrgn = GpiCreateRegion(hps, /* Creates region */
sizeof(arcl) / sizeof (RECTL), /* Number of rectangles in region */
arcl); /* Array of rectangle structures */
.
. /* Work with the region here. */
.
GpiDestroyRegion(hps, hrgn); /* Destroys region identified by hrgn */
} /* fncREGN01 */
ΓòÉΓòÉΓòÉ 13.2.2. Combining Regions ΓòÉΓòÉΓòÉ
To combine two regions:
1. Create a region that the operating system can use as the destination
region when it combines the source regions.
2. Determine which of the five combining methods to use.
3. Call GpiCombineRegion.
The following figure shows how to combine two regions by using the OR
operation:
#define INCL_GPIREGIONS
#include <os2.h>
void fncREGN02(void){
HPS hps;
HRGN hrgn1, hrgn2, hrgn3; /* Region handles */
RECTL rcl1, rcl2;
rcl1.xLeft = 50; rcl1.yBottom = 100;
rcl1.xRight = 200; rcl1.yTop = 175;
hrgn1 = GpiCreateRegion(hps, 1L, &rcl1); /* First source region */
rcl2.xLeft = 125; rcl2.yBottom = 150;
rcl2.xRight = 225; rcl2.yTop = 200;
hrgn2 = GpiCreateRegion(hps, 1L, &rcl2); /* Second source region */
hrgn3 = GpiCreateRegion(hps, 0L, (PRECTL) NULL); /* Destination region */
/* Combine the regions. */
GpiCombineRegion(hps, hrgn3, hrgn1, hrgn2, CRGN_OR);
} /* fncREGN02 */
ΓòÉΓòÉΓòÉ 13.2.3. Comparing Regions ΓòÉΓòÉΓòÉ
GpiEqualRegion determines whether two regions are identical. The following
figure shows how to compare regions.
#define INCL_GPIREGIONS
#include <os2.h>
void fncREGN03(void){
HPS hps; /* Presentation-space handle */
HRGN hrgn1, hrgn2; /* Region handles */
LONG lEqual; /* Return value for GpiEqualRegion */
RECTL rcl1, rcl2; /* Structures for region coordinates */
rcl1.xLeft = 50; rcl1.yBottom = 100;
rcl1.xRight = 200; rcl1.yTop = 175;
hrgn1 = GpiCreateRegion(hps, 1, &rcl1); /* Creates first region */
rcl2.xLeft = 125; rcl2.yBottom = 150;
rcl2.xRight = 225; rcl2.yTop = 200;
hrgn2 = GpiCreateRegion(hps, 1, &rcl2); /* Creates second region */
lEqual = GpiEqualRegion(hps, hrgn1, hrgn2); /* Compares regions */
if (lEqual == EQRGN_EQUAL)
{
.
. /* Regions are equal. */
.
}
else if (lEqual == EQRGN_NOTEQUAL)
{
.
. /* Regions are not equal. */
.
}
else if (lEqual == EQRGN_ERROR)
{
.
. /* An error occurred. */
.
}
} /* fncREGN03 */
ΓòÉΓòÉΓòÉ 13.2.4. Offsetting a Region ΓòÉΓòÉΓòÉ
GpiOffsetRegion moves a region, by a specified offset, from its current
position (in world space). This function must be called with the address of a
POINTL structure that contains an x and a y translation factor. The following
figure shows how to offset a region.
} /* fncREGN04 */
POINTL ptlNewPos; /* Structure for offset value */
ptlNewPos.x = 200; /* Sets x offset */
ptlNewPos.y = 10; /* Sets y offset */
GpiOffsetRegion(hps, hrgn, &ptlNewPos); /* Offsets region */
ΓòÉΓòÉΓòÉ 13.2.5. Painting a Region ΓòÉΓòÉΓòÉ
GpiPaintRegion fills a region with the current fill pattern, using the colors
and mix mode that appear in the current AREABUNDLE structure. GpiFrameRegion
draws a frame around a region by tracing the perimeter of the region with a
rectangle of a specified size. The following figure shows how to change the
fill-pattern color to green, paint a region, and draw a frame around the
region.
SIZEL sizl; /* Structure for size of frame */
HPS hps; /* Presentation-space handle */
HRGN hrgn; /* Region handle */
GpiSetColor(hps, CLR_DARKPINK);
GpiPaintRegion(hps, hrgn); /* Paint region dark pink */
GpiSetColor(hps, CLR_BLACK);
sizl.cx = 5;
sizl.cy = 5;
GpiFrameRegion(hps, hrgn, &sizl); /* 5-by-5 black frame */
ΓòÉΓòÉΓòÉ 13.2.6. Locating a Point with Respect to a Region ΓòÉΓòÉΓòÉ
To determine whether the mouse pointer lies within a region:
1. Retrieve the mouse-pointer coordinates and store them in a POINTL
structure.
2. Call GpiPtInRegion, passing it a handle that identifies the appropriate
region and the address of the POINTL structure from Step 1.
3. Examine the value that GpiPtInRegion returns to determine whether the
point lies within the region.
The following figure shows how to locate the mouse pointer with respect to a
region.
#define INCL_GPIREGIONS
#include <os2.h>
void fncREGN04(void){
POINTL ptlCurPos; /* Mouse coordinates */
HPS hps; /* Presentation-space handle */
HRGN hrgn; /* Region handle */
LONG lPosition; /* Return value for GpiPtInRegion */
/* Determine mouse coordinates and store in ptlCurPos. */
lPosition = GpiPtInRegion(hps, hrgn, &ptlCurPos);
if (lPosition == PRGN_INSIDE) {
.
. /* Point lies within region. */
.
} /* if */
else if (lPosition == PRGN_OUTSIDE) {
.
. /* Point lies outside region. */
.
} /* else-if */
ΓòÉΓòÉΓòÉ 13.2.7. Determining Coordinates of Rectangles in a Region ΓòÉΓòÉΓòÉ
If a region consists of more than one rectangle, you can call
GpiQueryRegionRects to retrieve the coordinates of the lower-left and
upper-right corners of each rectangle.
If you use GpiQueryRegionRects to retrieve every rectangle requested to define
a region, the function retrieves the coordinates of as many contiguous
rectangles as required. GpiQueryRegionRects returns the coordinates of the
rectangles that define a region to an array of RECTL structures, and returns
the number of rectangles that were requested for the definition to the
crcReturned field of the RGNRECT structure. Your RECTL array may not be large
enough to hold all of the rectangles. Specify the maximum it can accept and
request the remainder in subsequent functions if necessary.
To determine the coordinates of the rectangles that form a region, follow these
steps:
1. Create an array of RECTL structures that will receive the rectangle
coordinates. More rectangles may be required to define the region than
were required to create it.
2. Fill in the ircStart, crc, and usDirection fields of the RGNRECT
structure. The crc field can specify more rectangles than will be
returned by GpiQueryRegionRects.
3. Call GpiQueryRegionRects to retrieve the coordinates.
The following figure shows how to determine the number of rectangles that
define a region, the coordinates of the rectangles in that region, and how to
create a new region using those coordinates.
#define INCL_GPIREGIONS
#include <os2.h>
void fncREGN05(void){
RGNRECT rgnrc; /* Structure for region rectangles */
RECTL arcl1[5]; /* Array for determining rectangle count */
PRECTL parcl; /* Array for rectangle coordinates */
ULONG cRects = 0; /* Total number of rectangles in region */
HPS hps;
HRGN hrgn3;
rgnrc.ircStart = 1; /* Rectangle to start with */
rgnrc.crc = 5; /* Number of rectangles to query */
rgnrc.ulDirection = RECTDIR_LFRT_BOTTOP; /* Direction to query */
/**********************************************************************/
/* Determine the total number of rectangles in the region by */
/* repeatedly calling GpiQueryRegionRects with an array of 5 RECTL */
/* structures. The loop terminates when the function retrieves less */
/* than 5 rectangles. */
/**********************************************************************/
do {
GpiQueryRegionRects(hps, /* Handle of presentation space */
hrgn3, /* Region to query */
(PRECTL) NULL, /* Gets all rectangles in region */
&rgnrc, /* Structure with rectangle data */
arcl1); /* Array of structures for coordinates */
cRects += rgnrc.crcReturned;
} while (rgnrc.crcReturned == rgnrc.crc); /* While 5 rects retrieved */
//cRects = rgnrc.crcReturned + (rgnrc.ircStart - 1);
rgnrc.ircStart = 0; /* Rectangle to start with */
rgnrc.crc = cRects; /* Number of rectangles to query */
/* Allocate enough memory for all RECTL structures. */
parcl = (PRECTL) malloc(cRects * sizeof(RECTL));
/* Fill array with coordinates of all rectangles. */
GpiQueryRegionRects(hps, /* Handle of presentation space */
hrgn3, /* Region to query */
(PRECTL) NULL, /* Gets all rectangles in region */
&rgnrc, /* Structure with rectangle data */
parcl); /* Array of structures for coordinates */
} /* fncREGN05 */
ΓòÉΓòÉΓòÉ 14. Glossary ΓòÉΓòÉΓòÉ
This glossary defines many of the terms used in this book. It includes terms
and definitions from the IBM Dictionary of Computing, as well as terms specific
to the OS/2 operating system and the Presentation Manager. It is not a complete
glossary for the entire OS/2 operating system; nor is it a complete dictionary
of computer terms.
Other primary sources for these definitions are:
The American National Standard Dictionary for Information Systems, ANSI
X3.172-1990, copyrighted 1990 by the American National Standards
Institute, 11 West 42nd Street, New York, New York 10036. These
definitions are identified by the symbol (A) after the definition.
The Information Technology Vocabulary, developed by Subcommittee 1, Joint
Technical Committee 1, of the International Organization for
Standardization and the International Electrotechnical Commission
(ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are
identified by the symbol (I) after the definition; definitions taken from
draft international standards, committee drafts, and working papers being
developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the
definition, indicating that final agreement has not yet been reached
among the participating National Bodies of SC1.
ΓòÉΓòÉΓòÉ 14.1. Glossary Listing ΓòÉΓòÉΓòÉ
Select a starting letter of glossary terms:
A N
B O
C P
D Q
E R
F S
G T
H U
I V
J W
K X
L Y
M Z
ΓòÉΓòÉΓòÉ <hidden> Glossary - A ΓòÉΓòÉΓòÉ
accelerator -In SAA Common User Access architecture, a key or combination of
keys that invokes an application-defined function.
accelerator table -A table used to define which key strokes are treated as
accelerators and the commands they are translated into.
access mode -The manner in which an application gains access to a file it has
opened. Examples of access modes are read-only, write-only, and read/write.
access permission -All access rights that a user has regarding an object. (I)
action -One of a set of defined tasks that a computer performs. Users request
the application to perform an action in several ways, such as typing a
command, pressing a function key, or selecting the action name from an
action bar or menu.
action bar -In SAA Common User Access architecture, the area at the top of a
window that contains choices that give a user access to actions available in
that window.
action point -The current position on the screen at which the pointer is
pointing. Contrast with hot spot and input focus.
active program -A program currently running on the computer. An active
program can be interactive (running and receiving input from the user) or
noninteractive (running but not receiving input from the user). See also
interactive program and noninteractive program.
active window -The window with which the user is currently interacting.
address space -(1) The range of addresses available to a program. (A) (2)
The area of virtual storage available for a particular job.
alphanumeric video output -Output to the logical video buffer when the video
adapter is in text mode and the logical video buffer is addressed by an
application as a rectangular array of character cells.
American National Standard Code for Information Interchange -The standard
code, using a coded character set consisting of 7-bit coded characters (8
bits including parity check), that is used for information interchange among
data processing systems, data communication systems, and associated
equipment. The ASCII set consists of control characters and graphic
characters. (A)
Note: IBM has defined an extension to ASCII code (characters 128-255).
anchor -A window procedure that handles Presentation Manager message
conversions between an icon procedure and an application.
anchor block -An area of Presentation-Manager-internal resources to allocated
process or thread that calls WinInitialize.
anchor point -A point in a window used by a program designer or by a window
manager to position a subsequently appearing window.
ANSI -American National Standards Institute.
APA -All points addressable.
API -Application programming interface.
application -A collection of software components used to perform specific
types of work on a computer; for example, a payroll application, an airline
reservation application, a network application.
application object -In SAA Advanced Common User Access architecture, a form
that an application provides for a user; for example, a spreadsheet form.
Contrast with user object.
application programming interface (API) -A functional interface supplied by
the operating system or by a separately orderable licensed program that
allows an application program written in a high-level language to use
specific data or functions of the operating system or the licensed program.
application-modal -Pertaining to a message box or dialog box for which
processing must be completed before further interaction with any other
window owned by the same application may take place.
area -In computer graphics, a filled shape such as a solid rectangle.
ASCII -American National Standard Code for Information Interchange.
ASCIIZ -A string of ASCII characters that is terminated with a byte
containing the value 0.
aspect ratio -In computer graphics, the width-to-height ratio of an area,
symbol, or shape.
asynchronous (ASYNC) -(1) Pertaining to two or more processes that do not
depend upon the occurrence of specific events such as common timing
signals. (T) (2) Without regular time relationship; unexpected or
unpredictable with respect to the execution of program instructions. See
also synchronous.
atom -A constant that represents a string. As soon as a string has been
defined as an atom, the atom can be used in place of the string to save
space. Strings are associated with their respective atoms in an atom table.
See also integer atom.
atom table -A table used to relate atoms with the strings that they
represent. Also in the table is the mechanism by which the presence of a
string can be checked.
atomic operation -An operation that completes its work on an object before
another operation can be performed on the same object.
attribute -A characteristic or property that can be controlled, usually to
obtain a required appearance; for example, the color of a line. See also
graphics attributes and segment attributes.
automatic link -In Information Presentation Facility (IPF), a link that
begins a chain reaction at the primary window. When the user selects the
primary window, an automatic link is activated to display secondary windows.
AVIO -Advanced Video Input/Output.
ΓòÉΓòÉΓòÉ <hidden> Glossary - B ΓòÉΓòÉΓòÉ
Bezier curve -(1) A mathematical technique of specifying smooth continous
lines and surfaces, which require a starting point and a finishing point
with several intermediate points that influence or control the path of the
linking curve. Named after Dr. P. Bezier. (2) (D of C) In the AIX Graphics
Library, a cubic spline approximation to a set of four control points that
passes through the first and fourth control points and that has a continuous
slope where two spline segments meet. Named after Dr. P. Bezier.
background -(1) In multiprogramming, the conditions under which low-priority
programs are executed. Contrast with foreground. (2) An active session that
is not currently displayed on the screen.
background color -The color in which the background of a graphic primitive is
drawn.
background mix -An attribute that determines how the background of a graphic
primitive is combined with the existing color of the graphics presentation
space. Contrast with mix.
background program -In multiprogramming, a program that executes with a low
priority. Contrast with foreground program.
bit map -A representation in memory of the data displayed on an APA device,
usually the screen.
block -(1) A string of data elements recorded or transmitted as a unit. The
elements may be characters, words, or logical records. (T) (2) To record
data in a block. (3) A collection of contiguous records recorded as a unit.
Blocks are separated by interblock gaps and each block may contain one or
more records. (A)
block device -A storage device that performs I/O operations on blocks of data
called sectors. Data on block devices can be randomly accessed. Block
devices are designated by a drive letter (for example, C:).
blocking mode -A condition set by an application that determines when its
threads might block. For example, an application might set the Pipemode
parameter for the DosCreateNPipe function so that its threads perform I/O
operations to the named pipe block when no data is available.
border -A visual indication (for example, a separator line or a background
color) of the boundaries of a window.
boundary determination -An operation used to compute the size of the smallest
rectangle that encloses a graphics object on the screen.
breakpoint -(1) A point in a computer program where execution may be halted.
A breakpoint is usually at the beginning of an instruction where halts,
caused by external intervention, are convenient for resuming
execution. (T) (2) A place in a program, specified by a command or a
condition, where the system halts execution and gives control to the
workstation user or to a specified program.
broken pipe -When all of the handles that access one end of a pipe have been
closed.
bucket -One or more fields in which the result of an operation is kept.
buffer -(1) A portion of storage used to hold input or output data
temporarily. (2) To allocate and schedule the use of buffers. (A)
button -A mechanism used to request or initiate an action. See also barrel
buttons, bezel buttons, mouse button, push button, and radio button.
byte pipe -Pipes that handle data as byte streams. All unnamed pipes are byte
pipes. Named pipes can be byte pipes or message pipes. See byte stream.
byte stream -Data that consists of an unbroken stream of bytes.
ΓòÉΓòÉΓòÉ <hidden> Glossary - C ΓòÉΓòÉΓòÉ
cache -A high-speed buffer storage that contains frequently accessed
instructions and data; it is used to reduce access time.
cached micro presentation space -A presentation space from a
Presentation-Manager-owned store of micro presentation spaces. It can be
used for drawing to a window only, and must be returned to the store when
the task is complete.
CAD -Computer-Aided Design.
call -(1) The action of bringing a computer program, a routine, or a
subroutine into effect, usually by specifying the entry conditions and
jumping to an entry point. (I) (A) (2) To transfer control to a procedure,
program, routine, or subroutine.
calling sequence -A sequence of instructions together with any associated
data necessary to execute a call. (T)
Cancel -An action that removes the current window or menu without processing
it, and returns the previous window.
cascaded menu -In the OS/2 operating system, a menu that appears when the
arrow to the right of a cascading choice is selected. It contains a set of
choices that are related to the cascading choice. Cascaded menus are used to
reduce the length of a menu. See also cascading choice.
cascading choice -In SAA Common User Access architecture, a choice in a menu
that, when selected, produces a cascaded menu containing other choices. An
arrow (->) appears to the right of the cascading choice.
CASE statement -In PM programming, provides the body of a window procedure.
There is usually one CASE statement for each message type supported by an
application.
CGA -Color graphics adapter.
chained list -A list in which the data elements may be dispersed but in which
each data element contains information for locating the
next. (T)Synonymous with linked list.
character -A letter, digit, or other symbol.
character box -In computer graphics, the boundary that defines, in world
coordinates, the horizontal and vertical space occupied by a single
character from a character set. See also character mode. Contrast with
character cell.
character cell -The physical, rectangular space in which any single character
is displayed on a screen or printer device. Position is addressed by row and
column coordinates. Contrast with character box.
character code -The means of addressing a character in a character set,
sometimes called code point.
character device -A device that performs I/O operations on one character at a
time. Because character devices view data as a stream of bytes,
character-device data cannot be randomly accessed. Character devices include
the keyboard, mouse, and printer, and are referred to by name.
character mode -A mode that, in conjunction with the font type, determines
the extent to which graphics characters are affected by the character box,
shear, and angle attributes.
character set -(1) An ordered set of unique representations called
characters; for example, the 26 letters of English alphabet, Boolean 0 and
1, the set of symbols in the Morse code, and the 128 ASCII
characters. (A) (2) All the valid characters for a programming language or
for a computer system. (3) A group of characters used for a specific reason;
for example, the set of characters a printer can print.
check box -In SAA Advanced Common User Access architecture, a square box with
associated text that represents a choice. When a user selects a choice, an X
appears in the check box to indicate that the choice is in effect. The user
can clear the check box by selecting the choice again. Contrast with radio
button.
check mark - (1) (D of C) In SAA Advanced Common User Access architecture, a
symbol that shows that a choice is currently in effect. (2) The symbol that
is used to indicate a selected item on a pull-down menu.
child process -In the OS/2 operating system, a process started by another
process, which is called the parent process. Contrast with parent process.
child window -A window that appears within the border of its parent window
(either a primary window or another child window). When the parent window is
resized, moved, or destroyed, the child window also is resized, moved, or
destroyed; however, the child window can be moved or resized independently
from the parent window, within the boundaries of the parent window. Contrast
with parent window.
choice -(1) An option that can be selected. The choice can be presented as
text, as a symbol (number or letter), or as an icon (a pictorial symbol).
(2) (D of C) In SAA Common User Access architecture, an item that a user can
select.
chord -(1) To press more than one button on a pointing device while the
pointer is within the limits that the user has specified for the operating
environment. (2) (D of C) In graphics, a short line segment whose end points
lie on a circle. Chords are a means for producing a circular image from
straight lines. The higher the number of chords per circle, the smoother the
circular image.
class -In object-oriented design or programming, a group of objects that
share a common definition and that therefore share common properties,
operations, and behavior. Members of the group are called instances of the
class.
class method -In System Object Model, an action that can be performed on a
class object. Synonymous with factory method.
class object -In System Object Model, the run-time implementation of a class.
class style -The set of properties that apply to every window in a window
class.
client -(1) A functional unit that receives shared services from a
server. (T) (2) A user, as in a client process that uses a named pipe or
queue that is created and owned by a server process.
client area -The part of the window, inside the border, that is below the
menu bar. It is the user's work space, where a user types information and
selects choices from selection fields. In primary windows, it is where an
application programmer presents the objects that a user works on.
client program -An application that creates and manipulates instances of
classes.
client window -The window in which the application displays output and
receives input. This window is located inside the frame window, under the
window title bar and any menu bar, and within any scroll bars.
clip limits -The area of the paper that can be reached by a printer or
plotter.
clipboard -In SAA Common User Access architecture, an area of computer
memory, or storage, that temporarily holds data. Data in the clipboard is
available to other applications.
clipping -In computer graphics, removing those parts of a display image that
lie outside a given boundary. (I) (A)
clipping area -The area in which the window can paint.
clipping path -A clipping boundary in world-coordinate space.
clock tick -The minimum unit of time that the system tracks. If the system
timer currently counts at a rate of X Hz, the system tracks the time every
1/X of a second. Also known as time tick.
CLOCK$ -Character-device name reserved for the system clock.
code page -An assignment of graphic characters and control-function meanings
to all code points.
code point -(1) Synonym for character code. (2) (D of C) A 1-byte code
representing one of 256 potential characters.
code segment -An executable section of programming code within a load module.
color dithering -See dithering.
color graphics adapter (CGA) -An adapter that simultaneously provides four
colors and is supported by all IBM Personal Computer and Personal System/2
models.
command -The name and parameters associated with an action that a program can
perform.
command area -An area composed of a command field prompt and a command entry
field.
command entry field -An entry field in which users type commands.
command line -On a display screen, a display line, sometimes at the bottom of
the screen, in which only commands can be entered.
command mode -A state of a system or device in which the user can enter
commands.
command prompt -A field prompt showing the location of the command entry
field in a panel.
Common Programming Interface (CPI) -Definitions of those application
development languages and services that have, or are intended to have,
implementations on and a high degree of commonality across the SAA
environments. One of the three SAA architectural areas. See also Common User
Access architecture.
Common User Access (CUA) architecture - Guidelines for the dialog between a
human and a workstation or terminal. One of the three SAA architectural
areas. See also Common Programming Interface.
compile -To translate a program written in a higher-level programming
language into a machine language program.
composite window -A window composed of other windows (such as a frame window,
frame-control windows, and a client window) that are kept together as a unit
and that interact with each other.
computer-aided design (CAD) -The use of a computer to design or change a
product, tool, or machine, such as using a computer for drafting or
illustrating.
COM1, COM2, COM3 -Character-device names reserved for serial ports 1 through
3.
CON -Character-device name reserved for the console keyboard and screen.
conditional cascaded menu -A pull-down menu associated with a menu item that
has a cascade mini-push button beside it in an object's pop-up menu. The
conditional cascaded menu is displayed when the user selects the mini-push
button.
container -In SAA Common User Access architecture, an object that holds other
objects. A folder is an example of a container object. See also folder and
object.
contextual help -In SAA Common User Access Architecture, help that gives
specific information about the item the cursor is on. The help is contextual
because it provides information about a specific item as it is currently
being used. Contrast with extended help.
contiguous -Touching or joining at a common edge or boundary, for example, an
unbroken consecutive series of storage locations.
control -In SAA Advanced Common User Access architecture, a component of the
user interface that allows a user to select choices or type information; for
example, a check box, an entry field, a radio button.
control area -A storage area used by a computer program to hold control information. (I) (A)
Control Panel -In the Presentation Manager, a program used to set up user
preferences that act globally across the system.
Control Program -(1) The basic functions of the operating system, including
DOS emulation and the support for keyboard, mouse, and video input/output.
(2) A computer program designed to schedule and to supervise the execution
of programs of a computer system. (I) (A)
control window -A window that is used as part of a composite window to
perform simple input and output tasks. Radio buttons and check boxes are
examples.
control word -An instruction within a document that identifies its parts or
indicates how to format the document.
coordinate space -A two-dimensional set of points used to generate output on
a video display of printer.
Copy -A choice that places onto the clipboard, a copy of what the user has
selected. See also Cut and Paste.
correlation -The action of determining which element or object within a
picture is at a given position on the display. This follows a pick
operation.
coverpage window -A window in which the application's help information is
displayed.
CPI -Common Programming Interface.
critical extended attribute -An extended attribute that is necessary for the
correct operation of the system or a particular application.
critical section -(1) In programming languages, a part of an asynchronous
procedure that cannot be executed simultaneously with a certain part of
another asynchronous procedure. (I)
Note: Part of the other asynchronous procedure also is a critical section.
(2) A section of code that is not reentrant; that is, code that can be
executed by only one thread at a time.
CUA architecture -Common User Access architecture.
current position -In computer graphics, the position, in user coordinates,
that becomes the starting point for the next graphics routine, if that
routine does not explicitly specify a starting point.
cursor -A symbol displayed on the screen and associated with an input device.
The cursor indicates where input from the device will be placed. Types of
cursors include text cursors, graphics cursors, and selection cursors.
Contrast with pointer and input focus.
Cut -In SAA Common User Access architecture, a choice that removes a selected
object, or a part of an object, to the clipboard, usually compressing the
space it occupied in a window. See also Copy and Paste.
ΓòÉΓòÉΓòÉ <hidden> Glossary - D ΓòÉΓòÉΓòÉ
daisy chain -A method of device interconnection for determining interrupt
priority by connecting the interrupt sources serially.
data segment -A nonexecutable section of a program module; that is, a section
of a program that contains data definitions.
data structure -The syntactic structure of symbolic expressions and their
storage-allocation characteristics. (T)
data transfer -The movement of data from one object to another by way of the
clipboard or by direct manipulation.
DBCS -Double-byte character set.
DDE -Dynamic data exchange.
deadlock -(1) Unresolved contention for the use of a resource. (2) An error
condition in which processing cannot continue because each of two elements
of the process is waiting for an action by, or a response from, the other.
(3) An impasse that occurs when multiple processes are waiting for the
availability of a resource that will not become available because it is
being held by another process that is in a similar wait state.
debug -To detect, diagnose, and eliminate errors in programs. (T)
decipoint -In printing, one tenth of a point. There are 72 points in an
inch.
default procedure -A function provided by the Presentation Manager Interface
that may be used to process standard messages from dialogs or windows.
default value -A value assumed when no value has been specified. Synonymous
with assumed value. For example, in the graphics programming interface, the
default line-type is 'solid'.
definition list -A type of list that pairs a term and its description.
delta -An application-defined threshold, or number of container items, from
either end of the list.
descendant -See child process.
descriptive text -Text used in addition to a field prompt to give more
information about a field.
Deselect all -A choice that cancels the selection of all of the objects that
have been selected in that window.
Desktop Manager -In the Presentation Manager, a window that displays a list
of groups of programs, each of which can be started or stopped.
desktop window -The window, corresponding to the physical device, against
which all other types of windows are established.
detached process -A background process that runs independent of the parent
process.
detent -A point on a slider that represents an exact value to which a user
can move the slider arm.
device context -A logical description of a data destination such as memory,
metafile, display, printer, or plotter. See also direct device context,
information device context, memory device context, metafile device context,
queued device context, and screen device context.
device driver -A file that contains the code needed to attach and use a
device such as a display, printer, or plotter.
device space -(1) Coordinate space in which graphics are assembled after all
GPI transformations have been applied. Device space is defined in
device-specific units. (2) ( D of C) In computer graphics, a space defined
by the complete set of addressable points of a display device. (A)
dialog -The interchange of information between a computer and its user
through a sequence of requests by the user and the presentation of responses
by the computer.
dialog box -In SAA Advanced Common User Access architecture, a movable
window, fixed in size, containing controls that a user uses to provide
information required by an application so that it can continue to process a
user request. See also message box, primary window, secondary window. Also
known as a pop-up window.
Dialog Box Editor -A WYSIWYG editor that creates dialog boxes for
communicating with the application user.
dialog item -A component (for example, a menu or a button) of a dialog box.
Dialog items are also used when creating dialog templates.
dialog procedure -A dialog window that is controlled by a window procedure.
It is responsible for responding to all messages sent to the dialog window.
dialog tag language -A markup language used by the DTL compiler to create
dialog objects.
dialog template -The definition of a dialog box, which contains details of
its position, appearance, and window ID, and the window ID of each of its
child windows.
direct device context -A logical description of a data destination that is a
device other than the screen (for example, a printer or plotter), and where
the output is not to go through the spooler. Its purpose is to satisfy
queries. See also device context.
direct manipulation -The user's ability to interact with an object by using
the mouse, typically by dragging an object around on the Desktop and
dropping it on other objects.
direct memory access (DMA) -A technique for moving data directly between main
storage and peripheral equipment without requiring processing of the data by
the processing unit.(T)
directory -A type of file containing the names and controlling information
for other files or other directories.
display point -Synonym for pel.
dithering -(1) The process used in color displays whereby every other pel is
set to one color, and the intermediate pels are set to another. Together
they produce the effect of a third color at normal viewing distances. This
process can only be used on solid areas of color; it does not work, for
example, on narrow lines. (2) (D of C ) In computer graphics, a technique of
interleaving dark and light pixels so that the resulting image looks
smoothly shaded when viewed from a distance.
DMA -Direct memory access.
DOS Protect Mode Interface (DPMI) -An interface between protect mode and real
mode programs.
double-byte character set (DBCS) -A set of characters in which each character
is represented by two bytes. Languages such as Japanese, Chinese, and
Korean, which contain more characters than can be represented by 256 code
points, require double-byte character sets. Since each character requires
two bytes, the entering, displaying, and printing of DBCS characters
requires hardware and software that can support DBCS.
doubleword -A contiguous sequence of bits or characters that comprises two
computer words and is capable of being addressed as a unit. (A)
DPMI -DOS Protect Mode Interface.
drag -In SAA Common User Access, to use a pointing device to move an object;
for example, clicking on a window border, and dragging it to make the window
larger.
dragging -(1) In computer graphics, moving an object on the display screen as
if it were attached to the pointer. (2) (D of C) In computer graphics,
moving one or more segments on a display surface by translating. (I) (A)
drawing chain -See segment chain.
drop -To fix the position of an object that is being dragged, by releasing
the select button of the pointing device.
drop -To fix the position of an object that is being dragged, by releasing
the select button of the pointing device. See also drag.
DTL -Dialog tag language.
dual-boot function -A feature of the OS/2 operating system that allows the
user to start DOS from within the operating system, or an OS/2 session from
within DOS.
duplex -Pertaining to communication in which data can be sent and received at
the same time. Synonymous with full duplex.
dynamic data exchange (DDE) -A message protocol used to communicate between
applications that share data. The protocol uses shared memory as the means
of exchanging data between applications.
dynamic data formatting -A formatting procedure that enables you to
incorporate text, bit maps or metafiles in an IPF window at execution time.
dynamic link library -A collection of executable programming code and data
that is bound to an application at load time or run time, rather than during
linking. The programming code and data in a dynamic link library can be
shared by several applications simultaneously.
dynamic linking -The process of resolving external references in a program
module at load time or run time rather than during linking.
dynamic segments -Graphics segments drawn in exclusive-OR mix mode so that
they can be moved from one screen position to another without affecting the
rest of the displayed picture.
dynamic storage -(1) A device that stores data in a manner that permits the
data to move or vary with time such that the specified data is not always
available for recovery. (A) (2) A storage in which the cells require
repetitive application of control signals in order to retain stored data.
Such repetitive application of the control signals is called a refresh
operation. A dynamic storage may use static addressing or sensing
circuits. (A) (3) See also static storage.
dynamic time slicing -Varies the size of the time slice depending on system
load and paging activity.
dynamic-link module -A module that is linked at load time or run time.
ΓòÉΓòÉΓòÉ <hidden> Glossary - E ΓòÉΓòÉΓòÉ
EBCDIC -Extended binary-coded decimal interchange code. A coded character set
consisting of 8-bit coded characters (9 bits including parity check), used
for information interchange among data processing systems, data
communications systems, and associated equipment.
edge-triggered -Pertaining to an event semaphore that is posted then reset
before a waiting thread gets a chance to run. The semaphore is considered to
be posted for the rest of that thread's waiting period; the thread does not
have to wait for the semaphore to be posted again.
EGA -Extended graphics adapter.
element -An entry in a graphics segment that comprises one or more graphics
orders and that is addressed by the element pointer.
EMS -Expanded Memory Specification.
encapsulation -Hiding an object's implementation, that is, its private,
internal data and methods. Private variables and methods are accessible only
to the object that contains them.
entry field -In SAA Common User Access architecture, an area where a user
types information. Its boundaries are usually indicated. See also selection
field.
entry panel -A defined panel type containing one or more entry fields and
protected information such as headings, prompts, and explanatory text.
entry-field control -The component of a user interface that provides the
means by which the application receives data entered by the user in an entry
field. When it has the input focus, the entry field displays a flashing
pointer at the position where the next typed character will go.
environment segment -The list of environment variables and their values for a
process.
environment strings -ASCII text strings that define the value of environment
variables.
environment variables -Variables that describe the execution environment of a
process. These variables are named by the operating system or by the
application. Environment variables named by the operating system are PATH,
DPATH, INCLUDE, INIT, LIB, PROMPT, and TEMP. The values of environment
variables are defined by the user in the CONFIG.SYS file, or by using the
SET command at the OS/2 command prompt.
error message -An indication that an error has been detected. (A)
event semaphore -A semaphore that enables a thread to signal a waiting thread
or threads that an event has occurred or that a task has been completed. The
waiting threads can then perform an action that is dependent on the
completion of the signaled event.
exception -An abnormal condition such as an I/O error encountered in
processing a data set or a file.
exclusive system semaphore -A system semaphore that can be modified only by
threads within the same process.
executable file -(1) A file that contains programs or commands that perform
operations or actions to be taken. (2) A collection of related data records
that execute programs.
exit -To execute an instruction within a portion of a computer program in
order to terminate the execution of that portion. Such portions of computer
programs include loops, subroutines, modules, and so on. (T) Repeated exit
requests return the user to the point from which all functions provided to
the system are accessible. Contrast with cancel.
expanded memory specification (EMS) -Enables DOS applications to access
memory above the 1MB real mode addressing limit.
extended attribute -An additional piece of information about a file object,
such as its data format or category. It consists of a name and a value. A
file object may have more than one extended attribute associated with it.
extended help -In SAA Common User Access architecture, a help action that
provides information about the contents of the application window from which
a user requested help. Contrast with contextual help.
extended-choice selection -A mode that allows the user to select more than
one item from a window. Not all windows allow extended choice selection.
Contrast with multiple-choice selection.
extent -Continuous space on a disk or diskette that is occupied by or
reserved for a particular data set, data space, or file.
external link -In Information Presentation Facility, a link that connects
external online document files.
ΓòÉΓòÉΓòÉ <hidden> Glossary - F ΓòÉΓòÉΓòÉ
family-mode application -An application program that can run in the OS/2
environment and in the DOS environment; however, it cannot take advantage of
many of the OS/2-mode facilities, such as multitasking, interprocess
communication, and dynamic linking.
FAT -File allocation table.
FEA -Full extended attribute.
field-level help -Information specific to the field on which the cursor is
positioned. This help function is "contextual" because it provides
information about a specific item as it is currently used; the information
is dependent upon the context within the work session.
FIFO -First-in-first-out. (A)
file -A named set of records stored or processed as a unit. (T)
file allocation table (FAT) -In IBM personal computers, a table used by the
operating system to allocate space on a disk for a file, and to locate and
chain together parts of the file that may be scattered on different sectors
so that the file can be used in a random or sequential manner.
file attribute -Any of the attributes that describe the characteristics of a
file.
File Manager -In the Presentation Manager, a program that displays
directories and files, and allows various actions on them.
file specification -The full identifier for a file, which includes its drive
designation, path, file name, and extension.
file system -The combination of software and hardware that supports storing
information on a storage device.
file system driver (FSD) -A program that manages file I\O and controls the
format of information on the storage media.
fillet -A curve that is tangential to the end points of two adjoining lines.
See also polyfillet.
filtering -An application process that changes the order of data in a queue.
first-in-first-out (FIFO) -A queuing technique in which the next item to be
retrieved is the item that has been in the queue for the longest time. (A)
flag -(1) An indicator or parameter that shows the setting of a switch. (2) A
character that signals the occurrence of some condition, such as the end of
a word. (A) (3) (D of C) A characteristic of a file or directory that
enables it to be used in certain ways. See also archive flag, hidden flag,
and read-only flag.
focus -See input focus.
folder -A container used to organize objects.
font -A particular size and style of typeface that contains definitions of
character sets, marker sets, and pattern sets.
Font Editor -A utility program provided with the IBM Developers Toolkit that
enables the design and creation of new fonts.
foreground program -(1) The program with which the user is currently
interacting. Also known as interactive program. Contrast with background
program. (2) (D of C) In multiprogramming, a high-priority program.
frame -The part of a window that can contain several different visual
elements specified by the application, but drawn and controlled by the
Presentation Manager. The frame encloses the client area.
frame styles -Standard window layouts provided by the Presentation Manager.
FSD -File system driver.
full-duplex -Synonym for duplex.
full-screen application -An application that has complete control of the
screen.
function -(1) In a programming language, a block, with or without formal
parameters, whose execution is invoked by means of a call. (2) A set of
related control statements that cause one or more programs to be performed.
function key -A key that causes a specified sequence of operations to be
performed when it is pressed, for example, F1 and Alt-K.
function key area -The area at the bottom of a window that contains function
key assignments such as F1=Help.
ΓòÉΓòÉΓòÉ <hidden> Glossary - G ΓòÉΓòÉΓòÉ
GDT -Global Descriptor Table.
general protection fault -An exception condition that occurs when a process
attempts to use storage or a module that has some level of protection
assigned to it, such as I/O privilege level. See also IOPL code segment.
Global Descriptor Table (GDT) -A table that defines code and data segments
available to all tasks in an application.
global dynamic-link module -A dynamic-link module that can be shared by all
processes in the system that refer to the module name.
global file-name character -Either a question mark (?) or an asterisk (*)
used as a variable in a file name or file name extension when referring to a
particular file or group of files.
glyph -A graphic symbol whose appearance conveys information.
GPI -Graphics programming interface.
graphic primitive -In computer graphics, a basic element, such as an arc or a
line, that is not made up of smaller parts and that is used to create
diagrams and pictures. See also graphics segment.
graphics -(1) A picture defined in terms of graphic primitives and graphics
attributes. (2) (D of C) The making of charts and pictures. (3) Pertaining
to charts, tables, and their creation. (4) See computer graphics, coordinate
graphics, fixed-image graphics, interactive graphics, passive graphics,
raster graphics.
graphics attributes -Attributes that apply to graphic primitives. Examples
are color, line type, and shading-pattern definition. See also segment
attributes.
graphics field -The clipping boundary that defines the visible part of the
presentation-page contents.
graphics mode -One of several states of a display. The mode determines the
resolution and color content of the screen.
graphics model space -The conceptual coordinate space in which a picture is
constructed after any model transforms have been applied. Also known as
model space.
Graphics programming interface -The formally defined programming language
that is between an IBM graphics program and the user of the program.
graphics segment -A sequence of related graphic primitives and graphics
attributes. See also graphic primitive.
graying -The indication that a choice on a pull-down is unavailable.
group -A collection of logically connected controls. For example, the buttons
controlling paper size for a printer could be called a group. See also
program group.
ΓòÉΓòÉΓòÉ <hidden> Glossary - H ΓòÉΓòÉΓòÉ
handle -(1) An identifier that represents an object, such as a device or
window, to the Presentation Interface. (2) (D of C) In the Advanced DOS and
OS/2 operating systems, a binary value created by the system that identifies
a drive, directory, and file so that the file can be found and opened.
hard error -An error condition on a network that requires either that the
system be reconfigured or that the source of the error be removed before the
system can resume reliable operation.
header -(1) System-defined control information that precedes user data. (2)
The portion of a message that contains control information for the message,
such as one or more destination fields, name of the originating station,
input sequence number, character string indicating the type of message, and
priority level for the message.
heading tags -A document element that enables information to be displayed in
windows, and that controls entries in the contents window controls placement
of push buttons in a window, and defines the shape and size of windows.
heap -An area of free storage available for dynamic allocation by an
application. Its size varies according to the storage requirements of the
application.
help function -(1) A function that provides information about a specific
field, an application panel, or information about the help facility. (2) (D
of C) One or more display images that describe how to use application
software or how to do a system operation.
Help index -In SAA Common User Access architecture, a help action that
provides an index of the help information available for an application.
help panel -A panel with information to assist users that is displayed in
response to a help request from the user.
help window -A Common-User-Access-defined secondary window that displays
information when the user requests help.
hidden file -An operating system file that is not displayed by a directory
listing.
hide button -In the OS/2 operating system, a small, square button located in
the right-hand corner of the title bar of a window that, when selected,
removes from the screen all the windows associated with that window.
Contrast with maximize button. See also restore button.
hierarchical inheritance -The relationship between parent and child classes.
An object that is lower in the inheritance hierarchy than another object,
inherits all the characteristics and behaviors of the objects above it in
the hierarchy.
hierarchy -A tree of segments beginning with the root segment and proceeding
downward to dependent segment types.
high-performance file system (HPFS) -In the OS/2 operating system, an
installable file system that uses high-speed buffer storage, known as a
cache, to provide fast access to large disk volumes. The file system also
supports the coexistence of multiple, active file systems on a single
personal computer, with the capability of multiple and different storage
devices. File names used with the HPFS can have as many as 254 characters.
hit testing -The means of identifying which window is associated with which
input device event.
hook -A point in a system-defined function where an application can supply
additional code that the system processes as though it were part of the
function.
hook chain -A sequence of hook procedures that are "chained" together so that
each event is passed, in turn, to each procedure in the chain.
hot spot -The part of the pointer that must touch an object before it can be
selected. This is usually the tip of the pointer. Contrast with action
point.
HPFS -high-performance file system.
hypergraphic link -A connection between one piece of information and another
through the use of graphics.
hypertext -A way of presenting information online with connections between
one piece of information and another, called hypertext links. See also
hypertext link.
hypertext link -A connection between one piece of information and another.
ΓòÉΓòÉΓòÉ <hidden> Glossary - I ΓòÉΓòÉΓòÉ
I/O operation -An input operation to, or output operation from a device
attached to a computer.
I-beam pointer -A pointer that indicates an area, such as an entry field in
which text can be edited.
icon -In SAA Advanced Common User Access architecture, a graphical
representation of an object, consisting of an image, image background, and a
label. Icons can represent items (such as a document file) that the user
wants to work on, and actions that the user wants to perform. In the
Presentation Manager, icons are used for data objects, system actions, and
minimized programs.
icon area -In the Presentation Manager, the area at the bottom of the screen
that is normally used to display the icons for minimized programs.
Icon Editor -The Presentation Manager-provided tool for creating icons.
IDL -Interface Definition Language.
image font -A set of symbols, each of which is described in a rectangular
array of pels. Some of the pels in the array are set to produce the image of
one of the symbols. Contrast with outline font.
implied metaclass -Subclassing the metaclass of a parent class without a
separate CSC for the resultant metaclass.
indirect manipulation -Interaction with an object through choices and
controls.
information device context -A logical description of a data destination other
than the screen (for example, a printer or plotter), but where no output
will occur. Its purpose is to satisfy queries. See also device context.
information panel -A defined panel type characterized by a body containing
only protected information.
Information Presentation Facility (IPF) -A facility provided by the OS/2
operating system, by which application developers can produce online
documentation and context-sensitive online help panels for their
applications.
inheritance -The derivation of new (child) classes from existing (parent)
classes. The new class inherits all the data and methods of the parent class
without having to redefine them.
input focus -(1) The area of a window where user interaction is possible
using an input device, such as a mouse or the keyboard. (2) The position in
the active window where a user's normal interaction with the keyboard will
appear.
input router -An internal OS/2 process that removes messages from the system
queue.
input/output control -A device-specific command that requests a function of a
device driver.
installable file system (IFS) -A file system in which software is installed
when the operating system is started.
instance -A single occurrence of an object class that has a particular
behavior.
instruction pointer -In System/38, a pointer that provides addressability for
a machine interface instruction in a program.
integer atom -An atom that represents a predefined system constant and
carries no storage overhead. For example, names of window classes provided
by Presentation Manager are expressed as integer atoms.
interactive graphics -Graphics that can be moved or manipulated by a user at
a terminal.
interactive program -(1) A program that is running (active) and is ready to
receive (or is receiving) input from a user. (2) A running program that can
receive input from the keyboard or another input device. Compare with active
program and contrast with noninteractive program.
Also known as a foreground program.
interchange file -A file containing data that can be sent from one
Presentation Manager interface application to another.
Interface Definition Language (IDL) -Language-neutral interface specification
for a SOM class.
interpreter -A program that translates and executes each instruction of a
high-level programming language before it translates and executes.
interprocess communication (IPC) -In the OS/2 operating system, the exchange
of information between processes or threads through semaphores, pipes,
queues, and shared memory.
interval timer -(1) A timer that provides program interruptions on a
program-controlled basis. (2) An electronic counter that counts intervals of
time under program control.
IOCtl -Input/output control.
IOPL -Input/output privilege level.
IOPL code segment -An IOPL executable section of programming code that
enables an application to directly manipulate hardware interrupts and ports
without replacing the device driver. See also privilege level.
IPC -Interprocess communication.
IPF -Information Presentation Facility.
IPF compiler -A text compiler that interpret tags in a source file and
converts the information into the specified format.
IPF tag language -A markup language that provides the instructions for
displaying online information.
item -A data object that can be passed in a DDE transaction.
ΓòÉΓòÉΓòÉ <hidden> Glossary - J ΓòÉΓòÉΓòÉ
journal -A special-purpose file that is used to record changes made in the
system.
ΓòÉΓòÉΓòÉ <hidden> Glossary - K ΓòÉΓòÉΓòÉ
Kanji -A graphic character set used in Japanese ideographic alphabets.
KBD$ -Character-device name reserved for the keyboard.
kernel -The part of an operating system that performs basic functions, such
as allocating hardware resources.
kerning -The design of graphics characters so that their character boxes
overlap. Used to space text proportionally.
keyboard accelerator -A keystroke that generates a command message for an
application.
keyboard augmentation -A function that enables a user to press a keyboard key
while pressing a mouse button.
keyboard focus -A temporary attribute of a window. The window that has a
keyboard focus receives all keyboard input until the focus changes to a
different window.
Keys help -In SAA Common User Access architecture, a help action that
provides a listing of the application keys and their assigned functions.
ΓòÉΓòÉΓòÉ <hidden> Glossary - L ΓòÉΓòÉΓòÉ
label -In a graphics segment, an identifier of one or more elements that is
used when editing the segment.
LAN -local area network.
language support procedure -A function provided by the Presentation Manager
Interface for applications that do not, or cannot (as in the case of COBOL
and FORTRAN programs), provide their own dialog or window procedures.
lazy drag -See pickup and drop.
lazy drag set -See pickup set.
LDT -In the OS/2 operating system, Local Descriptor Table.
LIFO stack -A stack from which data is retrieved in last-in, first-out order.
linear address -A unique value that identifies the memory object.
linked list -Synonym for chained list.
list box -In SAA Advanced Common User Access architecture, a control that
contains scrollable choices from which a user can select one choice.
Note: In CUA architecture, this is a programmer term. The end user term is
selection list.
list button -A button labeled with an underlined down-arrow that presents a
list of valid objects or choices that can be selected for that field.
list panel -A defined panel type that displays a list of items from which
users can select one or more choices and then specify one or more actions to
work on those choices.
load time -The point in time at which a program module is loaded into main
storage for execution.
load-on-call -A function of a linkage editor that allows selected segments of
the module to be disk resident while other segments are executing. Disk
resident segments are loaded for execution and given control when any entry
point that they contain is called.
local area network (LAN) -(1) A computer network located on a user's premises
within a limited geographical area. Communication within a local area
network is not subject to external regulations; however, communication
across the LAN boundary may be subject to some form of regulation. (T)
Note: A LAN does not use store and forward techniques. (2) A network
inwhich a set of devices are connected to one another for communication and
that can be connected to a larger network.
Local Descriptor Table (LDT) -Defines code and data segments specific to a
single task.
lock -A serialization mechanism by means of which a resource is restricted
for use by the holder of the lock.
logical storage device -A device that the user can map to a physical (actual)
device.
LPT1, LPT2, LPT3 -Character-device names reserved for parallel printers 1
through 3.
ΓòÉΓòÉΓòÉ <hidden> Glossary - M ΓòÉΓòÉΓòÉ
main window -The window that is positioned relative to the desktop window.
manipulation button -The button on a pointing device a user presses to
directly manipulate an object.
map -(1) A set of values having a defined correspondence with the quantities
or values of another set. (I) (A) (2) To establish a set of values having
a defined correspondence with the quantities or values of another set. (I)
marker box -In computer graphics, the boundary that defines, in world
coordinates, the horizontal and vertical space occupied by a single marker
from a marker set.
marker symbol -A symbol centered on a point. Graphs and charts can use marker
symbols to indicate the plotted points.
marquee box -The rectangle that appears during a selection technique in which
a user selects objects by drawing a box around them with a pointing device.
Master Help Index -In the OS/2 operating system, an alphabetic list of help
topics related to using the operating system.
maximize -To enlarge a window to its largest possible size.
media window -The part of the physical device (display, printer, or plotter)
on which a picture is presented.
memory block -Part memory within a heap.
memory device context -A logical description of a data destination that is a
memory bit map. See also device context.
memory management -A feature of the operating system for allocating, sharing,
and freeing main storage.
memory object -Logical unit of memory requested by an application, which
forms the granular unit of memory manipulation from the application
viewpoint.
menu -In SAA Advanced Common User Access architecture, an extension of the
menu bar that displays a list of choices available for a selected choice in
the menu bar. After a user selects a choice in menu bar, the corresponding
menu appears. Additional pop-up windows can appear from menu choices.
menu bar -In SAA Advanced Common User Access architecture, the area near the
top of a window, below the title bar and above the rest of the window, that
contains choices that provide access to other menus.
menu button -The button on a pointing device that a user presses to view a
pop-up menu associated with an object.
message -(1) In the Presentation Manager, a packet of data used for
communication between the Presentation Manager interface and Presentation
Manager applications (2) In a user interface, information not requested by
users but presented to users by the computer in response to a user action or
internal process.
message box -(1) A dialog window predefined by the system and used as a
simple interface for applications, without the necessity of creating
dialog-template resources or dialog procedures. (2) (D of C) In SAA Advanced
Common User Access architecture, a type of window that shows messages to
users. See also dialog box, primary window, secondary window.
message filter -The means of selecting which messages from a specific window
will be handled by the application.
message queue -A sequenced collection of messages to be read by the
application.
message stream mode -A method of operation in which data is treated as a
stream of messages. Contrast with byte stream.
metacharacter -See global file-name character.
metaclass -The conjunction of an object and its class information; that is,
the information pertaining to the class as a whole, rather than to a single
instance of the class. Each class is itself an object, which is an instance
of the metaclass.
metafile -A file containing a series of attributes that set color, shape and
size, usually of a picture or a drawing. Using a program that can interpret
these attributes, a user can view the assembled image.
metafile device context -A logical description of a data destination that is
a metafile, which is used for graphics interchange. See also device context.
metalanguage -A language used to specify another language. For example, data
types can be described using a metalanguage so as to make the descriptions
independent of any one computer language.
method -A function that defines a behavior for a class or object.
method override -The replacement, by a child class, of the implementation of
a method inherited from a parent and an ancestor class.
mickey -A unit of measurement for physical mouse motion whose value depends
on the mouse device driver currently loaded.
micro presentation space -A graphics presentation space in which a restricted
set of the GPI function calls is available.
minimize -To remove from the screen all windows associated with an
application and replace them with an icon that represents the application.
mix -An attribute that determines how the foreground of a graphic primitive
is combined with the existing color of graphics output. Also known as
foreground mix. Contrast with background mix.
mixed character string -A string containing a mixture of one-byte and Kanji
or Hangeul (two-byte) characters.
mnemonic -(1) A method of selecting an item on a pull-down by means of typing
the highlighted letter in the menu item. (2) (D of C) In SAA Advanced Common
User Access architecture, usually a single character, within the text of a
choice, identified by an underscore beneath the character. If all characters
in a choice already serve as mnemonics for other choices, another character,
placed in parentheses immediately following the choice, can be used. When a
user types the mnemonic for a choice, the choice is either selected or the
cursor is moved to that choice.
modal dialog box -In SAA Advanced Common User Access architecture, a type of
movable window, fixed in size, that requires a user to enter information
before continuing to work in the application window from which it was
displayed. Contrast with modeless dialog box. Also known as a serial dialog
box. Contrast with parallel dialog box.
Note: In CUA architecture, this is a programmer term. The end user term is
pop-up window.
model space -See graphics model space.
modeless dialog box -In SAA Advanced Common User Access architecture, a type
of movable window, fixed in size, that allows users to continue their dialog
with the application without entering information in the dialog box. Also
known as a parallel dialog box. Contrast with modal dialog box.
Note: In CUA architecture, this is a programmer term. The end user term is
pop-up window.
module definition file -A file that describes the code segments within a load
module. For example, it indicates whether a code segment is loadable before
module execution begins (preload), or loadable only when referred to at run
time (load-on-call).
mouse -In SAA usage, a device that a user moves on a flat surface to position
a pointer on the screen. It allows a user to select a choice o function to
be performed or to perform operations on the screen, such as dragging or
drawing lines from one position to another.
MOUSE$ -Character-device name reserved for a mouse.
multiple-choice selection -In SAA Basic Common User Access architecture, a
type of field from which a user can select one or more choices or select
none. See also check box. Contrast with extended-choice selection.
multiple-line entry field -In SAA Advanced Common User Access architecture, a
control into which a user types more than one line of information. See also
single-line entry field.
multitasking -The concurrent processing of applications or parts of
applications. A running application and its data are protected from other
concurrently running applications.
mutex semaphore -(Mutual exclusion semaphore). A semaphore that enables
threads to serialize their access to resources. Only the thread that
currently owns the mutex semaphore can gain access to the resource, thus
preventing one thread from interrupting operations being performed by
another.
muxwait semaphore -(Multiple wait semaphore). A semaphore that enables a
thread to wait either for multiple event semaphores to be posted or for
multiple mutex semaphores to be released. Alternatively, a muxwait semaphore
can be set to enable a thread to wait for any ONE of the event or mutex
semaphores in the muxwait semaphore's list to be posted or released.
ΓòÉΓòÉΓòÉ <hidden> Glossary - N ΓòÉΓòÉΓòÉ
named pipe -A named buffer that provides client-to-server, server-to-client,
or full duplex communication between unrelated processes. Contrast with
unnamed pipe.
national language support (NLS) -The modification or conversion of a United
States English product to conform to the requirements of another language or
country. This can include the enabling or retrofitting of a product and the
translation of nomenclature, MRI, or documentation of a product.
nested list -A list that is contained within another list.
NLS -national language support.
non-8.3 file-name format -A file-naming convention in which file names can
consist of up to 255 characters. See also 8.3 file-name format.
noncritical extended attribute -An extended attribute that is not necessary
for the function of an application.
nondestructive read -Reading that does not erase the data in the source
location. (T)
noninteractive program -A running program that cannot receive input from the
keyboard or other input device. Compare with active program, and contrast
with interactive program.
nonretained graphics -Graphic primitives that are not remembered by the
Presentation Manager interface when they have been drawn. Contrast with
retained graphics.
null character (NUL) -(1) Character-device name reserved for a nonexistent
(dummy) device. (2) (D of C) A control character that is used to accomplish
media-fill or time-fill and that may be inserted into or removed from a
sequence of characters without affecting the meaning of the sequence;
however, the control of equipment or the format may be affected by this
character. (I) (A)
null-terminated string -A string of (n+1) characters where the (n+1)th
character is the 'null' character (0x00) Also known as 'zero-terminated'
string and 'ASCIIZ' string.
ΓòÉΓòÉΓòÉ <hidden> Glossary - O ΓòÉΓòÉΓòÉ
object -A set of data and actions that can be performed on that data.
Object Interface Definition Language (OIDL) -Specification language used in
SOM Version 1 for defining classes. Replaced by Interface Definition
Language (IDL).
object window -A window that does not have a parent but which might have
child windows. An object window cannot be presented on a device.
OIDL -Object Interface Definition Language.
open -To start working with a file, directory, or other object.
ordered list -Vertical arrangements of items, with each item in the list
preceded by a number or letter.
outline font -A set of symbols, each of which is created as a series of lines
and curves. Synonymous with vector font. Contrast with image font.
output area -An area of storage reserved for output. (A)
owner window -A window into which specific events that occur in another
(owned) window are reported.
ownership -The determination of how windows communicate using messages.
owning process -The process that owns the resources that might be shared with
other processes.
ΓòÉΓòÉΓòÉ <hidden> Glossary - P ΓòÉΓòÉΓòÉ
page -(1) A 4KB segment of contiguous physical memory. (2) (D of C) A defined
unit of space on a storage medium.
page viewport -A boundary in device coordinates that defines the area of the
output device in which graphics are to be displayed. The presentation-page
contents are transformed automatically to the page viewport in device space.
paint -(1) The action of drawing or redrawing the contents of a window. (2)
In computer graphics, to shade an area of a display image; for example,
with crosshatching or color.
panel -In SAA Basic Common User Access architecture, a particular arrangement
of information that is presented in a window or pop-up. If some of the
information is not visible, a user can scroll through the information.
panel area -An area within a panel that contains related information. The
three major Common User Access-defined panel areas are the action bar, the
function key area, and the panel body.
panel area separator -In SAA Basic Common User Access architecture, a solid,
dashed, or blank line that provides a visual distinction between two
adjacent areas of a panel.
panel body -The portion of a panel not occupied by the action bar, function
key area, title or scroll bars. The panel body can contain protected
information, selection fields, and entry fields. The layout and content of
the panel body determine the panel type.
panel body area -See client area.
panel definition -A description of the contents and characteristics of a
panel. A panel definition is the application developer's mechanism for
predefining the format to be presented to users in a window.
panel ID -In SAA Basic Common User Access architecture, a panel identifier,
located in the upper-left corner of a panel. A user can choose whether to
display the panel ID.
panel title -In SAA Basic Common User Access architecture, a particular
arrangement of information that is presented in a window or pop-up. If some
of the information is not visible, a user can scroll through the
information.
paper size -The size of paper, defined in either standard U.S. or European
names (for example, A, B, A4), and measured in inches or millimeters
respectively.
parallel dialog box -See modeless dialog box.
parameter list -A list of values that provides a means of associating
addressability of data defined in a called program with data in the calling
program. It contains parameter names and the order in which they are to be
associated in the calling and called program.
parent process -In the OS/2 operating system, a process that creates other
processes. Contrast with child process.
parent window -In the OS/2 operating system, a window that creates a child
window. The child window is drawn within the parent window. If the parent
window is moved, resized, or destroyed, the child window also will be moved,
resized, or destroyed. However, the child window can be moved and resized
independently from the parent window, within the boundaries of the parent
window. Contrast with child window.
partition -(1) A fixed-size division of storage. (2) On an IBM personal
computer fixed disk, one of four possible storage areas of variable size;
one may be accessed by DOS, and each of the others may be assigned to
another operating system.
Paste -A choice in the Edit pull-down that a user selects to move the
contents of the clipboard into a preselected location. See also Copy and
Cut.
path -The route used to locate files; the storage location of a file. A fully
qualified path lists the drive identifier, directory name, subdirectory name
(if any), and file name with the associated extension.
PDD -Physical device driver.
peeking -An action taken by any thread in the process that owns the queue to
examine queue elements without removing them.
pel -(1) The smallest area of a display screen capable of being addressed and
switched between visible and invisible states. Synonym for display point,
pixel, and picture element. (2) (D of C) Picture element.
persistent object -An object whose instance data and state are preserved
between system shutdown and system startup.
physical device driver (PDD) -A system interface that handles hardware
interrupts and supports a set of input and output functions.
pick -To select part of a displayed object using the pointer.
pickup -To add an object or set of objects to the pickup set.
pickup and drop -A drag operation that does not require the direct
manipulation button to be pressed for the duration of the drag.
pickup set -The set of objects that have been picked up as part of a pickup
and drop operation.
picture chain -See segment chain.
picture element -(1) Synonym for pel. (2) (D of C) In computer graphics, the
smallest element of a display surface that can be independently assigned
color and intensity. (T) . (3) The area of the finest detail that can be
reproduced effectively on the recording medium.
PID -Process identification.
pipe -(1) A named or unnamed buffer used to pass data between processes. A
process reads from or writes to a pipe as if the pipe were a standard-input
or standard-output file. See also named pipe and unnamed pipe. (2) (D of C)
To direct data so that the output from one process becomes the input to
another process. The standard output of one command can be connected to the
standard input of another with the pipe operator (|).
pixel -(1) Synonym for pel. (2) (D of C) Picture element.
plotter -An output unit that directly produces a hardcopy record of data on a
removable medium, in the form of a two-dimensional graphic representation. (T)
PM -Presentation Manager.
pointer -(1) The symbol displayed on the screen that is moved by a pointing
device, such as a mouse. The pointer is used to point at items that users
can select. Contrast with cursor. (2) A data element that indicates the
location of another data element. (T)
POINTER$ -Character-device name reserved for a pointer device (mouse screen
support).
pointing device -In SAA Advanced Common User Access architecture, an
instrument, such as a mouse, trackball, or joystick, used to move a pointer
on the screen.
pointings -Pairs of x-y coordinates produced by an operator defining
positions on a screen with a pointing device, such as a mouse.
polyfillet -A curve based on a sequence of lines. The curve is tangential to
the end points of the first and last lines, and tangential also to the
midpoints of all other lines. See also fillet.
polygon -One or more closed figures that can be drawn filled, outlined, or
filled and outlined.
polyline -A sequence of adjoining lines.
polymorphism -The ability to have different implementations of the same
method for two or more classes of objects.
pop -To retrieve an item from a last-in-first-out stack of items. Contrast
with push.
pop-up menu -A menu that lists the actions that a user can perform on an
object. The contents of the pop-up menu can vary depending on the context,
or state, of the object.
pop-up window -(1) A window that appears on top of another window in a
dialog. Each pop-up window must be completed before returning to the
underlying window. (2) (D of C) In SAA Advanced Common User Access
architecture, a movable window, fixed in size, in which a user provides
information required by an application so that it can continue to process a
user request.
presentation drivers -Special purpose I/O routines that handle field
device-independent I/O requests from the PM and its applications.
Presentation Manager (PM) -The interface of the OS/2 operating system that
presents, in windows a graphics-based interface to applications and files
installed and running under the OS/2 operating system.
presentation page -The coordinate space in which a picture is assembled for
display.
presentation space (PS) -(1) Contains the device-independent definition of a
picture. (2) (D of C) The display space on a display device.
primary window -In SAA Common User Access architecture, the window in which
the main interaction between the user and the application takes place. In a
multiprogramming environment, each application starts in its own primary
window. The primary window remains for the duration of the application,
although the panel displayed will change as the user's dialog moves forward.
See also secondary window.
primitive -In computer graphics, one of several simple functions for drawing
on the screen, including, for example, the rectangle, line, ellipse,
polygon, and so on.
primitive attribute -A specifiable characteristic of a graphic primitive. See
graphics attributes.
print job -The result of sending a document or picture to be printed.
Print Manager -In the Presentation Manager, the part of the spooler that
manages the spooling process. It also allows users to view print queues and
to manipulate print jobs.
privilege level -A protection level imposed by the hardware architecture of
the IBM personal computer. There are four privilege levels (number 0
through 3). Only certain types of programs are allowed to execute at each
privilege level. See also IOPL code segment.
procedure call -In programming languages, a language construct for invoking
execution of a procedure.
process -An instance of an executing application and the resources it is
using.
program -A sequence of instructions that a computer can interpret and
execute.
program details -Information about a program that is specified in the Program
Manager window and is used when the program is started.
program group -In the Presentation Manager, several programs that can be
acted upon as a single entity.
program name -The full file specification of a program. Contrast with program
title.
program title -The name of a program as it is listed in the Program Manager
window. Contrast with program name.
prompt -A displayed symbol or message that requests input from the user or
gives operational information; for example, on the display screen of an IBM
personal computer, the DOS A> prompt. The user must respond to the prompt in
order to proceed.
protect mode -A method of program operation that limits or prevents access to
certain instructions or areas of storage. Contrast with real mode.
protocol -A set of semantic and syntactic rules that determines the behavior
of functional units in achieving communication. (I)
pseudocode -An artificial language used to describe computer program
algorithms without using the syntax of any particular programming language. (A)
pull-down -(1) An action bar extension that displays a list of choices
available for a selected action bar choice. After users select an action bar
choice, the pull-down appears with the list of choices. Additional pop-up
windows may appear from pull-down choices to further extend the actions
available to users. (2) (D of C) In SAA Common User Access architecture,
pertaining to a choice in an action bar pull-down.
push -To add an item to a last-in-first-out stack of items. Contrast with
pop.
push button -In SAA Advanced Common User Access architecture, a rectangle
with text inside. Push buttons are used in windows for actions that occur
immediately when the push button is selected.
putback -To remove an object or set of objects from the lazy drag set. This
has the effect of undoing the pickup operation for those objects
putdown -To drop the objects in the lazy drag set on the target object.
ΓòÉΓòÉΓòÉ <hidden> Glossary - Q ΓòÉΓòÉΓòÉ
queue -(1) A linked list of elements waiting to be processed in FIFO order.
For example, a queue may be a list of print jobs waiting to be printed. (2)
(D of C) A line or list of items waiting to be processed; for example, work
to be performed or messages to be displayed.
queued device context -A logical description of a data destination (for
example, a printer or plotter) where the output is to go through the
spooler. See also device context.
ΓòÉΓòÉΓòÉ <hidden> Glossary - R ΓòÉΓòÉΓòÉ
radio button -(1) A control window, shaped like a round button on the screen,
that can be in a checked or unchecked state. It is used to select a single
item from a list. Contrast with check box. (2) In SAA Advanced Common User
Access architecture, a circle with text beside it. Radio buttons are
combined to show a user a fixed set of choices from which only one can be
selected. The circle is partially filled when a choice is selected.
RAS -Reliability, availability, and serviceability.
raster -(1) In computer graphics, a predetermined pattern of lines that
provides uniform coverage of a display space. (T) (2) The coordinate grid
that divides the display area of a display device. (A)
read-only file -A file that can be read from but not written to.
real mode -A method of program operation that does not limit or prevent
access to any instructions or areas of storage. The operating system loads
the entire program into storage and gives the program access to all system
resources. Contrast with protect mode.
realize -To cause the system to ensure, wherever possible, that the physical
color table of a device is set to the closest possible match in the logical
color table.
recursive routine -A routine that can call itself, or be called by another
routine that was called by the recursive routine.
reentrant -The attribute of a program or routine that allows the same copy of
the program or routine to be used concurrently by two or more tasks.
reference phrase -(1) A word or phrase that is emphasized in a
device-dependent manner to inform the user that additional information for
the word or phrase is available. (2) (D of C) In hypertext, text that is
highlighted and preceded by a single-character input field used to signify
the existence of a hypertext link.
reference phrase help -In SAA Common User Access architecture, highlighted
words or phrases within help information that a user selects to get
additional information.
refresh -To update a window, with changed information, to its current status.
region -A clipping boundary in device space.
register -A part of internal storage having a specified storage capacity and
usually intended for a specific purpose. (T)
remote file system -A file-system driver that gains access to a remote system
without a block device driver.
resource -The means of providing extra information used in the definition of
a window. A resource can contain definitions of fonts, templates,
accelerators, and mnemonics; the definitions are held in a resource file.
resource file -A file containing information used in the definition of a
window. Definitions can be of fonts, templates, accelerators, and mnemonics.
restore -To return a window to its original size or position following a
sizing or moving action.
retained graphics -Graphic primitives that are remembered by the Presentation
Manager interface after they have been drawn. Contrast with nonretained
graphics.
return code -(1) A value returned to a program to indicate the results of an
operation requested by that program. (2) A code used to influence the
execution of succeeding instructions.(A)
reverse video -(1) A form of highlighting a character, field, or cursor by
reversing the color of the character, field, or cursor with its background;
for example, changing a red character on a black background to a black
character on a red background. (2) In SAA Basic Common User Access
architecture, a screen emphasis feature that interchanges the foreground and
background colors of an item.
REXX Language -Restructured Extended Executor. A procedural language that
provides batch language functions along with structured programming
constructs such as loops; conditional testing and subroutines.
RGB -(1) Color coding in which the brightness of the additive primary colors
of light, red, green, and blue, are specified as three distinct values of
white light. (2) Pertaining to a color display that accepts signals
representing red, green, and blue.
roman -Relating to a type style with upright characters.
root segment -In a hierarchical database, the highest segment in the tree
structure.
round-robin scheduling -A process that allows each thread to run for a
specified amount of time.
run time -(1) Any instant at which the execution of a particular computer
program takes place. (T) (2) The amount of time needed for the execution of
a particular computer program. (T) (3) The time during which an instruction
in an instruction register is decoded and performed. Synonym for execution
time.
ΓòÉΓòÉΓòÉ <hidden> Glossary - S ΓòÉΓòÉΓòÉ
SAA -Systems Application Architecture.
SBCS -Single-byte character set.
scheduler -A computer program designed to perform functions such as
scheduling, initiation, and termination of jobs.
screen -In SAA Basic Common User Access architecture, the physical surface of
a display device upon which information is shown to a user.
screen device context -A logical description of a data destination that is a
particular window on the screen. See also device context.
SCREEN$ -Character-device name reserved for the display screen.
scroll bar -In SAA Advanced Common User Access architecture, a part of a
window, associated with a scrollable area, that a user interacts with to see
information that is not currently allows visible.
scrollable entry field -An entry field larger than the visible field.
scrollable selection field -A selection field that contains more choices than
are visible.
scrolling -Moving a display image vertically or horizontally in a manner such
that new data appears at one edge, as existing data disappears at the
opposite edge.
secondary window -A window that contains information that is dependent on
information in a primary window and is used to supplement the interaction in
the primary window.
sector -On disk or diskette storage, an addressable subdivision of a track
used to record one block of a program or data.
segment -See graphics segment.
segment attributes -Attributes that apply to the segment as an entity, as
opposed to the individual primitives within the segment. For example, the
visibility or detectability of a segment.
segment chain -All segments in a graphics presentation space that are defined
with the 'chained' attribute. Synonym for picture chain.
segment priority -The order in which segments are drawn.
segment store -An area in a normal graphics presentation space where retained
graphics segments are stored.
select -To mark or choose an item. Note that select means to mark or type in
a choice on the screen; enter means to send all selected choices to the
computer for processing.
select button -The button on a pointing device, such as a mouse, that is
pressed to select a menu choice. Also known as button 1.
selection cursor -In SAA Advanced Common User Access architecture, a visual
indication that a user has selected a choice. It is represented by outlining
the choice with a dotted box. See also text cursor.
selection field -(1) In SAA Advanced Common User Access architecture, a set
of related choices. See also entry field. (2) In SAA Basic Common User
Access architecture, an area of a panel that cannot be scrolled and contains
a fixed number of choices.
semantics -The relationships between symbols and their meanings.
semaphore -An object used by applications for signalling purposes and for
controlling access to serially reusable resources.
separator -In SAA Advanced Common User Access architecture, a line or color
boundary that provides a visual distinction between two adjacent areas.
serial dialog box -See modal dialog box.
serialization -The consecutive ordering of items.
serialize -To ensure that one or more events occur in a specified sequence.
serially reusable resource (SRR) -A logical resource or object that can be
accessed by only one task at a time.
session -(1) A routing mechanism for user interaction via the console; a
complete environment that determines how an application runs and how users
interact with the application. OS/2 can manage more than one session at a
time, and more than one process can run in a session. Each session has its
own set of environment variables that determine where OS/2 looks for
dynamic-link libraries and other important files. (2) (D of C) In the OS/2
operating system, one instance of a started program or command prompt. Each
session is separate from all other sessions that might be running on the
computer. The operating system is responsible for coordinating the resources
that each session uses, such as computer memory, allocation of processor
time, and windows on the screen.
Settings Notebook -A control window that is used to display the settings for
an object and to enable the user to change them.
shadow -An object that refers to another object. A shadow is not a copy of
another object, but is another representation of the object.
shadow box -The area on the screen that follows mouse movements and shows
what shape the window will take if the mouse button is released.
shared data -Data that is used by two or more programs.
shared memory -In the OS/2 operating system, a segment that can be used by
more than one program.
shear -In computer graphics, the forward or backward slant of a graphics
symbol or string of such symbols relative to a line perpendicular to the
baseline of the symbol.
shell -(1) A software interface between a user and the operating system of a
computer. Shell programs interpret commands and user interactions on devices
such as keyboards, pointing devices, and touch-sensitive screens, and
communicate them to the operating system. (2) Software that allows a kernel
program to run under different operating-system environments.
shutdown -The process of ending operation of a system or a subsystem,
following a defined procedure.
sibling processes -Child processes that have the same parent process.
sibling windows -Child windows that have the same parent window.
simple list -A list of like values; for example, a list of user names.
Contrast with mixed list.
single-byte character set (SBCS) -A character set in which each character is
represented by a one-byte code. Contrast with double-byte character set.
slider box -In SAA Advanced Common User Access architecture: a part of the
scroll bar that shows the position and size of the visible information in a
window relative to the total amount of information available. Also known as
thumb mark.
SOM -System Object Model.
source file -A file that contains source statements for items such as
high-level language programs and data description specifications.
source statement -A statement written in a programming language.
specific dynamic-link module -A dynamic-link module created for the exclusive
use of an application.
spin button -In SAA Advanced Common User Access architecture, a type of entry
field that shows a scrollable ring of choices from which a user can select a
choice. After the last choice is displayed, the first choice is displayed
again. A user can also type a choice from the scrollable ring into the
entry field without interacting with the spin button.
spline -A sequence of one or more Bezier curves.
spooler -A program that intercepts the data going to printer devices and
writes it to disk. The data is printed or plotted when it is complete and
the required device is available. The spooler prevents output from
different sources from being intermixed.
stack -A list constructed and maintained so that the next data element to be
retrieved is the most recently stored. This method is characterized as
last-in-first-out (LIFO).
standard window -A collection of window elements that form a panel. The
standard window can include one or more of the following window elements:
sizing borders, system menu icon, title bar, maximize/minimize/restore
icons, action bar and pull-downs, scroll bars, and client area.
static control -The means by which the application presents descriptive
information (for example, headings and descriptors) to the user. The user
cannot change this information.
static storage -(1) A read/write storage unit in which data is retained in
the absence of control signals. (A) Static storage may use dynamic
addressing or sensing circuits. (2) Storage other than dynamic storage. (A)
style -See window style.
subclass -A class that is a child of another class. See also Inheritance.
subdirectory -In an IBM personal computer, a file referred to in a root
directory that contains the names of other files stored on the diskette or
fixed disk.
swapping -(1) A process that interchanges the contents of an area of real
storage with the contents of an area in auxiliary storage. (I) (A) (2) In
a system with virtual storage, a paging technique that writes the active
pages of a job to auxiliary storage and reads pages of another job from
auxiliary storage into real storage. (3) The process of temporarily removing
an active job from main storage, saving it on disk, and processing another
job in the area of main storage formerly occupied by the first job.
switch -(1) In SAA usage, to move the cursor from one point of interest to
another; for example, to move from one screen or window to another or from
a place within a displayed image to another place on the same displayed
image. (2) In a computer program, a conditional instruction and an indicator
to be interrogated by that instruction. (3) A device or programming
technique for making a selection, for example, a toggle, a conditional jump.
switch list -See Task List.
symbolic identifier -A text string that equates to an integer value in an
include file, which is used to identify a programming object.
symbols -In Information Presentation Facility, a document element used to
produce characters that cannot be entered from the keyboard.
synchronous -Pertaining to two or more processes that depend upon the
occurrence of specific events such as common timing signals. (T) See also
asynchronous.
System Menu -In the Presentation Manager, the pull-down in the top left
corner of a window that allows it to be moved and sized with the keyboard.
System Object Model (SOM) -A mechanism for language-neutral, object-oriented
programming in the OS/2 environment.
system queue -The master queue for all pointer device or keyboard events.
system-defined messages -Messages that control the operations of applications
and provides input an other information for applications to process.
Systems Application Architecture (SAA) -A set of IBM software interfaces,
conventions, and protocols that provide a framework for designing and
developing applications that are consistent across systems.
ΓòÉΓòÉΓòÉ <hidden> Glossary - T ΓòÉΓòÉΓòÉ
table tags -In Information Presentation Facility, a document element that
formats text in an arrangement of rows and columns.
tag -(1) One or more characters attached to a set of data that contain
information about the set, including its identification. (I) (A) (2) In
Generalized Markup Language markup, a name for a type of document or
document element that is entered in the source document to identify it.
target object -An object to which the user is transferring information.
Task List -In the Presentation Manager, the list of programs that are active.
The list can be used to switch to a program and to stop programs.
terminate-and-stay-resident (TSR) -Pertaining to an application that modifies
an operating system interrupt vector to point to its own location (known as
hooking an interrupt).
text -Characters or symbols.
text cursor -A symbol displayed in an entry field that indicates where typed
input will appear.
text window -Also known as the VIO window.
text-windowed application -The environment in which the operating system
performs advanced-video input and output operations.
thread -A unit of execution within a process. It uses the resources of the
process.
thumb mark -The portion of the scroll bar that describes the range and
properties of the data that is currently visible in a window. Also known as
a slider box.
thunk -Term used to describe the process of address conversion, stack and
structure realignment, etc., necessary when passing control between 16-bit
and 32-bit modules.
tilde -A mark used to denote the character that is to be used as a mnemonic
when selecting text items within a menu.
time slice -(1) An interval of time on the processing unit allocated for use
in performing a task. After the interval has expired, processing-unit time
is allocated to another task, so a task cannot monopolize processing-unit
time beyond a fixed limit. (2) In systems with time sharing, a segment of
time allocated to a terminal job.
time-critical process -A process that must be performed within a specified
time after an event has occurred.
timer -A facility provided under the Presentation Manager, whereby
Presentation Manager will dispatch a message of class WM_TIMER to a
particular window at specified intervals. This capability may be used by an
application to perform a specific processing task at predetermined
intervals, without the necessity for the application to explicitly keep
track of the passage of time.
timer tick -See clock tick.
title bar -In SAA Advanced Common User Access architecture, the area at the
top of each window that contains the window title and system menu icon. When
appropriate, it also contains the minimize, maximize, and restore icons.
Contrast with panel title.
TLB -Translation lookaside buffer.
transaction -An exchange between a workstation and another device that
accomplishes a particular action or result.
transform -(1) The action of modifying a picture by scaling, shearing,
reflecting, rotating, or translating. (2) The object that performs or
defines such a modification; also referred to as a transformation.
Translation lookaside buffer (TLB) -A hardware-based address caching
mechanism for paging information.
Tree -In the Presentation Manager, the window in the File Manager that shows
the organization of drives and directories.
truncate -(1) To terminate a computational process in accordance with some
rule (A) (2) To remove the beginning or ending elements of a string. (3) To
drop data that cannot be printed or displayed in the line width specified or
available. (4) To shorten a field or statement to a specified length.
TSR -Terminate-and-stay-resident.
unnamed pipe -A circular buffer, created in memory, used by related processes
to communicate with one another. Contrast with named pipe.
unordered list -In Information Presentation Facility, a vertical arrangement
of items in a list, with each item in the list preceded by a special
character or bullet.
update region -A system-provided area of dynamic storage containing one or
more (not necessarily contiguous) rectangular areas of a window that are
visually invalid or incorrect, and therefore are in need of repainting.
user interface -Hardware, software, or both that allows a user to interact
with and perform operations on a system, program, or device.
User Shell -A component of OS/2 that uses a graphics-based, windowed
interface to allow the user to manage applications and files installed and
running under OS/2.
utility program -(1) A computer program in general support of computer
processes; for example, a diagnostic program, a trace program, a sort
program. (T) (2) A program designed to perform an everyday task such as
copying data from one storage device to another. (A)
ΓòÉΓòÉΓòÉ <hidden> Glossary - U ΓòÉΓòÉΓòÉ
There are no glossary terms for this starting letter.
ΓòÉΓòÉΓòÉ <hidden> Glossary - V ΓòÉΓòÉΓòÉ
value set control -A visual component that enables a user to select one
choice from a group of mutually exclusive choices.
vector font -A set of symbols, each of which is created as a series of lines
and curves. Synonymous with outline font. Contrast with image font.
VGA -Video graphics array.
view -A way of looking at an object's information.
viewing pipeline -The series of transformations applied to a graphic object
to map the object to the device on which it is to be presented.
viewing window -A clipping boundary that defines the visible part of model
space.
VIO -Video Input/Output.
virtual memory (VM) -Synonymous with virtual storage.
virtual storage -(1) The storage space that may be regarded as addressable
main storage by the user of a computer system in which virtual addresses are
mapped into real addresses. The size of virtual storage is limited by the
addressing scheme of the computer system and by the amount of auxiliary
storage available, not by the actual number of main storage
locations. (I) (A) (2) Addressable space that is apparent to the user as
the processor storage space, from which the instructions and the data are
mapped into the processor storage locations. (3) Synonymous with virtual
memory.
visible region -A window's presentation space, clipped to the boundary of the
window and the boundaries of any overlying window.
volume -(1) A file-system driver that uses a block device driver for input
and output operations to a local or remote device. (I) (2) A portion of
data, together with its data carrier, that can be handled conveniently as a
unit.
ΓòÉΓòÉΓòÉ <hidden> Glossary - W ΓòÉΓòÉΓòÉ
wildcard character -Synonymous with global file-name character.
window -(1) A portion of a display surface in which display images pertaining
to a particular application can be presented. Different applications can be
displayed simultaneously in different windows. (A) (2) An area of the
screen with visible boundaries within which information is displayed. A
window can be smaller than or the same size as the screen. Windows can
appear to overlap on the screen.
window class -The grouping of windows whose processing needs conform to the
services provided by one window procedure.
window coordinates -A set of coordinates by which a window position or size
is defined; measured in device units, or pels.
window handle -Unique identifier of a window, generated by Presentation
Manager when the window is created, and used by applications to direct
messages to the window.
window procedure -Code that is activated in response to a message. The
procedure controls the appearance and behavior of its associated windows.
window rectangle -The means by which the size and position of a window is
described in relation to the desktop window.
window resource -A read-only data segment stored in the .EXE file of an
application o the .DLL file of a dynamic link library.
window style -The set of properties that influence how events related to a
particular window will be processed.
window title -In SAA Advanced Common User Access architecture, the area in
the title bar that contains the name of the application and the OS/2
operating system file name, if applicable.
Workplace Shell -The OS/2 object-oriented, graphical user interface.
workstation -(1) A display screen together with attachments such as a
keyboard, a local copy device, or a tablet. (2) (D of C) One or more
programmable or nonprogrammable devices that allow a user to do work.
world coordinates -A device-independent Cartesian coordinate system used by
the application program for specifying graphical input and output. (I) (A)
world-coordinate space -Coordinate space in which graphics are defined before
transformations are applied.
WYSIWYG -What-You-See-Is-What-You-Get. A capability of a text editor to
continually display pages exactly as they will be printed.
ΓòÉΓòÉΓòÉ <hidden> Glossary - X ΓòÉΓòÉΓòÉ
There are no glossary terms for this starting letter.
ΓòÉΓòÉΓòÉ <hidden> Glossary - Y ΓòÉΓòÉΓòÉ
There are no glossary terms for this starting letter.
ΓòÉΓòÉΓòÉ <hidden> Glossary - Z ΓòÉΓòÉΓòÉ
z-order -The order in which sibling windows are presented. The topmost
sibling window obscures any portion of the siblings that it overlaps; the
same effect occurs down through the order of lower sibling windows.
zooming -The progressive scaling of an entire display image in order to give
the visual impression of movement of all or part of a display group toward
or away from an observer. (I) (A)
8.3 file-name format -A file-naming convention in which file names are
limited to eight characters before and three characters after a single dot.
Usually pronounced "eight-dot-three." See also non-8.3 file-name format.
ΓòÉΓòÉΓòÉ <hidden> IBM Trademark ΓòÉΓòÉΓòÉ
Trademark of the IBM Corporation.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of AT&T, Inc.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of the Adobe Systems Inc.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of the Microsoft Corporation.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of Linotype.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of Monotype Corporation, Limited.
ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ
Trademark of Intel Coporation.