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;

Shared implementation reference

These groups cover common transactions, lifecycle, mapping helpers and commands. Concrete class contracts and pass batching follow below. Namespaces disambiguate private names without changing C linkage.

Option preparation and commit

group Marker common option transactions

Internal services shared by concrete marker classes.

Functions

static int InitMarkerOptions(Marker *markerPtr)

Initialize the concrete Tk option record while preserving the chosen name.

Chooses monochrome specifications when supplied on a one-bit display. Uses a normalized component resource name and class identity. Temporarily detaches the owned preliminary name so partial Tk cleanup cannot free it. Returns TCL_OK with initialized options, or TCL_ERROR after releasing partial Tk resources and restoring the original name for caller cleanup.

Parameters:
  • markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.

static int ConfigureMarkerOptions(Marker *markerPtr, Tcl_Size objc, Tcl_Obj *const objv[], int creating)

Apply one marker option transaction and commit a rename last.

Requires initialized options. Installs candidate Tk fields, validates a nonempty name not starting with a dash, and rejects rename collisions when not creating. Passes optionMask to the class configuration callback and clears it afterwards. On error restores saved Tk fields and diagnostic; the class owns rollback of derived state. On success commits registry rename and frees saved options. Creation permits replacement, handled by CreateOp.

Parameters:
  • markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.

  • objc – [in] Even number of option/value entries in objv.

  • objv – [in] Borrowed even-length option/value vector, excluding widget and operation names.

  • creating – [in] Nonzero permits creation-time name replacement; zero enforces rename collision checks.

static int GetMarkerTagsFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, char ***tagsPtrPtr)

Parse an optional tag list into one owned allocation.

Initializes output to NULL. NULL/empty input succeeds without storage. Tcl_SplitList owns both the returned pointer array and its strings in one allocation; the caller frees it with ckfree. Returns TCL_ERROR on list errors.

Parameters:
  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objPtr – [in] Borrowed Tcl option value; accepted empty/NULL cases are described above.

  • tagsPtrPtr – [out] Required output initialized to NULL; success transfers one ckfree-compatible tag allocation.

static int GetMarkerStateFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, int *statePtr)

Parse an exact normal, active or disabled marker state.

Borrows the non-NULL object. Writes statePtr only on success; otherwise returns TCL_ERROR with a diagnostic. Does not change drawing or binding state.

Parameters:
  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objPtr – [in] Borrowed Tcl option value; accepted empty/NULL cases are described above.

  • statePtr – [out] Required output receiving the state selector only on success.

static int GetMarkerCoordinatesFromObj(Marker *markerPtr, Tcl_Obj *objPtr, Point2D **worldPtsPtr, Tcl_Size *nWorldPtsPtr)

Stage an owned coordinate array with class-specific point counts.

Initializes outputs to NULL/zero and accepts empty coordinates for every class. Nonempty lists must contain pairs and satisfy the class count limits. Checks allocation size and uses Tcl_AttemptAlloc. Each component is parsed through GetCoordinate, which can evaluate Tcl. Returns TCL_OK and transfers the array, or TCL_ERROR after freeing it. Borrows marker and list storage throughout; does not protect against callback mutation of owners/arguments.

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.

  • worldPtsPtr – [out] Required output initialized to NULL; success transfers an owned coordinate array.

  • nWorldPtsPtr – [out] Required output initialized to zero; receives the number of coordinate pairs.

static void FreeParsedMarkerOptions(Graph *graphPtr, ParsedMarkerOptions *optionsPtr)

Release candidate common resources that have not been transferred.

Frees tag/coordinate allocations and drops candidate axis references, clearing those pointers/counts. Track is borrowed and not released. Accepts a zeroed or partially populated candidate; does not free the candidate record.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • optionsPtr – [inout] Caller-owned common-option candidate; resource transfer and cleanup rules are described above.

static int ParseMarkerOptions(Marker *markerPtr, ParsedMarkerOptions *optionsPtr)

Prepare common tags, coordinates, state, axes and track association.

Zeros the caller-owned candidate, then parses all common fields and acquires axis references. A nonempty track must name an existing trackgraph track, and Y-axis ownership must equal the selected track (including NULL). Returns TCL_OK with staged ownership or TCL_ERROR after candidate cleanup. Coordinate expressions can execute Tcl; live records are not preserved here.

Parameters:
  • markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.

  • optionsPtr – [out] Fresh caller-owned candidate, zeroed here; success requires commit or cleanup.

static void CommitMarkerOptions(Marker *markerPtr, ParsedMarkerOptions *optionsPtr)

Transfer common candidate allocations and axis references to the marker.

Releases old tags, coordinates and axes, moves candidate storage/references and copies borrowed track and state. Clears transferred pointers so candidate cleanup is safe. Does not register a name, map geometry or schedule redraw; the concrete configuration routine owns those remaining steps.

Parameters:
  • markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.

  • optionsPtr – [inout] Caller-owned common-option candidate; resource transfer and cleanup rules are described above.

static int GetMarkerColorFromObj(Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj *objPtr, int allowDefault, XColor **colorPtrPtr)

Resolve an optional color or an allowed default-color sentinel.

Initializes output to NULL. Empty input succeeds; when allowDefault is true, a nonempty prefix of defcolor yields COLOR_DEFAULT. Other spellings acquire a Tk color reference. Returns TCL_OK/TCL_ERROR; callers must distinguish the sentinel from an owned color when releasing the result.

Parameters:
  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • tkwin – [in] Borrowed live Tk window supplying the native resource context.

  • objPtr – [in] Borrowed Tcl option value; accepted empty/NULL cases are described above.

  • allowDefault – [in] Nonzero permits the COLOR_DEFAULT sentinel instead of an owned Tk color.

  • colorPtrPtr – [out] Required output initialized to NULL; receives an owned Tk color or the allowed sentinel.

static int GetColorPairFromObj(Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj *objPtr, int allowDefault, ColorPair *pairPtr)

Stage foreground and background from a list of at most two colors.

Empty input yields a zeroed pair. Parses colors into temporary ownership; failure releases any first color and leaves the output pair unchanged. Success transfers the pair for eventual Rbc_FreeColorPair cleanup. Does not release an existing output pair, so callers must manage replacement explicitly.

Parameters:
  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • tkwin – [in] Borrowed live Tk window supplying the native resource context.

  • objPtr – [in] Borrowed Tcl option value; accepted empty/NULL cases are described above.

  • allowDefault – [in] Nonzero permits the COLOR_DEFAULT sentinel instead of an owned Tk color.

  • pairPtr – [out] Required output receiving candidate colors on success; existing contents are not released.

static int GetCoordinate(Tcl_Interp *interp, const char *expr, double *valuePtr)

Evaluate a coordinate with special elastic endpoint spellings.

Exact Inf, +Inf and -Inf become positive/negative DBL_MAX. Other strings are passed to Tcl_ExprDouble and may execute Tcl. Returns Tcl status and writes valuePtr on success. No general finite-value check is performed here.

Parameters:
  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • expr – [in] Borrowed NUL-terminated coordinate expression, potentially executing Tcl.

  • valuePtr – [out] Required output assigned only on successful conversion.

Record lifetime

group Marker record and resource lifecycle

Internal services shared by concrete marker classes.

Functions

static void ReleaseMarkerTkResources(Marker *markerPtr)

Release one initialized marker before the graph window is lost.

Guards uninitialized/already released records. Calls concrete cleanup before Tk frees option resources, then frees common coordinates/tags, drops axes, frees options/table and sets the release guard. Requires a live graph window. Registry links and record remain for final destruction. Class cleanup can release images or destroy a managed child; this is not just scalar cleanup.

Parameters:
  • markerPtr – [inout] Borrowed concrete marker with the class and lifecycle state required above.

static Marker *CreateMarker(Graph *graphPtr, const char *name, Rbc_Uid classUid)

Allocate an unregistered concrete marker and initialize common state.

Dispatches by interned class identity and returns NULL for an unknown class. Concrete allocation is asserted. Copies the name, borrows graph/class, sets MAP_ITEM and initializes option lifecycle flags. Caller must initialize and configure options, then register the marker or destroy the partial record.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • name – [in] Borrowed NUL-terminated exact marker name.

  • classUid – [in] Interned concrete marker class identifier.

static void DestroyMarker(Marker *markerPtr)

Remove binding and registry/list state and free a concrete marker.

Requires a live marker. Marks backing store dirty for under markers, removes object bindings, and releases initialized resources while the window exists. Handles pre-initialization failure with explicit cleanup instead. Deletes non-NULL hash/list links and frees the record. Bulk teardown or replacement may clear hashPtr first to retain control of the hash entry. Does not itself schedule a graph redraw or make callback-driven registry mutation safe.

Parameters:
  • markerPtr – [inout] Owned marker consumed by destruction; record and resources are invalid afterward.

Mapping helpers and picking

group Marker coordinate mapping and picking

Internal services shared by concrete marker classes.

Functions

static int BoxesDontOverlap(Graph *graphPtr, Extents2D *extsPtr)

Reject disjoint inclusive marker and current plot rectangles.

Requires ordered extents and graph plot bounds, checked with assertions. Touching edges count as overlap. Returns true only for disjoint rectangles; does not clip partial overlaps or map coordinates.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • extsPtr – [in] Borrowed ordered rectangle in screen coordinates.

static double HMap(Graph *graphPtr, Axis *axisPtr, double x)

Map a horizontal marker coordinate, preserving elastic endpoints.

Borrows current axis range and graph geometry. DBL_MAX sentinels select normalized endpoints; descending axes reverse them. Legacy log mapping uses log10 for positives and zero for negatives, then ordinary normalization. Track-owned axes use full world width, otherwise graph hRange/hOffset. Does not clamp normalized values or update layout.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • axisPtr – [in] Borrowed mapped axis providing range, scale, direction and track ownership.

  • x – [in] Horizontal world coordinate, including supported elastic sentinels.

static double VMap(Graph *graphPtr, Axis *axisPtr, double y)

Map a vertical marker coordinate against full track or graph geometry.

Uses the same sentinel, descending and legacy log rules as HMap, with screen-Y reversal. Track ownership selects world bounds even outside a temporary track drawing scope. Visible clipping must not replace this span.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • axisPtr – [in] Borrowed mapped axis providing range, scale, direction and track ownership.

  • y – [in] Vertical world coordinate, including supported elastic sentinels.

static Point2D MapPoint(Graph *graphPtr, Point2D *pointPtr, Axis2D *axesPtr)

Map one borrowed world point through its axes and graph inversion.

Uses marker-specific HMap/VMap, swapping logical axes when inverted. Returns screen coordinates without rounding or remapping graph layout. These helpers intentionally differ from ordinary element mapping.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • pointPtr – [in] Borrowed world-coordinate point to map.

  • axesPtr – [in] Borrowed logical X/Y axis pair.

int Rbc_MarkersUseTrack(Graph *graphPtr, RbcTrack *track, Axis *axis)

Test marker associations independently of display visibility.

Scans the registry, including hidden and coordinate-free markers. NULL track means graph-wide markers; NULL axis matches all markers in that scope. Otherwise compares the marker Y-axis pointer. Borrows all records.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • track – [in] Borrowed track selector, or NULL for graph-wide associations.

  • axis – [in] Borrowed Y-axis selector, or NULL to match every axis in the selected scope.

Marker *Rbc_NearestMarker(Graph *graphPtr, int x, int y, int under)

Pick the first eligible marker in reverse painter order.

Despite its name, this returns the first successful class point test rather than comparing distances. Requires mapped geometry. Filters by layer, nonempty coordinates, hidden flag and STATE_NORMAL; active/disabled states are excluded. Local picks enforce visible track bounds and clipping. Does not apply the associated-element hidden check used by drawing/FindOp. Returns borrowed marker or NULL, without layout refresh or lifetime preservation.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • x – [in] Query x coordinate in graph-window pixels.

  • y – [in] Query y coordinate in graph-window pixels.

  • under – [in] Layer selector: nonzero selects under markers, zero selects overlays.

void Rbc_MarkerFontsChanged(Graph *graphPtr)

Refresh all text-marker layouts after a font change.

Scans the registry including hidden text markers. Resets text style, replaces layout and rotated bounding geometry when text exists, then marks mapping dirty. Borrows graph/marker records; non-text markers are unaffected.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

Registry and commands

group Marker registry and command dispatch

Internal services shared by concrete marker classes.

Functions

static int NameToMarker(Graph *graphPtr, const char *name, Marker **markerPtrPtr)

Resolve an exact marker name to a borrowed registry record.

Returns TCL_OK and writes markerPtrPtr on success. Otherwise returns TCL_ERROR with graph/name diagnostic, leaving output unchanged. Does not search display order, accept patterns or acquire a lifetime reference.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • name – [in] Borrowed NUL-terminated exact marker name.

  • markerPtrPtr – [out] Required output receiving a borrowed registry marker only on success.

static int NamesOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Return display-list names matching any supplied glob pattern.

No patterns returns all listed names. Traverses from first to last and emits each marker at most once; hidden markers remain eligible. Registry entries detached from the display list are not returned. Returns TCL_OK.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static ClientData MakeMarkerTag(Graph *graphPtr, char *tagName)

Intern a binding tag in the graph marker-tag table.

Creates the string-key entry when needed and returns its borrowed key pointer, valid until table destruction. Does not require a named marker to exist or install a binding script.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • tagName – [in] Borrowed tag string, copied by the registry when first interned.

void Rbc_AppendMarkerBindingTags(Graph *graphPtr, Marker *markerPtr, Rbc_List list)

Append name, class and configured tags in binding order.

Borrows graph, marker and destination list. Interns tag identities in the marker-tag table; the list does not own their strings. Does not evaluate Tcl binding scripts or alter marker state.

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.

  • list – [inout] Caller-owned destination list; appends borrowed tag identities without clearing entries.

static int BindOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

List interned marker tags or delegate a binding query/update.

No tag returns registry tag names in hash order, not only tags with scripts. Otherwise interns the tag at objv[3] and passes the remaining arguments to the graph binding table service. Returns its Tcl status.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static int CgetOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Return a marker option through its concrete Tk option table.

Resolves objv[3] as an exact name and objv[4] as an option. Returns TCL_OK with its value or TCL_ERROR from lookup/Tk. Does not configure or redraw.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static int ConfigureOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Query one marker or configure multiple named markers in sequence.

Scans names until the first dash-prefixed argument and validates them before applying options. Zero/one option arguments query the first named marker. Updates re-resolve each name and call ConfigureMarkerOptions independently. A later failure does not roll back earlier markers. Returns a Tcl status; it is not a multi-marker atomic transaction.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static int CreateOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Configure a new marker before replacing any same-named registry entry.

Resolves the class and scans complete option pairs for the last -name prefix; otherwise generates markerN. Creates and initializes the concrete record, applies options and validates the final name before publishing. A duplicate name destroys the old marker while retaining its hash entry. Appends the new record to display order, invalidates under-layer backing when needed and schedules redraw. Returns the configured name or TCL_ERROR with cleanup.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static int DeleteOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Destroy each existing exact name and ignore missing names.

Performs deletions sequentially, clears lookup diagnostics and schedules graph redraw even for no matching names. Returns TCL_OK. Concrete cleanup owns associated resources, which can include a managed child window.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static int GetOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Return the current marker only when the binding context is a marker.

Recognizes only the exact selector current. Checks the common binding context before casting the current item, and verifies a supported marker class. Other selectors or absent/nonmarker items leave an empty result. Returns TCL_OK; does not pick coordinates or resolve ordinary names.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static int RelinkOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Move a marker link before or after an optional display-list reference.

Borrows graph and resolves both exact names before changing display order. Invalid names return TCL_ERROR without unlinking either marker. A reference to the target itself is a successful no-op. Otherwise moves the existing link, invalidates backing storage when the moved marker is an underlay and schedules redraw. No marker ownership or registry entries change.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static int FindOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Return the first visible marker passing a class rectangle test.

Parses enclosed/overlapping and four integer screen coordinates, normalizes corner order and scans first-to-last display order. Filters hidden markers and existing hidden associated elements. Local searches require a visible track intersection; overlapping queries clip the search box to that track, enclosed queries retain the original box. Returns the first name or an empty result. No automatic layout refresh, layer filter or marker-state filter.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static int ExistsOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Report exact registry membership regardless of visibility or list order.

Returns TCL_OK with integer zero/one. Does not require coordinates or current geometry, and does not report an error for a missing name.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

static int TypeOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Return the interned class identity for an existing marker.

Resolves an exact name and copies classUid into the interpreter result. Returns TCL_ERROR on missing name; does not configure or map the marker.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

int Rbc_MarkerOp(Graph *graphPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])

Validate operation and arity before shared marker command dispatch.

Uses the complete widget-command argument vector with the operation at index two. Returns shared-dispatch or handler Tcl status. Does not itself refresh layout or preserve marker records across application callbacks.

Parameters:
  • graphPtr – [inout] Borrowed owning graph; callers keep its required Tk and mapping resources valid.

  • interp – [inout] Borrowed interpreter for diagnostics and results; see Interpreter arguments.

  • objc – [in] Number of borrowed objv entries; see Tcl command arguments.

  • objv – [in] Borrowed command arguments at the positions described above; see Tcl command arguments.

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 lineWidth

Line width.

int capStyle

Cap style.

int joinStyle

Join style.

Rbc_Dashes dashes

Dash list values (max 11).

LineArrow arrow

Arrow placement selector: none, first, last or both.

double arrowShape[3]

Arrow dimensions in pixels: tip-to-neck, tip-to-trailing-corner, and extra half-width beyond half the shaft width.

Point2D firstArrow[PTS_IN_ARROW]

Closed mapped polygon for the first arrowhead.

Point2D lastArrow[PTS_IN_ARROW]

Closed mapped polygon for the last arrowhead.

Point2D firstShaftPoint

Adjusted first shaft endpoint after arrow shortening.

Point2D lastShaftPoint

Adjusted last shaft endpoint after arrow shortening.

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.

Tcl_Size nSegments

segments in the above array.

int xor

Nonzero requests reversible XOR screen drawing.

int xorState

State of the XOR drawing.

Indicates if the marker is currently drawn.

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.

Point2D *screenPts

Owned mapped un-clipped polygon or tessellated arc vertices.

ColorPair outline

Outline foreground/background colors.

ColorPair fill

Fill foreground/background colors.

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.

Tcl_Size nFillPts

points in the above array.

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.

Tcl_Size nOutlinePts

points in the above array.

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.

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.

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.

Point2D anchorPos

Translated anchor point.

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.

Point2D outline[MAX_OUTLINE_POINTS]

Polygon representing the background of the bitmap.

int nOutlinePts

Number of mapped outline vertices.

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.

Point2D anchorPos

Translated anchor point.

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.

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.

Point2D anchorPos

Translated anchor point.

int width

Dimension of bounding box.

int height

Dimension of bounding box.

TextStyle style

Text attributes (font, fg, anchor, etc).

TextLayout *textPtr

Contains information about the layout of the text.

Point2D outline[5]

Mapped rotated background polygon in display pixels.

XColor *fillColor

Configured text-background color, or NULL.

GC fillGC

Owned native text-background GC.

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.

Point2D anchorPos

Translated anchor point.

int width

Current size of the child window.

int height

Current size of the child window.

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.

Public Members

const Segment2D *segments

Borrowed mapped segment array.

Tcl_Size count

Number of segments.

const XColor *color

Borrowed stroke color.

int width

Stroke width in pixels.

int cap

Native cap selector.

int join

Native join selector.

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.

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.

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.

Graph *graphPtr

Borrowed owning graph.

unsigned int flags

Mapping/redraw state bits.

char **tags

Owned binding-tag strings.

int hidden

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.

Point2D *worldPts

Coordinate array to position marker.

Tcl_Size nWorldPts

Number of points in above array.

char *elemName

Element associated with marker.

Axis2D axes

Axis references retained by the marker.

RbcTrack *track

Optional owner; prevents track/axis detachment.

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.

struct ParsedMarkerOptions

Staged marker coordinates, tags and axis references for transactional configuration.

Public Members

char **tags

Staged owned binding-tag array.

Point2D *worldPts

Staged owned world-coordinate array.

Tcl_Size nWorldPts

Number of staged world-coordinate points.

Axis *xAxis

Staged retained X-axis reference.

Axis *yAxis

Staged retained Y-axis reference.

RbcTrack *track

Borrowed validated target track, or NULL.

int state

Validated Tk interaction state.

Implementation selectors

enum LineArrow

Selects the endpoints that receive arrowheads on a line marker.

Values:

enumerator LINE_ARROW_NONE
enumerator LINE_ARROW_FIRST
enumerator LINE_ARROW_LAST
enumerator LINE_ARROW_BOTH