Marker C reference
These private entry points borrow the graph. Mapping and drawing assume the caller has prepared the appropriate layout and retained graph lifetime. See Marker lifecycle and drawing for class dispatch, special window behavior and cleanup.
Mapping and output
-
void Rbc_MapMarkers(Graph *graphPtr)
Map pending marker geometry in display-list order.
Skips hidden markers and markers without coordinates. MAP_ALL or MAP_ITEM selects mapping; each class mapper runs in a paired owning-track viewport scope and MAP_ITEM is cleared afterward. Does not draw or update axes.
- Parameters:
graphPtr – Borrowed graph with prepared axes and plot geometry.
-
void Rbc_DrawMarkers(Graph *graphPtr, Drawable drawable, int under)
Draw one marker layer and synchronize embedded child visibility.
Synchronizes windows from both layers even when drawing only one layer. Track drawing preserves painter order with per-track clipping; ordinary graphs may batch compatible adjacent primitives. Window markers manage real children rather than paint them into the supplied drawable.
- Parameters:
graphPtr – Borrowed live graph with current mapped marker geometry.
drawable – Borrowed compatible screen drawable.
under – Layer selector: 1 below elements, 0 above elements.
-
void Rbc_MarkersExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, int under)
Export eligible markers from one layer in display-list order.
Skips missing exporters, absent coordinates, hidden markers and markers associated with an existing hidden element. Non-window track markers use a track viewport and renderer clip; window export follows its own capture path. Does not perform layout or own the export context.
- Parameters:
graphPtr – Borrowed graph with export layout already mapped.
exportPtr – Borrowed initialized export context.
under – Layer selector: 1 below elements, 0 above elements.
Resource and record cleanup
-
void Rbc_ReleaseMarkerTkResources(Graph *graphPtr)
Release marker resources while the graph’s Tk window is still live.
Releases derived resources, common coordinates, tags and axis references before Tk option resources. Already released or uninitialized option records are skipped. Marker records and registry entries remain for later destruction. Window-marker cleanup destroys its current child.
- Parameters:
graphPtr – Borrowed graph with initialized marker registry.
-
void Rbc_DestroyMarkers(Graph *graphPtr)
Destroy all marker records and their registry infrastructure.
Removes bindings and display-list entries, cleans remaining resources through the class-specific path, then destroys marker and tag hash tables and the display list. Release Tk-dependent resources before the window disappears. This whole-registry destructor is not a repeatable resource-release pass.
- Parameters:
graphPtr – Owning graph being torn down.
Internal class interface
The class callbacks are local to rbcGrMarker.c. Their exact signatures and option-table fields are included
directly:
typedef Marker *(MarkerCreateProc)(void);
typedef void(MarkerDrawProc)(Marker *markerPtr, Drawable drawable);
typedef void(MarkerFreeProc)(Graph *graphPtr, Marker *markerPtr);
typedef int(MarkerConfigProc)(Marker *markerPtr);
typedef void(MarkerMapProc)(Marker *markerPtr);
typedef void(MarkerExportProc)(Marker *markerPtr, Rbc_ExportContext *exportPtr);
typedef int(MarkerPointProc)(Marker *markerPtr, Point2D *samplePtr);
typedef int(MarkerRegionProc)(Marker *markerPtr, Extents2D *extsPtr, int enclosed);
/** @brief Immutable dispatch and option descriptor for a marker type. */
typedef struct {
const Tk_OptionSpec *optionSpecs; /**< Borrowed color-display option table. */
const Tk_OptionSpec *monoOptionSpecs; /**< Borrowed monochrome option table. */
MarkerConfigProc *configProc; /**< Rebuild marker resources after option validation. */
MarkerDrawProc *drawProc; /**< Draw mapped geometry into the supplied drawable. */
MarkerFreeProc *freeProc; /**< Release concrete resources before generic marker destruction. */
MarkerMapProc *mapProc; /**< Map world coordinates and update clipping state. */
MarkerPointProc *pointProc; /**< Test the mapped marker against a picking point. */
MarkerRegionProc *regionProc; /**< Test overlap or enclosure with a search rectangle. */
MarkerExportProc *exportProc; /**< Serialize mapped geometry through the document backend. */
} MarkerClass;
Line geometry and lifetime
- group Line marker geometry and lifetime
Internal geometric marker implementation.
Functions
-
static int ComputeArrowHead(Point2D tip, Point2D adjacent, double lineWidth, const double shape[3], Point2D arrow[PTS_IN_ARROW], Point2D *shaftPtr)
Construct a closed arrowhead and shortened shaft endpoint.
Borrows the three shape distances and writes six vertices, including the repeated tip, plus shaftPtr. Uses mapped display coordinates, effective line width and Tk-style neck interpolation. Returns FALSE for an adjacent point within DBL_EPSILON of the tip; outputs must not be used on that path. Allocates nothing and does not clip the resulting head.
- Parameters:
tip – [in] Arrow tip in display coordinates, after marker pixel offsets.
adjacent – [in] Adjacent mapped vertex defining the direction toward the tip.
lineWidth – [in] Effective shaft width in pixels; callers substitute one for a zero-width hairline.
shape – [in] Borrowed three-element array of arrow distances A, B and C in pixels.
arrow – [out] Required PTS_IN_ARROW-element output array, including the repeated closing tip; valid only on TRUE.
shaftPtr – [out] Required shortened shaft endpoint, valid only when TRUE is returned.
-
static int PointInsideExtents(const Point2D *pointPtr, const Extents2D *extsPtr)
Test inclusive containment of a display point.
Borrows both inputs; returns TRUE on the rectangle boundary as well as inside it. No coordinate mapping, tolerance expansion or mutation.
- Parameters:
pointPtr – [in] Borrowed point in display coordinates.
extsPtr – [in] Borrowed ordered query rectangle in display coordinates.
-
static void MapLineMarker(Marker *markerPtr)
Replace clipped shaft segments and endpoint arrow geometry.
Clears prior segments and arrow flags, then maps at least two world points with pixel offsets. Heads are constructed only when their original tips lie inside plot extents; shaft endpoints are shortened before edge clipping. Owns the replacement segment allocation. Size/allocation failure leaves an empty clipped marker without a Tcl error. A visible head alone makes the marker non-clipped even when no shaft segment survives.
- Parameters:
markerPtr – [inout] Borrowed line marker whose owned mapping caches are replaced in the current axis/track viewport.
-
static int PointInLineMarker(Marker *markerPtr, Point2D *samplePtr)
Pick mapped arrow polygons or clipped shaft segments.
Borrows mapped caches. Tests five unique vertices per enabled head, then segment distance using the graph halo. Does not expand that halo by shaft width or refresh layout.
- Parameters:
markerPtr – [in] Borrowed line marker with current mapped caches; no ownership is transferred.
samplePtr – [in] Borrowed query point in display coordinates; mapping is not refreshed here.
-
static int RegionInLineMarker(Marker *markerPtr, Extents2D *extsPtr, int enclosed)
Test original mapped line edges and cached arrowheads against a region.
Requires two world points. Enclosure requires every original mapped point (including pixel offsets) and every enabled head inside the rectangle. Overlap accepts any original edge or cached head intersection. Unlike point picking, shaft tests do not use the plot-clipped segment cache or graph halo.
- Parameters:
markerPtr – [in] Borrowed line marker with current mapped caches; no ownership is transferred.
extsPtr – [in] Borrowed ordered query rectangle in display coordinates.
enclosed – [in] Nonzero requests complete enclosure; zero requests overlap.
-
static int ParseArrowShape(LineMarker *lmPtr, double shape[3])
Parse three screen distances into caller-owned shape storage.
Borrows arrowShapeObjPtr and the graph window. Returns TCL_ERROR with a diagnostic for a malformed list, wrong count or invalid screen distance. Earlier output entries may be written before failure. No additional positivity or relative-size check is performed here.
- Parameters:
lmPtr – [in] Borrowed line marker supplying the arrow-shape Tcl object, interpreter and window.
shape – [out] Required three-double output array; earlier entries may be assigned before TCL_ERROR.
-
static int ConfigureLineMarker(Marker *markerPtr)
Prepare and commit line style, common options and a private GC.
Parses common options, arrow shape, caps, joins, dashes and nonnegative width/offset before committing derived state. Error paths release staged resources; the outer option transaction restores Tk-managed values. Erases the recorded old XOR shaft and heads before replacing geometry/GC, then maps/draws graph-wide XOR immediately or schedules redraw (including track transitions). Erasure uses old caches and GC regardless of new options. Under-layer scheduled drawing invalidates the backing store.
- Parameters:
markerPtr – [inout] Borrowed line marker with candidate Tk option fields installed by the outer saved-options transaction.
-
static void FreeLineMarker(Graph *graphPtr, Marker *markerPtr)
Release line-owned segment storage and private graphics context.
Borrows graph and marker; does not free the record or common options. Erases recorded immediate XOR shaft and heads while a drawable and GC remain, including head-only geometry. Clears released pointers and segment count. Common lifecycle code owns subsequent record destruction.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
markerPtr – [inout] Borrowed line marker whose class-owned resources are released; the common record is retained.
-
static Marker *CreateLineMarker(void)
Allocate a zeroed line record and install initial class/style values.
Uses the RBC allocation wrapper, sets the class, disables XOR and selects butt caps/miter joins. Returns the embedded common marker; the caller owns option initialization, registry insertion and eventual destruction.
-
struct LineMarker
Line-specific option state, owned segment cache and fixed arrow arrays.
Common Marker is embedded first. Tk options own Tcl representations and colors; class cleanup owns the private GC and segment allocation. Arrow arrays have five unique vertices plus a repeated tip. xorState records an immediate graph-wide image, not the current requested xor option alone.
Public Members
-
Marker core
Common Marker prefix; must remain first.
-
Tcl_Obj *capObjPtr
Tk option-managed Tcl representation for cap; released with the owning option state.
-
Tcl_Obj *dashesObjPtr
Tk option-managed Tcl representation for dashes; released with the owning option state.
-
Tcl_Obj *dashOffsetObjPtr
Tk option-managed Tcl representation for dash offset; released with the owning option state.
-
Tcl_Obj *joinObjPtr
Tk option-managed Tcl representation for join; released with the owning option state.
-
Tcl_Obj *lineWidthObjPtr
Tk option-managed Tcl representation for line width; released with the owning option state.
-
Tcl_Obj *arrowShapeObjPtr
Tk option-managed Tcl representation for arrow shape; released with the owning option state.
-
XColor *fillColor
Off-dash background color, or NULL for unpainted gaps.
-
XColor *outlineColor
Foreground stroke and arrowhead color.
-
int capStyle
Cap style.
-
int joinStyle
Join style.
-
Rbc_Dashes dashes
Dash list values (max 11).
-
double arrowShape[3]
Arrow dimensions in pixels: tip-to-neck, tip-to-trailing-corner, and extra half-width beyond half the shaft width.
-
int hasFirstArrow
Nonzero when firstArrow contains drawable geometry.
-
int hasLastArrow
Nonzero when lastArrow contains drawable geometry.
-
GC gc
Private graphic context.
-
Segment2D *segments
Malloc’ed array of points.
Represents individual line segments (2 points per segment) comprising the mapped line. The segments may not necessarily be connected after clipping.
-
int xor
Nonzero requests reversible XOR screen drawing.
-
int xorState
State of the XOR drawing.
Indicates if the marker is currently drawn.
-
Marker core
-
static int ComputeArrowHead(Point2D tip, Point2D adjacent, double lineWidth, const double shape[3], Point2D arrow[PTS_IN_ARROW], Point2D *shaftPtr)
Polygon and arc geometry and ownership
- group Polygon and arc geometry and ownership
Internal geometric marker implementation.
Functions
-
static void MapPolygonMarker(Marker *markerPtr)
Replace full mapped vertices and independently clipped fill/outline caches.
Frees old geometry first and requires at least three world vertices. Applies axes and pixel offsets to screenPts. Fill clipping is attempted only with a fill foreground; outlines require foreground and positive width, and include the closing edge. Each allocation is size-checked and fallible without a Tcl error. A partial cache may survive another cache allocation failure; clipped becomes FALSE when drawable geometry remains.
- Parameters:
markerPtr – [inout] Borrowed polygon marker whose owned mapping caches are replaced in the current axis/track viewport.
-
static int PointInPolygonMarker(Marker *markerPtr, Point2D *samplePtr)
Pick the interior of the full mapped polygon.
Requires screenPts and at least three world vertices. Borrows that cache and tests polygon interior irrespective of fill visibility or line width. Does not use clipped fill geometry, graph halo or refresh mapping.
- Parameters:
markerPtr – [in] Borrowed polygon marker with current mapped caches; no ownership is transferred.
samplePtr – [in] Borrowed query point in display coordinates; mapping is not refreshed here.
-
static int RegionInPolygonMarker(Marker *markerPtr, Extents2D *extsPtr, int enclosed)
Test the full mapped polygon for enclosure or overlap.
Requires screenPts and at least three world vertices, then delegates to the region/polygon helper. Uses original mapped vertices rather than clipped fill/outline caches and ignores stroke thickness.
- Parameters:
markerPtr – [in] Borrowed polygon marker with current mapped caches; no ownership is transferred.
extsPtr – [in] Borrowed ordered query rectangle in display coordinates.
enclosed – [in] Nonzero requests complete enclosure; zero requests overlap.
-
static int ConfigurePolygonMarker(Marker *markerPtr)
Prepare and commit shared polygon/arc appearance and common options.
Arc angles must be finite. Stages common resources, styles and owned color pairs, builds a private outline GC and shared fill GC, then erases a recorded immediate outline before commit. Errors release staged resources; the outer Tk option transaction restores option fields. Immediate XOR is restricted to graph-wide outline-only cases without pending axis reset; open arcs qualify as outline-only. Otherwise marks for mapping and redraw, invalidating under-layer backing storage. Fill GC construction does not apply the outline GC XOR function.
- Parameters:
markerPtr – [inout] Borrowed polygon or arc marker with candidate Tk option fields installed by the outer saved-options transaction.
-
static void FreePolygonMarker(Graph *graphPtr, Marker *markerPtr)
Release polygon/arc caches, color pairs and graphics contexts.
Erases a recorded immediate outline when its drawable/resources remain. Releases the private outline GC, shared fill GC and three owned geometry arrays, clearing pointers/counts as implemented. Frees manually owned color pairs; common option/record cleanup retains responsibility for the stipple, world points, tags and the record itself.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
markerPtr – [inout] Borrowed polygon or arc marker whose class-owned resources are released; the common record is retained.
-
static Marker *CreatePolygonMarker(void)
Allocate polygon storage with its class and initial line style.
Returns the embedded common marker, with butt caps/miter joins and other fields zeroed. Common creation configures options and registers the record. The same allocation layout is reused by arc markers.
-
static void MapArcMarker(Marker *markerPtr)
Map an ellipse box and build bounded flattened geometry caches.
Clears old caches, requires two corners and nonzero extent, and rejects nonfinite/zero mapped radii. Normalizes start modulo 360 and clamps signed extent to one turn. Stores the exact ellipse separately; flattened points target 0.15-pixel chord error with at most 8192 steps. Closure follows open, chord or pieslice style. Visibility is conservative from the ellipse box plus outline margin, independent of successful cache allocation. Fallible allocations do not set Tcl errors; picking caches can be absent even when the exact curve remains eligible for renderer drawing.
- Parameters:
markerPtr – [inout] Borrowed arc marker whose owned mapping caches are replaced in the current axis/track viewport.
-
static int PointInArcMarker(Marker *markerPtr, Point2D *samplePtr)
Pick clipped arc fill or outline caches.
Requires a two-corner world box. Tests the clipped fill polygon first, then outline segments with tolerance max(graph halo, half line width). Borrows caches; does not analytically test the ellipse or rebuild missing geometry.
- Parameters:
markerPtr – [in] Borrowed arc marker with current mapped caches; no ownership is transferred.
samplePtr – [in] Borrowed query point in display coordinates; mapping is not refreshed here.
-
static int RegionInArcMarker(Marker *markerPtr, Extents2D *extsPtr, int enclosed)
Test flattened arc geometry for enclosure or overlap.
Requires mapped vertices and at least one nonempty fill/outline cache. Enclosure tests every untrimmed flattened vertex; overlap tests clipped fill and outline segments. Neither branch expands the rectangle by stroke width or provides an exact analytic curve test.
- Parameters:
markerPtr – [in] Borrowed arc marker with current mapped caches; no ownership is transferred.
extsPtr – [in] Borrowed ordered query rectangle in display coordinates.
enclosed – [in] Nonzero requests complete enclosure; zero requests overlap.
-
static Marker *CreateArcMarker(void)
Allocate polygon storage and substitute the arc callback class.
Delegates allocation/default style to CreatePolygonMarker, then changes only classPtr when non-NULL. Common initialization installs arc options; configuration and cleanup remain the polygon class implementations.
-
struct PolygonMarker
Shared polygon/arc storage with separately owned mapped caches.
screenPts retains full mapped geometry; fillPts and outlinePts are clipped output caches. Polygon vertex count is core.nWorldPts; arc count is nArcPts while its world input remains two corners. arc retains exact curve geometry for curved renderers. Color pairs and GCs are class-owned; Tk options own their Tcl representations and stipple reference.
Public Members
-
Marker core
Common Marker prefix; must remain first.
-
Tcl_Obj *capObjPtr
Tk option-managed Tcl representation for cap; released with the owning option state.
-
Tcl_Obj *dashesObjPtr
Tk option-managed Tcl representation for dashes; released with the owning option state.
-
Tcl_Obj *fillObjPtr
Tk option-managed Tcl representation for fill; released with the owning option state.
-
Tcl_Obj *joinObjPtr
Tk option-managed Tcl representation for join; released with the owning option state.
-
Tcl_Obj *lineWidthObjPtr
Tk option-managed Tcl representation for line width; released with the owning option state.
-
Tcl_Obj *outlineObjPtr
Tk option-managed Tcl representation for outline; released with the owning option state.
-
Pixmap stipple
Stipple pattern to fill the polygon.
-
int lineWidth
Width of polygon outline.
-
int capStyle
Native stroke cap selector.
-
int joinStyle
Native stroke join selector.
-
Rbc_Dashes dashes
List of dash values.
Indicates how draw the dashed line. If no dash values are provided, or the first value is zero, then the line is drawn solid.
-
GC outlineGC
Graphics context to draw the outline of the polygon.
-
GC fillGC
Graphics context to draw the filled polygon.
-
Point2D *fillPts
Malloc’ed array of points used to draw the filled polygon.
These points may form a degenerate polygon after clipping.
-
Segment2D *outlinePts
Malloc’ed array of points.
Represents individual line segments (2 points per segment) comprising the outline of the polygon. The segments may not necessarily be closed or connected after clipping.
-
int xor
Nonzero requests reversible XOR screen drawing.
-
int xorState
State of the XOR drawing.
Indicates if the marker is visible. We have to drawn it again to erase it.
-
double start
Arc start angle in degrees.
-
double extent
Signed arc sweep in degrees.
-
int arcStyle
Open arc, chord or pie-slice closure selector.
-
Tcl_Size nArcPts
Number of tessellated arc vertices.
-
Rbc_RenderArcGeometry arc
Unclipped ellipse for curved renderers.
-
Marker core
-
static void MapPolygonMarker(Marker *markerPtr)
Geometric renderer dispatch
- group Geometric marker renderer dispatch
Internal geometric marker implementation.
Functions
-
static int DrawRenderedMarkerSegments(Graph *graphPtr, Drawable drawable, const Segment2D *segments, Tcl_Size count, const XColor *color, const XColor *gapColor, int width, const Rbc_Dashes *dashes, int cap, int join, int xorMode)
Submit independent clipped segments to the selected renderer.
Borrows geometry/style. XOR requests or a missing render context return FALSE so the caller can use its native GC path. Otherwise sets caps/joins, submits all segments, ends the context and returns TRUE. Width is at least one pixel; TRUE denotes dispatch, not a pixel-visibility assertion.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
segments – [in] Borrowed array of mapped, independently clipped segments; retained only for this call.
count – [in] Nonnegative number of readable segment entries.
color – [in] Borrowed foreground color passed to renderer selection.
gapColor – [in] Borrowed dash-gap background color, or NULL for transparent gaps.
width – [in] Requested stroke width in pixels, clamped to at least one.
dashes – [in] Borrowed dash description, including its offset.
cap – [in] Native cap-style selector for the stroke context.
join – [in] Native join-style selector for the stroke context.
xorMode – [in] Nonzero forces FALSE without drawing so the caller can use its XOR GC.
-
static void DrawNativeLineSegments(LineMarker *lmPtr, Drawable drawable)
Draw shaft segments with legacy native endpoint conversion.
Borrows the line GC/cache. Without heads, delegates directly to the screen segment renderer. With heads, rounds endpoints in bounded 128-segment stack batches before dispatch. Never modifies mapped doubles used by picking/export and never draws the heads themselves.
- Parameters:
lmPtr – [in] Borrowed line marker with current mapped geometry and valid graphics context.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
-
static void EraseLineMarkerXor(LineMarker *lmPtr, Drawable drawable)
Erase all recorded immediate line geometry with its original native GC.
Borrows the old shaft/head caches and GC, independent of newly installed Tk options such as xor, arrow and outline. Redraws shaft and enabled heads when a drawable and GC remain, including head-only markers, then clears xorState. Does not map geometry, select a renderer or schedule graph redraw.
- Parameters:
lmPtr – [inout] Borrowed line marker retaining old XOR geometry/GC; xorState is cleared even if erasure cannot draw.
drawable – [in] Original screen destination, or None to clear bookkeeping without drawing.
-
static int DrawRenderedArrowHead(Graph *graphPtr, Drawable drawable, const Point2D *arrow, XColor *color)
Submit temporary half-pixel-shifted arrow fill vertices.
Copies the five unique vertices and shifts both coordinates by 0.5 to align area boundaries with the rendered shaft. Returns the area helper status for fallback selection. Original geometry remains unchanged for native drawing, picking and document export.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
arrow – [in] Borrowed mapped arrow vertices; only the five unique vertices are read.
color – [in] Borrowed foreground color passed to renderer selection.
-
static void DrawLineMarker(Marker *markerPtr, Drawable drawable)
Draw mapped shafts followed by first and last arrowheads.
Uses renderer strokes/fills where possible, otherwise native GC services; XOR always uses native paths. An absent non-XOR outline may be recovered from the GC foreground for screen drawing. Toggles xorState after any drawing only for graph-wide XOR markers, not track-owned markers.
- Parameters:
markerPtr – [inout] Borrowed marker of the concrete class described above; common record ownership stays with the caller.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
-
static void ArrowHeadExport(LineMarker *lmPtr, Rbc_ExportContext *exportPtr, Point2D *arrow)
Export the five unique arrow vertices using the explicit outline color.
Borrows the mapped arrow and export context. An empty outline suppresses head output rather than recovering the screen GC color. Creates and ends a fill-render context; does not shorten or remap the shaft.
- Parameters:
lmPtr – [in] Borrowed line marker with current mapped geometry and valid graphics context.
exportPtr – [inout] Borrowed document output context; geometry must already match its export layout.
arrow – [in] Borrowed mapped arrow vertices; only the five unique vertices are read.
-
static void LineMarkerExport(Marker *markerPtr, Rbc_ExportContext *exportPtr)
Export clipped shaft segments and mapped arrowheads.
Borrows caches at the current export layout. Sets cap/join/dash state and dash-gap color for the shaft, then exports enabled heads. Uses the original double geometry without native rounding or screen half-pixel shifts. Export does not toggle XOR state.
- Parameters:
markerPtr – [in] Borrowed marker of the concrete class described above; common record ownership stays with the caller.
exportPtr – [inout] Borrowed document output context; geometry must already match its export layout.
-
static void DrawPolygonMarker(Marker *markerPtr, Drawable drawable)
Draw clipped polygon fill followed by clipped outline segments.
Borrows fill/outline caches and colors. Tries selected-renderer area and stroke operations, with native GC fallback (forced for XOR). Fill needs at least three points; outline needs positive width and a foreground. Does not update immediate-XOR bookkeeping.
- Parameters:
markerPtr – [in] Borrowed marker of the concrete class described above; common record ownership stays with the caller.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
-
static void PolygonMarkerExport(Marker *markerPtr, Rbc_ExportContext *exportPtr)
Export polygon fill and outline from clipped caches.
Borrows the export context and current mapped caches. Fill preserves foreground/background/stipple; outline preserves width, cap/join and dash gap color. Creates and ends each renderer context independently, without remapping or altering XOR state.
- Parameters:
markerPtr – [in] Borrowed marker of the concrete class described above; common record ownership stays with the caller.
exportPtr – [inout] Borrowed document output context; geometry must already match its export layout.
-
static void StrokeArcMarker(PolygonMarker *pmPtr, Drawable drawable, Rbc_ExportContext *exportPtr)
Stroke the mapped ellipse through curved or native renderer services.
Skips zero extent, empty outline or nonpositive width. An export context selects document output; otherwise uses the screen renderer unless XOR is requested. Native fallback receives clipped flattened segments as well as the exact ellipse. Renderer arc handling owns continuous-path dash/join behavior; this helper does not join vertices itself.
- Parameters:
pmPtr – [in] Borrowed polygon/arc record with current mapped geometry and drawing resources.
drawable – [in] Screen destination for native fallback; normal export callers pass None.
exportPtr – [inout] Borrowed export context, or NULL to select screen output.
-
static void DrawImmediatePolygonOutline(PolygonMarker *pmPtr, Drawable drawable)
Draw or erase a polygon/arc outline using existing native state.
Borrows the old outline GC and geometry. Polygon outlines submit cached segments. Arcs temporarily force the XOR flag while calling StrokeArcMarker to bypass Cairo, then restore it. The caller owns xorState bookkeeping and must retain valid old resources until the call completes.
- Parameters:
pmPtr – [inout] Borrowed polygon/arc retaining the old outline GC and geometry; arc xor is temporarily set and restored.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
-
static void DrawArcMarker(Marker *markerPtr, Drawable drawable)
Fill a closed mapped arc and then stroke its outline.
Skips zero extent. Open arcs never fill. Selected-renderer fill contexts consume the exact ellipse; native fallback also receives the clipped fill polygon. Stroke dispatch is shared with export/immediate outline paths. Does not change immediate-XOR bookkeeping.
- Parameters:
markerPtr – [in] Borrowed marker of the concrete class described above; common record ownership stays with the caller.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
-
static void ArcMarkerExport(Marker *markerPtr, Rbc_ExportContext *exportPtr)
Export the exact mapped ellipse with its closure and appearance.
Skips zero extent and omits fill for open arcs. Borrows geometry/export context, emits a fill if requested and calls the shared arc stroke path. Does not export the flattened picking polygon as the primary curve or modify screen XOR state.
- Parameters:
markerPtr – [in] Borrowed marker of the concrete class described above; common record ownership stays with the caller.
exportPtr – [inout] Borrowed document output context; geometry must already match its export layout.
-
static int DrawRenderedMarkerSegments(Graph *graphPtr, Drawable drawable, const Segment2D *segments, Tcl_Size count, const XColor *color, const XColor *gapColor, int width, const Rbc_Dashes *dashes, int cap, int join, int xorMode)
Bitmap marker resources and presentation
- group Bitmap marker resources and presentation
Internal concrete marker implementation.
Functions
-
static void FreeMappedBitmapResources(Graph *graphPtr, BitmapMarker *bmPtr)
Release only owned mapped bitmap and mask pixmaps.
Source Tk bitmaps are borrowed here. A destination mask may alias the destination bitmap but must not also own that same pixmap. Frees owned handles and clears both handles/ownership flags; dimensions and outline count are left to the caller.
- Parameters:
graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.
bmPtr – [inout] Borrowed bitmap marker whose owned mapped caches are released.
-
static Pixmap AndBitmapMasks(Tk_Window tkwin, Pixmap mask1, Pixmap mask2, int width, int height)
Allocate a depth-one intersection of two equally sized masks.
Borrows both masks and window/display. Copies mask1 and applies GXand with mask2 through a temporary GC. Returns None on pixmap/GC allocation failure; otherwise the caller must Tk_FreePixmap the result. Does not validate input dimensions or alter the source masks.
- Parameters:
tkwin – [in] Borrowed live Tk window supplying the native resource context.
mask1 – [in] Borrowed depth-one mask matching width and height.
mask2 – [in] Borrowed second depth-one mask with identical dimensions.
width – [in] Positive mask width in pixels; input storage must match.
height – [in] Positive mask height in pixels; input storage must match.
-
static int ConfigureBitmapMarker(Marker *markerPtr)
Stage bitmap options and GCs before invalidating mapped resources.
Parses common resources and checks explicit mask dimensions against the source bitmap. Normalizes rotation separately from the configured value. After validation, commits common state, releases old mapped pixmaps and shared GCs, installs replacements and schedules remapping/redraw. Error paths release staged resources; the outer Tk transaction owns rollback.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static void MapBitmapMarker(Marker *markerPtr)
Build visible bitmap/mask transformations and background geometry.
Requires a source bitmap and caller-supplied coordinates. One point uses source dimensions and anchor; two corners define an inclusive scaled box. Applies offsets, rejects offscreen boxes, and transforms only the visible subregion. With transparent background, combines an explicit mask with source bits or aliases the source bitmap. Tracks generated pixmap ownership separately. Stores the background outline in absolute display coordinates for drawing and picking without further anchor translation.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static int PointInBitmapMarker(Marker *markerPtr, Point2D *samplePtr)
Test a mapped bitmap rectangle or rotated bounding polygon.
Returns false without a source bitmap. Unrotated bounds are half-open. Rotated tests use the absolute mapped outline directly. Does not test individual bitmap bits or transparency mask pixels.
- Parameters:
markerPtr – [in] Borrowed concrete marker with current mapped geometry.
samplePtr – [in] Borrowed query point in screen coordinates; cached geometry must be current.
-
static int RegionInBitmapMarker(Marker *markerPtr, Extents2D *extsPtr, int enclosed)
Test bitmap bounds against an enclosed/overlapping region.
Requires world coordinates; uses cached dimensions for unrotated tests. Rotated tests use the absolute mapped outline directly. No pixel-mask or alpha test is made.
- Parameters:
markerPtr – [in] Borrowed concrete marker with current mapped geometry.
extsPtr – [in] Borrowed ordered rectangle in screen coordinates.
enclosed – [in] Nonzero requests full enclosure; zero requests overlap.
-
static void DrawBitmapMarker(Marker *markerPtr, Drawable drawable)
Present the mapped bitmap through screen raster services.
Skips missing/empty destination bitmaps. Borrows mapped handles and GCs. Arbitrary rotations with opaque background and no explicit mask use the background polygon plus bitmap-as-mask workaround. Integer placement is performed here; renderer services own native clip/origin handling.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
drawable – [in] Borrowed compatible screen destination drawable.
-
static void BitmapMarkerExport(Marker *markerPtr, Rbc_ExportContext *exportPtr)
Export mapped foreground and background masks or polygon.
Borrows export context and mapped resources. Explicit masks restrict the background and intersect foreground bits; transparent backgrounds use the mapper-selected effective mask. An unmasked opaque background uses the mapped polygon. Frees any temporary foreground intersection and ends the output context on both empty and normal paths.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
exportPtr – [inout] Borrowed export context receiving output and backend error state.
-
static void FreeBitmapMarker(Graph *graphPtr, Marker *markerPtr)
Release bitmap-derived caches and shared drawing GCs.
Clears mapped handles/ownership, both GCs, destination dimensions and outline count. Tk option cleanup owns source bitmap/mask and colors; common cleanup owns the record. Does not itself schedule redraw.
- Parameters:
graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static Marker *CreateBitmapMarker(void)
Allocate a zeroed bitmap record and select its callback class.
Returns the embedded common marker. Common creation supplies options, registry membership and later destruction; no bitmap is acquired here.
-
struct BitmapMarker
Bitmap source references and explicitly owned mapped pixmaps.
Tk options own srcBitmap/srcMask and configured colors. Destination handles may alias source handles or each other; ownership flags govern release. outline is an absolute mapped background polygon, not anchor-local geometry.
Public Members
-
Marker core
Common Marker prefix; must remain first.
-
Pixmap srcBitmap
Original bitmap.
May be further scaled or rotated.
-
Pixmap srcMask
User-specified transparency mask.
-
double rotate
Requested rotation of the bitmap.
-
double theta
Normalized rotation (0..360 degrees).
-
Tk_Anchor anchor
If only one X-Y coordinate is given, indicates how to translate the given marker position.
Otherwise, if there are two X-Y coordinates, then this value is ignored.
-
XColor *outlineColor
Foreground color.
-
XColor *fillColor
Background color.
-
GC gc
Private graphic context.
-
GC fillGC
Shared graphic context.
-
Pixmap destBitmap
Bitmap to be drawn.
-
Pixmap destMask
Final scaled/rotated clip mask.
-
int destBitmapOwned
Nonzero when destBitmap must be freed separately from srcBitmap.
-
int destMaskOwned
Nonzero when destMask must be freed separately from srcMask.
-
int destWidth
Dimensions of the final bitmap.
-
int destHeight
Dimensions of the final bitmap.
-
int nOutlinePts
Number of mapped outline vertices.
-
Marker core
-
static void FreeMappedBitmapResources(Graph *graphPtr, BitmapMarker *bmPtr)
Image marker resources and presentation
- group Image marker resources and presentation
Internal concrete marker implementation.
Functions
-
static void ImageChangedProc(ClientData clientData, int x, int y, int width, int height, int imageWidth, int imageHeight)
Refresh the owned photo copy after a Tk image change.
Borrows the marker callback data and ignores the changed rectangle/size arguments. Looks up the configured name and replaces srcImage with a fresh photo copy, or NULL if no photo remains. Frees the old copy and marks mapping and backing storage dirty before scheduling redraw; no script evaluation is performed directly here.
- Parameters:
clientData – [inout] Borrowed marker registered as callback data; concrete type is specified above.
x – [in] Changed image rectangle metadata supplied by Tk; ignored by this callback.
y – [in] Changed image rectangle metadata supplied by Tk; ignored by this callback.
width – [in] Changed image rectangle metadata supplied by Tk; ignored by this callback.
height – [in] Changed image rectangle metadata supplied by Tk; ignored by this callback.
imageWidth – [in] Image width supplied by Tk; ignored by this callback.
imageHeight – [in] Image height supplied by Tk; ignored by this callback.
-
static int ConfigureImageMarker(Marker *markerPtr)
Acquire replacement Tk image resources before releasing the old ones.
Stages common options, Tk image instance/change callback, optional photo copy and GC. After validation, commits common resources and releases old pixmap, temporary image, photo copy, Tk instance and GC. Installs new state, clears dimensions and schedules remap/redraw. Error paths free staged resources; the named source image itself is not owned by the marker.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static void MapImageMarker(Marker *markerPtr)
Map image placement and maintain a temporary scaled photo.
Skips absent/deleted source instances. Non-photo images use the first mapped point plus offsets as top-left, without anchor adjustment or scaling. Photos use anchor/natural size or a two-corner inclusive box; only the visible scaled subregion is generated. Returning to natural size destroys the temporary photo after clearing its field. Creation failure returns without a Tcl status; callers must not assume mapping is atomic.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static int PointInImageMarker(Marker *markerPtr, Point2D *samplePtr)
Test the half-open cached image rectangle.
Borrows placement/dimensions and does not refresh mapping or inspect source existence, transparency or individual pixels. Caller filtering and current mapped state remain prerequisites.
- Parameters:
markerPtr – [in] Borrowed concrete marker with current mapped geometry.
samplePtr – [in] Borrowed query point in screen coordinates; cached geometry must be current.
-
static int RegionInImageMarker(Marker *markerPtr, Extents2D *extsPtr, int enclosed)
Test enclosure or overlap of cached image bounds.
Requires at least one world point. Uses anchor plus width/height, with strict overlap excluding edge-only contact. Does not inspect alpha or source-image availability and does not remap.
- Parameters:
markerPtr – [in] Borrowed concrete marker with current mapped geometry.
extsPtr – [in] Borrowed ordered rectangle in screen coordinates.
enclosed – [in] Nonzero requests full enclosure; zero requests overlap.
-
static void DrawImageMarker(Marker *markerPtr, Drawable drawable)
Draw the temporary/source Tk image or cached pixmap.
Skips absent/deleted source instances. Prefers tmpImage when there is no pixmap, otherwise submits the pixmap with its GC and rectangle. Borrows all resources and ends the screen raster context after dispatch.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
drawable – [in] Borrowed compatible screen destination drawable.
-
static void ImageMarkerExport(Marker *markerPtr, Rbc_ExportContext *exportPtr)
Export the current temporary/source image through output services.
Skips absent/deleted source instances. Resolves the selected image name as a photo for photo output, otherwise delegates to generic Tk image output. Borrows resources and ends the context on all paths; format-specific capture/conversion remains in the renderer.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
exportPtr – [inout] Borrowed export context receiving output and backend error state.
-
static void FreeImageMarker(Graph *graphPtr, Marker *markerPtr)
Release owned image caches and the source image instance.
Frees pixmap, GC, Tk instance, temporary image and photo copy, then clears dimensions. Clears tmpImage before temporary-image destruction. Freeing the source instance does not delete the user-owned named image; common cleanup releases option objects and the record.
- Parameters:
graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static Marker *CreateImageMarker(void)
Allocate a zeroed image record and set its class.
Returns the embedded common marker for common option initialization and registry insertion. Acquires no image resources itself.
-
struct ImageMarker
Source image instance and owned photo/scaled-image caches.
The application owns the named source image. The marker owns its Tk instance, source color-image copy, temporary scaled image and drawing resources. Cached dimensions describe current mapped presentation.
Public Members
-
Marker core
Common Marker prefix; must remain first.
-
Tcl_Obj *imageObjPtr
Tk option-managed Tcl representation for image; released with the owning option state.
-
Tk_Image tkImage
Tk image to be displayed.
-
Tk_Anchor anchor
Indicates how to translate the given marker position.
-
int width
Dimensions of the image.
-
int height
Dimensions of the image.
-
Tk_Image tmpImage
Owned resized color-image cache, or NULL.
-
Pixmap pixmap
Pixmap containing the scaled image.
-
Rbc_ColorImage srcImage
Owned source color-image copy, or NULL.
-
GC gc
Owned native image-copy GC.
-
Marker core
-
static void ImageChangedProc(ClientData clientData, int x, int y, int width, int height, int imageWidth, int imageHeight)
Text marker layout and presentation
- group Text marker layout and presentation
Internal concrete marker implementation.
Functions
-
static int ConfigureTextMarker(Marker *markerPtr)
Stage text layout, padding, shadow and drawing resources.
Parses common resources, padding and shadow, normalizes rotation, and builds a new layout/rotated outline using the proposed Tk-managed style. After validation commits the layout, GCs and manually owned shadow color while saved Tk options retain old resources. Error paths free staged resources. Marks mapping and under-layer backing dirty and schedules redraw.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static void MapTextMarker(Marker *markerPtr)
Place the cached rotated text rectangle using its marker anchor.
Requires a non-NULL string and caller-supplied coordinates. Maps the first point, applies marker anchor and pixel offsets, tests plot overlap, and stores anchorPos. Does not rebuild text layout or allocate a bitmap.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static int PointInTextMarker(Marker *markerPtr, Point2D *samplePtr)
Pick the text bounding rectangle or rotated outline.
Returns false for a NULL string. Rotated outline coordinates are local to anchorPos and are translated for polygon testing. Unrotated bounds are half-open. Tests bounds, not glyph coverage or shadow pixels independently.
- Parameters:
markerPtr – [in] Borrowed concrete marker with current mapped geometry.
samplePtr – [in] Borrowed query point in screen coordinates; cached geometry must be current.
-
static int RegionInTextMarker(Marker *markerPtr, Extents2D *extsPtr, int enclosed)
Test cached text bounds for enclosure or overlap.
Requires coordinates. Uses four translated rotated-outline vertices or the unrotated rectangle; does not refresh layout or inspect glyph coverage. Unrotated overlap excludes edge-only contact.
- Parameters:
markerPtr – [in] Borrowed concrete marker with current mapped geometry.
extsPtr – [in] Borrowed ordered rectangle in screen coordinates.
enclosed – [in] Nonzero requests full enclosure; zero requests overlap.
-
static int DrawRenderedTextBackground(Graph *graphPtr, Drawable drawable, TextMarker *tmPtr)
Try Cairo background fill with native-sized integer vertices.
Returns FALSE for other renderers. Translates the four local outline vertices by anchorPos and truncates to integer coordinates before area submission. Returns the render helper status for native fallback; does not modify cached geometry.
- Parameters:
graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.
drawable – [in] Borrowed compatible screen destination drawable.
tmPtr – [in] Borrowed text marker with current layout and mapped background outline.
-
static void DrawTextMarker(Marker *markerPtr, Drawable drawable)
Draw optional background and cached text layout.
Returns for a NULL string. Background tries Cairo then native services; text uses the screen-text renderer when foreground exists, with integer placement. Borrows layout/style and does not alter their ownership.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
drawable – [in] Borrowed compatible screen destination drawable.
-
static void TextMarkerExport(Marker *markerPtr, Rbc_ExportContext *exportPtr)
Export the text string/style and optional rotated background.
Returns through an ended context for a NULL string. Translates background vertices without screen integer truncation, then delegates text to document output using the string and style rather than the cached screen layout.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
exportPtr – [inout] Borrowed export context receiving output and backend error state.
-
static void FreeTextMarker(Graph *graphPtr, Marker *markerPtr)
Release derived text resources without freeing Tk option values.
Frees shared text/background GCs, manually owned shadow color and layout. Clears their fields, dimensions and outline. Tk option cleanup owns font, foreground/background colors and string; common cleanup owns the record.
- Parameters:
graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static Marker *CreateTextMarker(void)
Allocate text storage with an internally north-west text style.
Initializes the text style, class and four-pixel padding. The internal style anchor differs from the marker anchor applied during mapping. Common creation installs configured options and takes record ownership.
-
struct TextMarker
Text options, derived layout and anchor-local rotated outline.
Tk options own font/string/foreground/background; the class owns layout, GCs and shadow color. The marker anchor is distinct from the internal north-west text-style anchor. outline is translated by anchorPos at use.
Public Members
-
Marker core
Common Marker prefix; must remain first.
-
Tcl_Obj *padXObjPtr
Tk option-managed Tcl representation for pad x; released with the owning option state.
-
Tcl_Obj *padYObjPtr
Tk option-managed Tcl representation for pad y; released with the owning option state.
-
Tcl_Obj *shadowObjPtr
Tk option-managed Tcl representation for shadow; released with the owning option state.
-
char *string
Text string to be display.
The string make contain newlines.
-
Tk_Anchor anchor
Indicates how to translate the given marker position.
-
int width
Dimension of bounding box.
-
int height
Dimension of bounding box.
-
TextLayout *textPtr
Contains information about the layout of the text.
-
XColor *fillColor
Configured text-background color, or NULL.
-
GC fillGC
Owned native text-background GC.
-
Marker core
-
static int ConfigureTextMarker(Marker *markerPtr)
Window marker geometry management and callbacks
- group Window marker geometry management and callbacks
Internal concrete marker implementation.
Functions
-
static int GetWindowMarkerDimension(Marker *markerPtr, Tcl_Obj *objPtr, int explicitlyChanged, int *valuePtr)
Parse a child dimension while distinguishing defaults from explicit zero.
Writes zero for a NULL object. Otherwise parses pixels and rejects negative values or explicitly changed zero, leaving output unchanged on error. Internal zero means use the child requested size. Returns Tcl status and diagnostic; caller supplies the option-change flag.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
objPtr – [in] Borrowed Tcl option value; accepted empty/NULL cases are described above.
explicitlyChanged – [in] Nonzero rejects an explicitly supplied zero dimension.
valuePtr – [out] Required output assigned only on successful conversion.
-
static void ReleaseWindowMarkerChild(WindowMarker *wmPtr, int destroyWindow)
Detach the embedded child and optionally destroy it.
Returns if no child. Clears the marker token before removing its event handler and geometry management. Destroys the child when requested, else unmaps it for reuse; resets dimensions afterward. The marker record must remain alive across the Tk operations. Does not free the record.
- Parameters:
wmPtr – [inout] Borrowed window marker kept alive while its child is detached.
destroyWindow – [in] Nonzero destroys the detached child; zero unmaps it for reuse.
-
static int ConfigureWindowMarker(Marker *markerPtr)
Validate dimensions and direct-child ownership before transferring geometry.
Stages common options and dimensions and resolves the requested window. Only direct children of the graph are accepted. On success commits common state, detaches/unmaps the previous child without destroying it, and sets the new token before registering events and geometry management. Schedules remap/redraw; errors release staged common state. Geometry transfer invokes Tk services, so successful validation is not a blanket callback-safety guarantee.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static void MapWindowMarker(Marker *markerPtr)
Map child requested/explicit dimensions, anchor and pixel offsets.
Returns without a child. Uses positive explicit dimensions in preference to Tk requested size, stores rectangle and tests plot overlap. Does not move/map the actual child or introduce plot/track clipping containers.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static int PointInWindowMarker(Marker *markerPtr, Point2D *samplePtr)
Test the half-open cached child rectangle.
Borrows geometry only; does not check the child token, mapping state or refresh its requested dimensions. Outer marker filtering remains separate.
- Parameters:
markerPtr – [in] Borrowed concrete marker with current mapped geometry.
samplePtr – [in] Borrowed query point in screen coordinates; cached geometry must be current.
-
static int RegionInWindowMarker(Marker *markerPtr, Extents2D *extsPtr, int enclosed)
Test enclosure or strict overlap of cached child bounds.
Requires coordinates and uses anchor plus width/height. Does not inspect child visibility, update geometry or test actual window contents.
- Parameters:
markerPtr – [in] Borrowed concrete marker with current mapped geometry.
extsPtr – [in] Borrowed ordered rectangle in screen coordinates.
enclosed – [in] Nonzero requests full enclosure; zero requests overlap.
-
static void DrawWindowMarker(Marker *markerPtr, Drawable drawable)
Synchronize the real child position/size and map it if necessary.
Returns without a child. Moves/resizes only when cached geometry differs, then maps if needed. Ignores drawable: this changes a real Tk child, not a pixmap. Caller must have checked visibility and prepared mapped geometry.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
drawable – [in] Unused drawable; this callback moves/maps the real Tk child.
-
static void SyncWindowMarkers(Graph *graphPtr)
Synchronize visibility of all real child markers across both layers.
Walks display order and filters missing coordinates, hidden/clipped state, collapsed tracks and associated hidden elements. Maps/moves visible children and unmaps others. Partial overlap keeps the full child, clipped by its graph parent only. Required even when under-layer backing is reused.
- Parameters:
graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.
-
static void WindowMarkerExport(Marker *markerPtr, Rbc_ExportContext *exportPtr)
Delegate capture of an existing mapped child to the exporter.
Creates/ends an output context and emits only if the child exists and is mapped. Uses marker placement; does not map a hidden child or replace it with an independent widget rendering. Capture policy belongs to the backend.
- Parameters:
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
exportPtr – [inout] Borrowed export context receiving output and backend error state.
-
static void FreeWindowMarker(Graph *graphPtr, Marker *markerPtr)
Destroy the currently embedded child and clear marker placement.
Delegates detachment/destruction to ReleaseWindowMarkerChild, then clears anchorPos. Unlike image markers, deleting this marker destroys its owned child. Common lifecycle code frees the marker record/options.
- Parameters:
graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.
markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.
-
static Marker *CreateWindowMarker(void)
Allocate a zeroed window marker and set its class.
Returns the embedded common record; common configuration later resolves and acquires geometry management of a child. No child is created here.
-
static void ChildEventProc(ClientData clientData, XEvent *eventPtr)
Clear a destroyed child token while retaining the marker record.
Handles DestroyNotify only. Clears token/dimensions, marks mapping dirty and schedules redraw if the graph window still exists. Other structure events are ignored; this callback does not delete the marker.
- Parameters:
clientData – [inout] Borrowed marker registered as callback data; concrete type is specified above.
eventPtr – [in] Borrowed child structure event; only DestroyNotify is handled.
-
static void ChildGeometryProc(ClientData clientData, Tk_Window tkwin)
Copy newly requested child dimensions into automatic-size fields.
Updates only dimensions whose explicit request is zero. When either changes, marks mapping dirty and schedules redraw for a live graph window so anchor and visibility are recomputed. Invalidates under-layer backing storage as needed. Fully overridden or unchanged requests need no redraw.
- Parameters:
clientData – [inout] Borrowed marker registered as callback data; concrete type is specified above.
tkwin – [in] Borrowed managed child window supplied by Tk geometry management.
-
static void ChildCustodyProc(ClientData clientData, Tk_Window tkwin)
Delete the marker when another manager takes its child.
Removes the event handler and clears the matching child token before DestroyMarker, preserving the window for its new manager. Schedules graph redraw afterward. The marker pointer is invalid after destruction; no marker field may be read again by this callback.
- Parameters:
clientData – [inout] Borrowed marker registered as callback data; concrete type is specified above.
tkwin – [in] Borrowed managed child window supplied by Tk geometry management.
-
struct WindowMarker
Embedded child token and requested/mapped geometry.
Geometry management and structure notifications retain this record as client data. Zero requested dimensions mean automatic size. Deleting the marker destroys its current child; replacing the child only detaches it.
Public Members
-
Marker core
Common Marker prefix; must remain first.
-
Tcl_Obj *reqHeightObjPtr
Tk option-managed Tcl representation for req height; released with the owning option state.
-
Tcl_Obj *reqWidthObjPtr
Tk option-managed Tcl representation for req width; released with the owning option state.
-
char *pathName
Name of child widget to be displayed.
-
Tk_Window tkwin
Window to display.
-
int reqWidth
If non-zero, this overrides the size requested by the child widget.
-
int reqHeight
If non-zero, this overrides the size requested by the child widget.
-
Tk_Anchor anchor
Indicates how to translate the given marker position.
-
int width
Current size of the child window.
-
int height
Current size of the child window.
-
Marker core
-
static int GetWindowMarkerDimension(Marker *markerPtr, Tcl_Obj *objPtr, int explicitlyChanged, int *valuePtr)
Pass batching and renderer dispatch
- group Marker pass batching and renderer dispatch
Internal style predicates, synchronous runs and clipping.
Functions
-
static void DrawTextMarkerRun(void *clientData, Drawable drawable, Tcl_Size count)
Draw an eligible Windows text run synchronously in array order.
Borrows the marker-pointer array for count entries and delegates each to DrawTextMarker. Renderer services own the shared native target. Retains no pointers and neither filters eligibility nor merges text layouts.
- Parameters:
clientData – [in] Borrowed array of count eligible TextMarker pointers; records and layouts remain live through the callback.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
count – [in] Nonnegative number of eligible text-marker pointers in clientData.
-
static int CanBatchWinTextMarker(TextMarker *tmPtr)
Test eligibility for shared-target Windows text drawing.
Requires a string, foreground and layout, with no background GC, disabled/ emphasis/active text-style state or visible shadow. Does not require equal fonts/colors across the run and does not reject Cairo: glyph drawing stays native. Outer traversal owns layer and visibility filtering.
- Parameters:
tmPtr – [in] Borrowed concrete marker to inspect, or NULL (returns FALSE); no visibility filtering or mutation.
-
static int CanBatchWinLineMarker(LineMarker *lmPtr)
Test eligibility for the narrow Windows native line batch.
Requires nonempty segments/GC and explicit outline, native rendering, no XOR or arrows, solid dashes, exactly one-pixel width, butt caps and miter joins. Dash-gap fill is irrelevant for these solid strokes. Does not test layer, hidden state or associated-element visibility.
- Parameters:
lmPtr – [in] Borrowed concrete marker to inspect, or NULL (returns FALSE); no visibility filtering or mutation.
-
static int CanBatchWinPolygonOutlineMarker(PolygonMarker *pmPtr)
Test native outline-only polygon batch eligibility.
Requires mapped segments/GC, explicit foreground, one-pixel solid butt/ miter stroke, non-Cairo and non-XOR. Rejects a drawable fill to preserve fill-before-outline ordering. Outer traversal filters marker visibility.
- Parameters:
pmPtr – [in] Borrowed concrete marker to inspect, or NULL (returns FALSE); no visibility filtering or mutation.
-
static int CanBatchWinPolygonFillMarker(PolygonMarker *pmPtr)
Test native solid fill-only polygon batch eligibility.
Requires GC, foreground and 3..INT_MAX fill points; rejects Cairo, XOR, stipple, background color and any drawable outline. This narrow predicate makes the subsequent style comparison valid; it does not filter layers.
- Parameters:
pmPtr – [in] Borrowed concrete marker to inspect, or NULL (returns FALSE); no visibility filtering or mutation.
-
static int CanBatchWinBitmapMarker(BitmapMarker *bmPtr)
Test opaque unmasked native bitmap batch eligibility.
Requires destination bitmap, dimensions, GC and both colors; rejects Cairo and destination masks. Accepts right-angle rotations within DBL_EPSILON after modulo reduction. Arbitrary rotations retain the individual background-polygon/mask path.
- Parameters:
bmPtr – [in] Borrowed concrete marker to inspect, or NULL (returns FALSE); no visibility filtering or mutation.
-
static int SameWinLineMarkerStyle(LineMarker *aPtr, LineMarker *bPtr)
Compare foreground pixels of already eligible native line markers.
Returns FALSE for NULL records. Eligibility must have established valid colors and identical width/cap/join/dash/XOR characteristics. Borrows inputs and does not compare geometry or GC identity.
- Parameters:
aPtr – [in] Borrowed already-eligible marker, or NULL (returns FALSE); eligibility must be checked before comparison.
bPtr – [in] Borrowed already-eligible marker, or NULL (returns FALSE); eligibility must be checked before comparison.
-
static int SameWinPolygonOutlineStyle(PolygonMarker *aPtr, PolygonMarker *bPtr)
Compare foreground pixels of eligible polygon outlines.
Returns FALSE for NULL records. Caller must first establish outline-only batch eligibility, including non-NULL foreground and fixed stroke style.
- Parameters:
aPtr – [in] Borrowed already-eligible marker, or NULL (returns FALSE); eligibility must be checked before comparison.
bPtr – [in] Borrowed already-eligible marker, or NULL (returns FALSE); eligibility must be checked before comparison.
-
static int SameWinPolygonFillStyle(PolygonMarker *aPtr, PolygonMarker *bPtr)
Compare foreground pixels of eligible solid polygon fills.
Returns FALSE for NULL records. Requires prior fill-only eligibility; stipple, background, outline and XOR differences have already been excluded.
- Parameters:
aPtr – [in] Borrowed already-eligible marker, or NULL (returns FALSE); eligibility must be checked before comparison.
bPtr – [in] Borrowed already-eligible marker, or NULL (returns FALSE); eligibility must be checked before comparison.
-
static int SameWinBitmapStyle(BitmapMarker *aPtr, BitmapMarker *bPtr)
Compare the shared source and GC colors of eligible bitmap markers.
Returns FALSE for NULL records. Otherwise compares destination bitmap identity, dimensions and native GC foreground/background pixels. Placement is deliberately excluded and collected separately. Eligibility guarantees the borrowed GC and bitmap state are valid.
- Parameters:
aPtr – [in] Borrowed already-eligible marker, or NULL (returns FALSE); eligibility must be checked before comparison.
bPtr – [in] Borrowed already-eligible marker, or NULL (returns FALSE); eligibility must be checked before comparison.
-
static void FlushWinLineMarkerBatch(Graph *graphPtr, Drawable drawable, LineMarker **stylePtrPtr, Segment2D *segments, Tcl_Size *nSegmentsPtr)
Draw pending native line segments and reset batch bookkeeping.
Borrows the array, representative marker and its GC. Emits only for a non-NULL style and positive count, then clears style/count even when empty. Does not free the pass-owned array or marker resources.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
stylePtrPtr – [inout] Required batch representative slot, possibly containing NULL; reset to NULL after submission.
segments – [in] Borrowed array of mapped, independently clipped segments; retained only for this call.
nSegmentsPtr – [inout] Required pending segment count matching the array; reset to zero, without freeing storage.
-
static void FlushWinPolygonMarkerBatch(Graph *graphPtr, Drawable drawable, PolygonMarker **stylePtrPtr, Segment2D *segments, Tcl_Size *nSegmentsPtr)
Draw pending polygon-outline segments and reset the batch.
Borrows representative outline GC and segment storage. Opens/ends a native segment context only for a nonempty styled batch. Clears style/count; allocation ownership remains with the outer drawing pass.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
stylePtrPtr – [inout] Required batch representative slot, possibly containing NULL; reset to NULL after submission.
segments – [in] Borrowed array of mapped, independently clipped segments; retained only for this call.
nSegmentsPtr – [inout] Required pending segment count matching the array; reset to zero, without freeing storage.
-
static void DrawWinPolygonFillMarkers(Graph *graphPtr, Drawable drawable, PolygonMarker *stylePtr, PolygonMarker **markers, Tcl_Size nMarkers)
Draw a compatible fill run with one native polygon batch context.
Borrows markers/style and returns for missing/empty input. Computes maximum point count for renderer scratch capacity, then submits each polygon in array order. Does not merge polygon geometry or assume equal vertex counts.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
stylePtr – [in] Borrowed eligible representative supplying the shared fill GC, or NULL for no output.
markers – [in] Borrowed array of live, eligible marker pointers in painter order; records are not released.
nMarkers – [in] Number of readable marker pointers; nonpositive values produce no output.
-
static void FlushWinPolygonFillBatch(Graph *graphPtr, Drawable drawable, PolygonMarker **stylePtrPtr, PolygonMarker **markers, Tcl_Size *nMarkersPtr)
Submit pending polygon fills and clear style/count.
Delegates nonempty styled runs to DrawWinPolygonFillMarkers. Borrows the marker-pointer array; neither destroys markers nor frees batch storage.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
stylePtrPtr – [inout] Required batch representative slot, possibly containing NULL; reset to NULL after submission.
markers – [in] Borrowed array of live, eligible marker pointers in painter order; records are not released.
nMarkersPtr – [inout] Required nonnegative pending marker count matching the array; reset to zero after synchronous drawing.
-
static void FlushWinTextMarkerBatch(Graph *graphPtr, Drawable drawable, TextMarker **markers, Tcl_Size *nMarkersPtr)
Submit a synchronous shared-target text run and clear its count.
Borrows the marker-pointer array and dispatches through Rbc_RenderScreenRun and DrawTextMarkerRun. Empty batches do nothing. Array ownership remains with Rbc_DrawMarkers; this helper does not free it.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
markers – [in] Borrowed array of live, eligible marker pointers in painter order; records are not released.
nMarkersPtr – [inout] Required nonnegative pending marker count matching the array; reset to zero after synchronous drawing.
-
static void FlushWinBitmapMarkerBatch(Graph *graphPtr, Drawable drawable, BitmapMarker **stylePtrPtr, Rbc_RenderPosition *positions, Tcl_Size *nPositionsPtr)
Draw compatible bitmap placements and reset batch bookkeeping.
Borrows the representative bitmap/GC/dimensions and position array. Sends a nonempty run to renderer bitmap services, then clears style/count. Does not acquire or release source bitmap ownership.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
stylePtrPtr – [inout] Required batch representative slot, possibly containing NULL; reset to NULL after submission.
positions – [in] Borrowed array of integer destination positions, matching the pending count.
nPositionsPtr – [inout] Required nonnegative pending position count; reset to zero without freeing the array.
-
static int GetMarkerStroke(Marker *markerPtr, MarkerStroke *stroke)
Describe a Cairo-compatible line or polygon-outline stroke.
Writes a borrowed segment/color view for non-XOR solid lines without arrows, or polygons without drawable fills. Requires the appropriate GC and returns TRUE only for nonempty geometry and explicit color. Width is normalized to at least one. Output may be partially written on FALSE and must not be used then. Arcs and non-Cairo graphs are excluded.
- Parameters:
markerPtr – [in] Borrowed marker to inspect; only eligible line and polygon classes produce a descriptor.
stroke – [out] Required descriptor receiving borrowed geometry/colors on TRUE; contents are unusable on FALSE.
-
static int SameMarkerStroke(const MarkerStroke *a, const MarkerStroke *b)
Compare renderer stroke state independently of marker identity.
Requires two successful stroke descriptors. Compares width, cap, join and RGB channels, not color-pointer identity or segment storage. A match allows context reuse, not path merging or a single combined alpha operation.
- Parameters:
a – [in] Borrowed successful GetMarkerStroke descriptor; its color must remain live.
b – [in] Borrowed second successful GetMarkerStroke descriptor; its color must remain live.
-
static int MarkersNeedRenderTarget(Graph *graphPtr, int under)
Conservatively decide whether a Windows Cairo pass needs a target.
Returns FALSE for non-Cairo graphs. Scans the requested layer, skipping hidden/clipped/coordinate-free markers, windows, background-free text and XOR line/polygon markers. Does not repeat associated-element hidden checks, so TRUE can overestimate actual drawing. Owns no render target itself.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
under – [in] Exact drawUnder selector: one for the under layer, zero for overlays.
-
static void DrawTrackMarkers(Graph *graphPtr, Drawable drawable, int under)
Draw one trackgraph marker layer in painter order with per-track clipping.
Skips windows and ineligible visibility/layer/element associations. Graph-wide markers draw directly. Track-owned markers use a lazily created reusable screen clip context with bounded rectangles and paired viewport entry/exit around class drawing. An unavailable clip drawable skips that marker. Ends each clip scope and the reusable context; no ordinary-graph batch arrays or cross-marker stroke context are used.
- Parameters:
graphPtr – [inout] Borrowed owning graph with live drawing resources and the required current viewport.
drawable – [in] Borrowed compatible screen destination; no ownership is transferred.
under – [in] Exact drawUnder selector: one for the under layer, zero for overlays.
-
struct MarkerStroke
Borrowed Cairo stroke view valid while its marker caches remain alive.
Holds no ownership or lifetime references. Style equality permits context reuse only; each marker must still be submitted as its own stroke.
-
static void DrawTextMarkerRun(void *clientData, Drawable drawable, Tcl_Size count)
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 MarkerClass
Immutable dispatch and option descriptor for a marker type.
Public Members
-
const Tk_OptionSpec *optionSpecs
Borrowed color-display option table.
-
const Tk_OptionSpec *monoOptionSpecs
Borrowed monochrome option table.
-
MarkerConfigProc *configProc
Rebuild marker resources after option validation.
-
MarkerDrawProc *drawProc
Draw mapped geometry into the supplied drawable.
-
MarkerFreeProc *freeProc
Release concrete resources before generic marker destruction.
-
MarkerMapProc *mapProc
Map world coordinates and update clipping state.
-
MarkerPointProc *pointProc
Test the mapped marker against a picking point.
-
MarkerRegionProc *regionProc
Test overlap or enclosure with a search rectangle.
-
MarkerExportProc *exportProc
Serialize mapped geometry through the document backend.
-
const Tk_OptionSpec *optionSpecs
-
struct MarkerOpSpec
Typed command dispatch entry with shared argument validation metadata.
Public Members
-
Rbc_OpSpecHeader header
Operation name, total argument bounds and usage suffix.
-
RbcGrMarkerOp *proc
Typed command handler for this operation.
-
Rbc_OpSpecHeader header
-
struct MarkerStruct
Common marker prefix: graph registry identity, coordinates, axis references and option lifecycle.
Public Members
-
char *name
Identifier for marker in list.
-
Rbc_Uid classUid
Type of marker.
-
unsigned int flags
Mapping/redraw state bits.
-
char **tags
Owned binding-tag strings.
If non-zero, don’t display the marker.
-
Tcl_HashEntry *hashPtr
Borrowed registry entry; cleared when detached.
-
Rbc_ChainLink *linkPtr
Link in the owning graph marker display chain.
-
Tcl_Size nWorldPts
Number of points in above array.
-
char *elemName
Element associated with marker.
-
Tcl_Obj *trackObjPtr
Tk option-managed Tcl representation for track; released with the owning option state.
-
int drawUnder
If non-zero, draw the marker underneath any elements.
This can be a performance penalty because the graph must be redraw entirely each time the marker is redrawn.
-
int clipped
Indicates if the marker is totally clipped by the plotting area.
-
int xOffset
Pixel offset from graph position.
-
int yOffset
Pixel offset from graph position.
-
MarkerClass *classPtr
Borrowed immutable descriptor for the concrete marker type.
-
int state
Tk interaction state controlling event eligibility.
-
Tcl_Obj *bindTagsObjPtr
Tk option-managed Tcl representation for bind tags; released with the owning option state.
-
Tcl_Obj *coordsObjPtr
Tk option-managed Tcl representation for coords; released with the owning option state.
-
Tcl_Obj *mapXObjPtr
Tk option-managed Tcl representation for map x; released with the owning option state.
-
Tcl_Obj *mapYObjPtr
Tk option-managed Tcl representation for map y; released with the owning option state.
-
Tcl_Obj *stateObjPtr
Tk option-managed Tcl representation for state; released with the owning option state.
-
Tcl_Obj *xOffsetObjPtr
Tk option-managed Tcl representation for x offset; released with the owning option state.
-
Tcl_Obj *yOffsetObjPtr
Tk option-managed Tcl representation for y offset; released with the owning option state.
-
int optionMask
Change mask from the current option transaction.
-
Tk_OptionTable optionTable
Tk option table for this component configuration lifecycle.
-
int optionsInitialized
Nonzero after Tk option initialization.
-
int tkResourcesReleased
Nonzero after guarded Tk-resource release.
-
char *name
-
struct ParsedMarkerOptions
Staged marker coordinates, tags and axis references for transactional configuration.