TkGS Specification - Graphics Contexts

Introduction

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.

Structures


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).

Functions


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.

TODO