TkGS Specification - Graphics Contexts
Graphics Contexts (GCs) correspond to the drawing parameters needed by graphics
primitives. TkGS defines a device-independent GC structure called TkGS_GCValues which is the visible
part of any device-dependent structure. TkGS_GCValues can then
be passed to any TkGS_Drawable and even
transmitted between TkGS_Drawable in a completely
device-independent manner.
The TkGS_GCValues structure is only the public part of a GC. In
addition, the opaque token TkGS_GC can
be used to save and restore any TkGS_Drawable's state.
Internally,
TkGS_GCs are implemented using
TkGS_Objs. As seen from the
outside,
TkGS_GCs are opaque tokens.
- TkGS_GCValues
- Description
- TkGS_GCValues is a system- and device-independent
structure that contains drawing parameters such as colors and fonts. It
is used to query and set TkGS_Drawables
drawing parameters.
- Status
- Specification incomplete. We may add many more parameters (fonts,
clipping,
stippling, dashes...).
- Structure
struct TkGS_GCValues {
TkGS_Color background;
TkGS_Color foreground;
unsigned int lineWidth;
TkGS_Font font;
}
- TkGS_GC
- Description
- TkGS_GCs can be used to store the current state
of a TkGS_Drawable
for later restoration.
- Structure
- TkGS_GC is an opaque token that holds
system-independent drawable information. Its internals could for example
hold X or Window-specific data about the drawable (window, printer
context...).
- TkGS_GC's internals are defined by the
TkGS_GC_
structure (notice the trailing underscore).
- TkGS_GetGCValues
- Description
- This function is used to fill a TkGS_GCValues structure with
the current state of the specified TkGS_Drawable.
- Status
- Complete.
- Declaration
-
void TkGS_GetGCValues(
TkGS_Drawable drawable,
unsigned long valueMask,
TkGS_GCValues *values
);
- Arguments
drawable
: the TkGS_Drawable
we
want to get attributes from.
valueMask
: an OR-ed combination of flags specifying the
values to get.
values
: a pointer to a TkGS_GCValues structure that
will be filled with the values specified by valueMask
.
- Returned value
- None.
- Side effects
- The requested fields of
valuesPtr
are modified.
- TkGS_SetGCValues
- Description
- This function is used to set the state of a given TkGS_Drawable
to
the values specified by a TkGS_GCValues structure.
- Status
- Complete.
- Declaration
-
void TkGS_SetGCValues(
TkGS_Drawable drawable,
unsigned long valueMask,
TkGS_GCValues *values
);
- Arguments
drawable
: the TkGS_Drawable
we
want to get attributes from.
valueMask
: an OR-ed combination of flags specifying the
values to set.
values
: a pointer to a TkGS_GCValues structure
containing the values specified by valueMask
.
- Returned value
- None.
- Side effects
drawable
's state is modified.
- TkGS_GetDrawableForeground
- TkGS_GetDrawableBackground
- TkGS_GetDrawableLineWidth
- TkGS_GetDrawableFont
- Description
- This functions are used to retrieve the corresponding drawing
parameters
from a specified TkGS_Drawable.
They are shorthands for single-parameter calls to
TkGS_GetDrawableGCValues.
- Status
- Complete.
- Declaration
-
TkGS_Color TkGS_GetDrawableForeground(
TkGS_Drawable drawable
);
TkGS_Color TkGS_GetDrawableBackground(
TkGS_Drawable drawable
);
unsigned int TkGS_GetDrawableLineWidth(
TkGS_Drawable drawable
);
unsigned TkGS_Font TkGS_GetDrawableFont(
TkGS_Drawable drawable
);
- Arguments
drawable
: the TkGS_Drawable
we
want to get attributes from.
- Returned value
- The requested parameter.
- Side effects
- None.
- TkGS_SetDrawableForeground
- TkGS_SetDrawableBackground
- TkGS_SetDrawableLineWidth
- TkGS_SetDrawableFont
- Description
- This functions are used to set the value of the corresponding
drawing parameters
of a given TkGS_Drawable
to
They are shorthands for single-parameter calls to
TkGS_SetDrawableGCValues.
- Status
- Complete.
- Declaration
-
void TkGS_SetDrawableForeground(
TkGS_Drawable drawable,
TkGS_Color color
);
void TkGS_SetDrawableBackground(
TkGS_Drawable drawable,
TkGS_Color color
);
void TkGS_SetDrawableLineWidth(
TkGS_Drawable drawable,
unsigned int lineWidth
);
void TkGS_SetDrawableFont(
TkGS_Drawable drawable,
TkGS_Font font
);
- Arguments
drawable
: the TkGS_Drawable
we
want to get attributes from.
color
or lineWidth
: the value to set.
- Returned value
- None.
- Side effects
drawable
's state is modified.
- TkGS_GetGC
- Description
- This function is used to retrieve the current state of the specified
TkGS_Drawable
in the form of a TkGS_GC. This
can be used to save the current state for later restoration with TkGS_SetGC(). This can be useful
for saving and restoring the current state before and after performing
complex drawing operations.
- Status
- Most likely to change (see TODO).
- Declaration
-
TkGS_GC TkGS_GetGC(
TkGS_Drawable drawable
);
- Arguments
drawable
: the TkGS_Drawable
we
want to get the state from.
- Returned value
- A newly allocated TkGS_GC
holding
drawable
's current state.
- Side effects
- Storage is allocated.
- TkGS_SetGC
- Description
- This function is used to set the state of the specified TkGS_Drawable
from a TkGS_GC. The current
state is lost.
- Status
- Most likely to change (see TODO).
- Declaration
-
void TkGS_SetGC(
TkGS_Drawable drawable,
TkGS_GC gc
);
- Arguments
drawable
: the TkGS_Drawable
we
want to modify.
gc
: the TkGS_GC
holding the state we want to set.
- Returned value
- None.
- Side effects
drawable
's state is modified.
- TkGS_FreeGC
- Description
- This function is used to free a TkGS_GC previously returned by TkGS_GetGC.
- Status
- Most likely to change (see TODO).
- Declaration
-
void TkGS_FreeGC(
TkGS_GC gc
);
- Arguments
gc
: the TkGS_GC
to free.
- Returned value
- None.
- Side effects
- Storage is freed, and
gc
is not valid anymore.
- Define more GC parameters and their associated masks.
- Define a more precise mechanism to store/restore GCs.
TkGS_{Set|Get|Free}GC
may not be the best solution with respect to the different graphics models:
X, Win32, PostScript...
Maybe a GC stack such as PostScript's
gsave/grestore or Win32's
SaveDC/RestoreDC?