TkGS Specification - Drawables
TkGS uses a state-based model. Graphics operations are performed on a TkGS_Drawable, which can refer to any
device: native window, Tk-emulated Xlib window, PostScript generator... A
TkGS_Drawable must be obtained before any graphics operation
and must be released at the end.
TkGS_Drawables are device-independent: they use object-oriented
paradigms, can be obtained from real-world objects (windows, printers...) or be
user-defined through the use of device drivers (eg. PostScript, OpenGL...).
Also, each TkGS_Drawable exposes its capabilities in a device-independent
manner.
Conceptually speaking, a TkGS_Drawable is very close to a
Windows DC (Device Context), in the sense that it is attached to a
specific device (eg. a window) and holds a drawing state, or context (eg.
drawing colors). Despite its name, it is quite different from a X Drawable. In
the special case of X, a TkGS_Drawable should contain
information about the display, the drawable (window or pixmap), and the GC. As X
is rather stateless, all three are usually passed to drawing primitives. Under
TkGS, only the TkGS_Drawable is needed. Internally,
TkGS_Drawables are implemented using
TkGS_Objs. As seen from the
outside,
TkGS_Drawables are opaque tokens.
- TkGS_Drawable
- Description
- A TkGS_Drawable corresponds to the drawing area on
which primitives are called. it retains state information about
parameters such as color, font, etc. (see TkGS_GC).
- This document does not specify how TkGS_Drawables
are obtained (however it provides an interface to get a
TkGS_Drawable from a Tk_Window).
Extension writers may provide their own APIs for returning valid
TkGS_Drawables. For example, a PostScript driver may
provide an API for getting a TkGS_Drawable to generate
a PostScript page of a given size. A native Windows printer extension
may provide an API for opening a printer dialog that returns a
TkGS_Drawable corresponding to a given print job. The
goal of TkGS is only to provide a device-independent way of performing
graphics jobs.
- Structure
- TkGS_Drawable 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_Drawable's internals are defined by the
TkGS_Drawable_<
/A>
structure (notice the trailing underscore).
- TkGS_GetDrawableDevice
- Description
- Retrieve the TkGS_Device
associated with the given TkGS_Drawable.
- Status
- Specification complete. Currently implemented as a macro.
- Declaration
-
TkGS_Device TkGS_GetDevice(
TkGS_Drawable drawable
);
- Arguments
drawable
: the TkGS_Drawable we want to
get information about.
- Returned value
- The corresponding TkGS_Device.
- Side effects
- None.
- TkGS_ReleaseDrawable
- Description
- This function is used to release a TkGS_Drawable
previously returned by device-specific procedures, once the drawing is
complete. While obtaining a valid TkGS_Drawable
depends on the device (window, printer, pixmap...), releasing it is done
in a device-independent manner.
- Declaration
-
void TkGS_ReleaseDrawable(
TkGS_Drawable drawable
);
- Arguments
drawable
: the TkGS_Drawable to
release.
- Returned value
- None.
- Side effects
- Storage is freed,
drawable
is not valid
anymore.