EPS canvas C reference
See EPS canvas item implementation for ownership, failure and platform boundaries. These are private implementation interfaces.
- group EPS canvas item internals
Private command/canvas callbacks, not installed C APIs.
Functions
-
static char *SkipBlanks(EpsParseInfo *piPtr)
Locate the first non-whitespace byte in the current parser line.
Returns a borrowed pointer into piPtr->line, possibly its terminating NUL. Uses unsigned-byte character classification and does not modify the buffer, read the stream or advance nextPtr.
- Parameters:
piPtr – [in] Borrowed parser record whose current line is inspected without advancing state.
-
static int ReadPsLine(EpsParseInfo *piPtr)
Read one bounded chunk of the PostScript stream.
Borrow the FILE in piPtr and update bytesRead, lineNumber and line. A nonzero maxBytes limits the PostScript section; zero reads to EOF. Return FALSE at the limit or when fgets fails. Long physical lines may be split into chunks; this is not an arbitrary-length line reader.
- Parameters:
piPtr – [inout] Caller-owned parser state with the current line and borrowed input stream.
-
static void AppendPsLine(Tcl_DString *dStringPtr, const char *line)
Retain a string chunk with exactly one required trailing newline.
Appends the complete NUL-terminated input to an initialized caller-owned DString. Adds a newline only when the chunk is empty or lacks a final newline; existing content and multiple existing newlines are not normalized. Does not preserve byte identity for unterminated or size-limited source chunks.
- Parameters:
dStringPtr – [inout] Initialized caller-owned DString receiving appended text.
line – [in] Borrowed NUL-terminated text chunk.
-
static unsigned char ReverseBits(unsigned char byte)
Reverse the order of all eight bits in one byte.
Uses successive adjacent-bit, two-bit and nibble swaps. Returns the reversed byte without allocation, parser changes or host-endianness assumptions.
- Parameters:
byte – [in] Eight-bit value whose bit order is reversed.
-
static int GetHexValue(EpsParseInfo *piPtr, unsigned char *bytePtr)
Consume the next two-digit EPSI preview byte.
Uses nextPtr within the current line or reads another bounded chunk. New chunks must start with a percent sign; whitespace after that prefix and between byte pairs is skipped. Requires both hex digits in the same chunk. Returns TCL_OK and writes bytePtr only for a complete byte, TCL_RETURN for an EndPreview comment prefix, or TCL_ERROR for malformed/truncated input. Updates parser stream position and nextPtr on success; does not set a Tcl diagnostic.
- Parameters:
piPtr – [inout] Caller-owned parser state with the current line and borrowed input stream.
bytePtr – [out] Required output written only when a complete preview byte is decoded.
-
static void ReadEPSI(EpsItem *epsPtr, EpsParseInfo *piPtr)
Decode an optional one-bit or eight-bit EPSI preview.
Requires the current line to contain the recognized BeginPreview header. Accepts positive dimensions through SHRT_MAX and depths 1 or 8; parses but does not enforce the declared line count. Allocates a zeroed image and consumes the required hex bytes. Eight-bit samples become opaque inverted grayscale in bottom-to-top row order. One-bit rows consume high bits first with byte padding per row; zero bits become opaque white and set bits retain the zeroed pixel. Installs the owned image and consumed-line metadata on success. Decode failure frees the temporary and clears line markers, without rewinding input or reporting a Tcl error. Caller supplies an item ready to receive preview ownership.
- Parameters:
epsPtr – [inout] Canvas-owned EPS item; stream, preview and text ownership changes are described above.
piPtr – [inout] Caller-owned parser state with the current line and borrowed input stream.
-
static int ReadPostScript(Tcl_Interp *interp, EpsItem *epsPtr)
Parse EPS header metadata and retain its PostScript body.
Borrow the open psFile; reset the item DString and seek to psStart if needed. Require a percent-bang PS signature and an integer BoundingBox with positive, int-representable extents. Retain title and optional EPSI color preview on the item. Preserve an already-consumed first body line. Return TCL_ERROR with a diagnostic on header/seek failure; this does not restore prior item state.
- Parameters:
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
epsPtr – [inout] Canvas-owned EPS item; stream, preview and text ownership changes are described above.
-
static int OpenEpsFile(Tcl_Interp *interp, EpsItem *epsPtr)
Open the item file and parse its EPS section.
Own a binary stdio stream in psFile. On Windows recognize the DOS EPS header and record section offsets and lengths before parsing. Close the stream on seek or parse failure; on success the caller must eventually CloseEpsFile(). Recorded preview formats do not imply a general TIFF/WMF renderer.
- Parameters:
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
epsPtr – [inout] Canvas-owned EPS item; stream, preview and text ownership changes are described above.
-
static void CloseEpsFile(EpsItem *epsPtr)
Close and clear an item-owned stdio stream if present.
Does not release parsed text, preview pixels or other item resources.
- Parameters:
epsPtr – [inout] Canvas-owned EPS item; stream, preview and text ownership changes are described above.
-
static void DeleteEps(Tk_Canvas canvas, Tk_Item *itemPtr, Display *display)
Release resources of a canvas-owned EPS item.
Release options, file, DString, color snapshot, source-image instance, private photo, pixmaps, fill GC, title style and parsed title through their matching APIs. Detach tmpImage before temporary-image cleanup can notify clients. The canvas owns the item record itself; this function does not free it.
- Parameters:
canvas – [in] Borrowed owning Tk canvas; supplies window and coordinate conversion.
itemPtr – [inout] Canvas-owned initialized EpsItem; owned resources are released, but the record is not freed.
display – [in] Borrowed display matching the item graphics resources.
-
static int CreateEps(Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, Tcl_Size objc, Tcl_Obj *const objv[])
Initialize a canvas-owned EPS item and apply its creation options.
Returns Tcl status. A configuration failure releases initialized resources through DeleteEps; the item record remains caller-owned.
- Parameters:
interp – [inout] Borrowed result interpreter; see Interpreter arguments.
canvas – [in] Borrowed owning Tk canvas; supplies window and coordinate conversion.
itemPtr – [inout] Caller-allocated EpsItem with its Tk_Item header initialized; record ownership stays with the canvas.
objc – [in] Number of creation arguments; at least two coordinates are required.
objv – [in] Borrowed x/y coordinates followed by option/value pairs; see Tcl command arguments.
-
static void ImageChangedProc(ClientData clientData, int x, int y, int width, int height, int imageWidth, int imageHeight)
Notice deletion of a supplied EPS preview image.
Ordinary image changes do not refresh the saved color snapshot. If the retained instance is absent or deleted, frees and clears the source name and schedules redraw of the item rectangle. Keeps the image instance token for later reconfiguration/teardown because Tk still visits it after its deletion callback returns. Does not release the snapshot or temporary display photo.
- Parameters:
clientData – [inout] Borrowed canvas-owned EpsItem registered for image-change notifications.
x – [in] Changed image rectangle origin; ignored by this deletion-notification callback.
y – [in] Changed image rectangle origin; ignored by this deletion-notification callback.
width – [in] Changed image rectangle width; ignored by this callback.
height – [in] Changed image rectangle height; ignored by this callback.
imageWidth – [in] Current image width reported by Tk; ignored by this callback.
imageHeight – [in] Current image height reported by Tk; ignored by this callback.
-
static int EpsOptionSpecified(Tcl_Size objc, Tcl_Obj *const objv[], const char *optionName)
Find a supplied option prefix among validated option-value pairs.
Checks every option word with a following value against optionName, accepting a prefix no longer than the full name. Returns a Boolean without modifying arguments. Does not validate ambiguity, option syntax or values; ConfigureEps calls it after Tk configuration has validated the arguments. A trailing unmatched word is ignored by this helper.
- Parameters:
objc – [in] Number of borrowed objv entries; see Tcl command arguments.
objv – [in] Borrowed validated option/value pairs; a trailing unmatched entry is ignored.
optionName – [in] Borrowed full option name against which supplied prefixes are compared.
-
static int ConfigureEps(Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, Tcl_Size objc, Tcl_Obj *const objv[], int flags)
Apply legacy canvas options and rebuild EPS preview resources.
Use Tk_ConfigureWidget and explicit option-prefix detection for image, file and quick changes. Source images are photo-only and copied to owned pixels. Create or discard the temporary display photo as needed, rebuild the fill GC and bbox, and close the file on success. Return Tcl status. Resource updates are incremental, not a Tk_SetOptions saved-options rollback transaction.
- Parameters:
interp – [inout] Borrowed result interpreter; see Interpreter arguments.
canvas – [in] Borrowed owning Tk canvas; supplies window and coordinate conversion.
itemPtr – [inout] Borrowed initialized EpsItem; updates can remain partially applied on failure.
objc – [in] Number of option/value objects in objv.
objv – [in] Borrowed option/value array; see Tcl command arguments.
flags – [in] Tk_ConfigureWidget configuration flags, including TK_CONFIG_ARGV_ONLY for reconfiguration.
-
static int EpsCoords(Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, Tcl_Size objc, Tcl_Obj *const objv[])
Query or replace the EPS anchor coordinates.
Returns TCL_OK or TCL_ERROR. A query returns a two-value coordinate list; replacement converts both values before changing the item.
- Parameters:
interp – [inout] Borrowed result interpreter; see Interpreter arguments.
canvas – [in] Borrowed owning Tk canvas; supplies window and coordinate conversion.
itemPtr – [inout] Borrowed initialized EpsItem; anchor and bbox change only after both coordinates parse.
objc – [in] Zero for a query or two for an X/Y replacement; other counts are rejected.
objv – [in] Borrowed coordinate objects for replacement; not read for a query.
-
static void ComputeEpsBbox(Tk_Canvas canvas, EpsItem *epsPtr)
Map the item anchor and size into integer canvas bounds.
Round x/y, translate the anchor, then update canvasX/Y and the Tk_Item bbox. Right and bottom bounds are exclusive for canvas redraw. No graph axes, track viewport or renderer clip stack participates.
- Parameters:
canvas – [in] Borrowed owning canvas; retained item bounds supply the geometry.
epsPtr – [inout] Canvas-owned EPS item; stream, preview and text ownership changes are described above.
-
static void DisplayEps(Tk_Canvas canvas, Tk_Item *itemPtr, Display *display, Drawable drawable, int x, int y, int width, int height)
Draw the preview or placeholder through Tk canvas/native services.
Rescale the saved color snapshot only when cached dimensions differ. Quick mode uses resize; otherwise use box resampling. Publish into the private photo, release the intermediate buffer, and draw pixmap/photo or filled placeholder, optional title and border. Borrow the drawable and canvas. This path does not construct a graph renderer context.
- Parameters:
canvas – [in] Borrowed owning Tk canvas; supplies window and coordinate conversion.
itemPtr – [inout] Borrowed configured EpsItem; preview caches may be rebuilt.
display – [in] Borrowed display associated with the destination.
drawable – [in] Borrowed canvas drawable receiving the preview, title and border.
x – [in] Canvas redisplay rectangle X origin; unused.
y – [in] Canvas redisplay rectangle Y origin; unused.
width – [in] Canvas redisplay rectangle width; unused.
height – [in] Canvas redisplay rectangle height; unused.
-
static double EpsToPoint(Tk_Canvas canvas, Tk_Item *itemPtr, double *coordArr)
Measure point distance to the cached EPS item rectangle.
Uses cached canvas bounds and hypot of horizontal/vertical separation. Returns zero inside or on any rectangle edge, including right and bottom. Does not inspect preview alpha, PostScript paths or relief borders, change the item or invoke callbacks.
- Parameters:
canvas – [in] Borrowed owning canvas; retained item bounds supply the geometry.
itemPtr – [in] Borrowed canvas-owned Tk_Item header of an EpsItem.
coordArr – [in] Borrowed two-element query point {x,y} in canvas coordinates.
-
static int EpsToArea(Tk_Canvas canvas, Tk_Item *itemPtr, double *area)
Classify the EPS rectangle against a canvas query rectangle.
Requires ordered query bounds. Returns -1 for disjoint rectangles, including edge-only contact, 1 when the query contains the entire item, and 0 for partial overlap. Uses cached bounds without examining image pixels or modifying state.
- Parameters:
canvas – [in] Borrowed owning canvas; retained item bounds supply the geometry.
itemPtr – [in] Borrowed canvas-owned Tk_Item header of an EpsItem.
area – [in] Borrowed four-element ordered query rectangle {left,top,right,bottom}.
-
static void ScaleEps(Tk_Canvas canvas, Tk_Item *itemPtr, double originX, double originY, double scaleX, double scaleY)
Scale the anchor position about a canvas origin and recompute bounds.
Only x/y change. Configured width and height are not multiplied by scaleX/Y; canvas scale is not equivalent to resizing the preview.
- Parameters:
canvas – [in] Borrowed owning canvas; retained item bounds supply the geometry.
itemPtr – [inout] Borrowed canvas-owned Tk_Item header of an EpsItem.
originX – [in] Horizontal canvas coordinate about which the anchor is scaled.
originY – [in] Vertical canvas coordinate about which the anchor is scaled.
scaleX – [in] Horizontal anchor scale factor; configured width is unchanged.
scaleY – [in] Vertical anchor scale factor; configured height is unchanged.
-
static void TranslateEps(Tk_Canvas canvas, Tk_Item *itemPtr, double deltaX, double deltaY)
Move the canvas anchor and recompute the cached item bounds.
Adds deltaX/deltaY to the anchor, then calls ComputeEpsBbox. Does not change configured dimensions, resample preview pixels or request redraw itself; the canvas operation handles redisplay.
- Parameters:
canvas – [in] Borrowed owning canvas; retained item bounds supply the geometry.
itemPtr – [inout] Borrowed canvas-owned Tk_Item header of an EpsItem.
deltaX – [in] Horizontal displacement in canvas coordinates.
deltaY – [in] Vertical displacement in canvas coordinates.
-
static int EpsToPostScript(Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, int prepass)
Append EPS item output to the canvas PostScript result.
Prepass is a no-op. With a file, load rbcCanvEps.pro, transform and clip to the EPS bounding box, and append the retained body between encapsulation guards. Without a file, serialize the cached temporary photo when present. Own a PsToken for output construction and release it on the handled output paths. This callback does not regenerate a stale preview or export SVG/PDF.
- Parameters:
interp – [inout] Borrowed interpreter for results and diagnostics; see Interpreter arguments.
canvas – [in] Borrowed owning canvas; retained item bounds supply the geometry.
itemPtr – [inout] Borrowed canvas-owned Tk_Item header of an EpsItem.
prepass – [in] Nonzero requests the canvas prepass, which emits no output.
-
void Rbc_InitEpsCanvasItem(Tcl_Interp *interp)
Register the EPS canvas item type and Tk tag option callbacks.
Registers the static Tk item-type descriptor. Does not create a canvas or item.
- Parameters:
interp – [in] Interpreter supplied by package initialization; currently unused.
-
static char *SkipBlanks(EpsParseInfo *piPtr)
Data records and member contracts
These records describe stored state and resource ownership. Their presence in the reference does not make private layouts part of the installed C API.
-
struct EpsItem
Canvas EPS item owning parsed PostScript and preview resources.
Public Members
-
Tk_Item header
Generic stuff that’s the same for all types.
MUST BE FIRST IN STRUCTURE.
-
Tk_Canvas canvas
Canvas containing the EPS item.
-
int canvasX
Translated (by the anchor) canvas coordinates of the EPS item.
-
int canvasY
Translated (by the anchor) canvas coordinates of the EPS item.
-
int lastWidth
Last known dimensions of the EPS item.
This is used to know if the color image preview needs to be resized.
-
int lastHeight
Last known dimensions of the EPS item.
This is used to know if the color image preview needs to be resized.
-
Tcl_Interp *interp
Borrowed canvas interpreter.
-
FILE *psFile
File pointer to Encapsulated PostScript file.
We’ll hold this as long as the EPS item is using this file.
-
size_t psStart
File offset of PostScript code.
-
size_t psLength
Length of PostScript code.
If zero, indicates to read to EOF.
-
size_t wmfStart
File offset of Windows Metafile preview.
-
size_t wmfLength
Length of WMF portion in bytes.
If zero, indicates there is no WMF preview.
-
size_t tiffStart
File offset of TIFF preview.
-
size_t tiffLength
Length of TIFF portion in bytes.
If zero, indicates there is no TIFF preview.
-
char *previewName
Configured preview image name.
-
int previewFormat
Preview format selector.
-
Tk_Image preview
A Tk photo image provided as a preview of the EPS contents.
This image supersedes any EPS preview embedded PostScript preview (EPSI).
-
Tk_Image tmpImage
Used to display the resized preview image.
Created and deleted internally.
-
Pixmap pixmap
Pixmap representing scaled preview.
This isn’t currently used. For now we’re overwriting the Tk image everytime the EPS item is resized. In the future we’ll use our own image routines.
-
Rbc_ColorImage colorImage
The original photo or PostScript preview image converted to a color image.
This is kept around for resampling or resizing the image.
-
int firstLine
First and last line numbers of the PostScript preview.
They are used to skip over the preview when encapsulating PostScript for the canvas item.
-
int lastLine
First and last line numbers of the PostScript preview.
They are used to skip over the preview when encapsulating PostScript for the canvas item.
-
GC fillGC
Graphics context to fill background of image outline if no preview image was present.
-
int llx
Lower left and upper right coordinates of PostScript bounding box, retrieved from file’s “BoundingBox:” field.
-
int lly
Lower left and upper right coordinates of PostScript bounding box, retrieved from file’s “BoundingBox:” field.
-
int urx
Lower left and upper right coordinates of PostScript bounding box, retrieved from file’s “BoundingBox:” field.
-
int ury
Lower left and upper right coordinates of PostScript bounding box, retrieved from file’s “BoundingBox:” field.
-
char *title
Title, retrieved from the file’s “Title:” field, to be displayed over the top of the EPS preview (allocated).
-
Tcl_DString dString
Contains the encapsulate PostScript.
-
double x
Canvas coordinates of the item.
-
double y
Canvas coordinates of the item.
-
Tk_Anchor anchor
Tk anchor locating the item relative to x/y.
-
char *fileName
Name of the encapsulated PostScript file.
If NULL, indicates that no EPS file has be successfully loaded yet.
-
char *reqTitle
Title to be displayed in the EPS item.
Supersedes the title found in the EPS file. If NULL, indicates that the title found in the EPS file should be used.
-
int width
Dimensions of EPS item.
If set to zero, the dimension found in the “%%BoundingBox:” specification from the EPS file are used.
-
int height
Dimensions of EPS item.
If set to zero, the dimension found in the “%%BoundingBox:” specification from the EPS file are used.
-
int showImage
Indicates if the image or the outline rectangle should be displayed.
-
int quick
Nonzero requests quick preview resampling.
-
XColor *fillColor
Fill color of the image outline.
-
Tk_3DBorder border
Outline color.
-
int borderWidth
Preview border thickness in pixels.
-
int relief
Tk preview border relief.
-
Pixmap stipple
Stipple for image fill.
-
ClientData tiffPtr
TIFF decoder handle when TIFF preview support is compiled in.
-
Tk_Item header
-
struct EpsParseInfo
Temporary EPS input parser state.
Public Members
-
size_t maxBytes
Maximum bytes in PostScript section.
Zero means read to EOF.
-
size_t bytesRead
Bytes consumed from PostScript section.
-
int lineNumber
Current input line number.
-
char line[MAX_EPS_LINE_LENGTH + 1]
Current line buffer.
-
char hexTable[256]
Hexadecimal-byte lookup table used for preview decoding.
-
char *nextPtr
Current position within the buffered input.
-
FILE *f
Borrowed open input stream.
-
size_t maxBytes