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.

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.

TextStyle titleStyle

Font, color, etc.

for title

Pixmap stipple

Stipple for image fill.

ClientData tiffPtr

TIFF decoder handle when TIFF preview support is compiled in.

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.