Crosshair C reference

These private helpers borrow graph state. See Crosshair state and presentation before changing erase/update/present ordering.

Lifecycle and background changes

int Rbc_CreateCrosshairs(Graph *graphPtr)

Create the graph-owned named crosshair component.

Initializes resource name crosshairs and class Crosshairs, then prepares derived geometry and XOR drawing state. Returns TCL_OK on success; failure destroys the partial record and leaves crosshairs NULL with a diagnostic.

Parameters:
  • graphPtr – [inout] Graph with no existing crosshair record and a live Tk configuration context.

void Rbc_ConfigureCrosshairs(Graph *graphPtr)

Refresh crosshair drawing state after a graph background change.

Reuses validated option values and requests GC reconstruction through ConfigureCrosshairs. That helper erases old pixels before replacing the GC and redraws eligible requested hairs. This void interface discards the conversion status and does not schedule a full graph redraw.

Parameters:
  • graphPtr – [inout] Live graph; a NULL crosshair record is a no-op.

void Rbc_DestroyCrosshairs(Graph *graphPtr)

Release crosshair options and native resources during graph teardown.

Detaches the record before freeing Tk options, option table, private GC and allocation. Does not erase an overlay on a continuing window; callers own visual transitions before teardown.

Parameters:
  • graphPtr – [inout] Owning graph with a live Tk cleanup context; NULL crosshairs is allowed.

Direct overlay control

void Rbc_EnableCrosshairs(Graph *graphPtr)

Restore XOR crosshairs when requested and drawable on screen.

Honors hidden state and draws only when the window is mapped, hairs are not already visible, and the hotspot is inside the plot. Does not change -hide.

Parameters:
  • graphPtr – Live graph with initialized crosshairs and current segments.

void Rbc_DisableCrosshairs(Graph *graphPtr)

Temporarily erase currently visible XOR crosshairs.

When not hidden, erases on a mapped window using the current GC and segments. Does not change -hide. Call before overwriting geometry in direct redraws.

Parameters:
  • graphPtr – Live graph with initialized crosshairs and their old geometry.

void Rbc_UpdateCrosshairs(Graph *graphPtr)

Update segment lengths from current graph plot bounds.

Leaves hotspot coordinates unchanged. Does not erase, draw or change visible state. Call only when old geometry is no longer needed to erase old pixels.

Parameters:
  • graphPtr – Graph with initialized crosshairs and prepared plot geometry.

Buffered presentation

int Rbc_CrosshairsNeedFullRedraw(Graph *graphPtr)

Test whether a plot-only frame copy could leave crosshair pixels behind.

Call before updating segments. The caller must request margin drawing as well as a full copy so the entire source frame contains initialized pixels.

Parameters:
  • graphPtr – Borrowed graph with old crosshair geometry still intact.

Returns:

Nonzero for relevant wide strokes or visible old endpoints outside the current plot; zero when no full-frame copy is needed by this test.

void Rbc_PresentGraphWithCrosshairs(Graph *graphPtr, Drawable drawable)

Compose crosshairs into a completed temporary frame and present once.

Updates segments, adds requested visible hairs, copies the frame to the window, then commits visible state. DRAW_MARGINS selects full-frame copying; otherwise only the plot is copied. No Tcl callbacks or event processing may intervene between geometry update and state commit. Do not separately erase or enable window hairs around this call. Does not free the pixmap.

Parameters:
  • graphPtr – Live mapped graph with current layout and copy GC.

  • drawable – Temporary compatible pixmap containing a completed frame without crosshairs; never the window, reusable backing store or export target.

Implementation helpers

group Crosshair configuration and motion helpers

Private component helpers; not installed C API entry points.

Functions

static void TurnOffHairs(Tk_Window tkwin, Crosshairs *chPtr)

Erase currently visible XOR segments using their original GC.

Requires a live Tk window and crosshair record. Only draws when the window is mapped and visible is true, then clears visible. On an unmapped window it leaves visible unchanged. Does not consult or modify requested hidden state. Endpoints/GC must still describe the pixels being erased. No Tcl callbacks.

Parameters:
  • tkwin – [in] Live window holding the original XOR pixels.

  • chPtr – [inout] Prepared crosshair record with original GC/endpoints; visible is cleared only after mapped erasure.

static void TurnOnHairs(Graph *graphPtr, Crosshairs *chPtr)

Draw requested XOR geometry when the hotspot lies inside the plot.

Borrows a live graph/window and prepared crosshair GC/segments. Draws only when mapped, not already visible, and PointInGraph accepts the hotspot; then sets visible. Does not test hidden: callers decide requested visibility. Does not remap endpoints or schedule an idle redraw. No Tcl callbacks.

Parameters:
  • graphPtr – [in] Borrowed live graph providing window and plot bounds.

  • chPtr – [inout] Prepared GC, hotspot and segments; visible may become true, hidden is not inspected.

static int GetCrosshairPositionFromObj(Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj *objPtr, Point2D *pointPtr)

Parse an optional @x,y widget-pixel position.

NULL or empty input succeeds with INT_MIN in both output coordinates, an out-of-plot sentinel. Otherwise splits at the first comma and converts both parts through Tk_GetPixelsFromObj using temporary retained Tcl objects. Accepts Tk screen-distance syntax, storing integer pixel results as doubles.

Returns TCL_OK only after both coordinates convert. On TCL_ERROR leaves pointPtr unchanged, releases both temporary objects, and reports syntax or conversion context in interp. Does not move crosshairs or invoke Tcl code.

Parameters:
  • interp – [in] Borrowed interpreter receiving diagnostics; see Interpreter arguments.

  • tkwin – [in] Borrowed Tk window used to convert screen distances.

  • objPtr – [in] Borrowed position object; NULL or empty selects the off-plot sentinel.

  • pointPtr – [out] Required result storage; receives integer pixel coordinates as doubles, unchanged on failure.

static int ConfigureCrosshairs(Graph *graphPtr, Crosshairs *chPtr, int mask)

Validate derived crosshair state before changing XOR pixels.

Requires a live graph/window and Tk-parsed option fields. Stages dash, width and hotspot conversions selected by mask; TCL_ERROR leaves active GC/geometry and displayed pixels unchanged, while caller restores Tk options separately. Windows exact position-only changes delegate to MoveCrosshairs.

Otherwise prepares a replacement XOR GC, erases with old GC/endpoints, commits new state, rebuilds both segments, and draws when requested and eligible. Releases replaced GC; returns TCL_OK without scheduling a graph redraw. No Tcl callback is evaluated between erase and replacement.

Parameters:
  • graphPtr – [in] Borrowed live graph supplying background, bounds and Tk context.

  • chPtr – [inout] Initialized crosshairs with candidate Tk fields; active geometry/GC change only after conversion succeeds.

  • mask – [in] HAIRS_*_CHANGED bits; exactly HAIRS_POSITION_CHANGED selects Windows motion batching.

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

Return one component option value.

The typed dispatcher has validated argument count. Borrows the graph-owned component and its option table, returning Tk option errors unchanged. This query does not configure resources or schedule drawing.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected crosshair record; enclosing dispatch owns lifetime protection.

  • interp – [in] Borrowed interpreter receiving diagnostics; see Interpreter arguments.

  • objc – [in] Validated count of four; option name is objv[3].

  • objv – [in] Borrowed full widget-command vector; see Tcl command arguments.

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

Query or transactionally configure crosshair options.

Three or four arguments return Tk option metadata. Updates stage Tk fields and invoke ConfigureCrosshairs to validate derived state before visual replacement. Failure restores saved options and the diagnostic; success frees saved values. Presentation is handled by the helper rather than scheduling a whole-graph redraw here.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected crosshair record; enclosing dispatch owns lifetime protection.

  • interp – [in] Borrowed interpreter receiving diagnostics; see Interpreter arguments.

  • objc – [in] Command count; operation is at index two, optional arguments start at index three.

  • objv – [in] Borrowed full widget-command vector; see Tcl command arguments.

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

Request crosshairs to be shown.

When previously hidden, attempts drawing with TurnOnHairs before clearing hidden. Actual visibility still depends on window mapping and hotspot location. Repeated on is a no-op even if requested hairs are not currently visible; display/motion paths own later presentation.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected crosshair record; enclosing dispatch owns lifetime protection.

  • interp – [in] Unused by this visibility handler.

  • objc – [in] Validated count of three; unused by this visibility handler.

  • objv – [in] Unused validated command vector.

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

Request crosshairs to be hidden.

When previously requested on, erases through TurnOffHairs before setting hidden. Repeated off is a no-op. The low-level helper may leave actual visibility unchanged on an unmapped window; requested state is not a direct pixel-state assertion.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected crosshair record; enclosing dispatch owns lifetime protection.

  • interp – [in] Unused by this visibility handler.

  • objc – [in] Validated count of three; unused by this visibility handler.

  • objv – [in] Unused validated command vector.

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

Toggle requested crosshair state and perform its visual transition.

Updates hidden first, then erases or draws through the low-level helpers. Those helpers do not consult hidden; they use actual visibility, mapping and hotspot eligibility. Does not invalidate the reusable graph backing store.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected crosshair record; enclosing dispatch owns lifetime protection.

  • interp – [in] Unused by this visibility handler.

  • objc – [in] Validated count of three; unused by this visibility handler.

  • objv – [in] Unused validated command vector.

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

Validate and dispatch a crosshair subcommand.

The typed table validates operation name and argument count before calling a handler. Borrowed graph state must remain live. Dispatch itself does not update segment geometry, process events or perform buffered presentation.

Parameters:
  • graphPtr – [inout] Borrowed live graph with selected crosshair record; enclosing dispatch owns lifetime protection.

  • interp – [in] Borrowed interpreter receiving diagnostics; see Interpreter arguments.

  • objc – [in] Command count; operation is at index two, optional arguments start at index three.

  • objv – [in] Borrowed full widget-command vector; see Tcl command arguments.

Windows position-only transition

This function is extracted from the Windows branch separately. Its documented scope does not change the compiled symbol or the shared crosshair interfaces.

static void MoveCrosshairs(Graph *graphPtr, Crosshairs *chPtr, const Point2D *hotSpotPtr)

Batch Windows position-only XOR erasure and drawing.

Requires unchanged drawing style/GC and a live graph/window. Computes new segments from hotSpotPtr and current graph bounds; compares both visibility and endpoints to avoid redrawing identical geometry. Submits up to four old/new segments in one renderer call, preserving a single native drawing batch.

Always updates hotspot, segments and visible, including when unmapped or hidden. Does not alter hidden or allocate a replacement GC. Only appropriate for position-only configuration; style changes must erase with the old GC. No Tcl callbacks or event processing may intervene in this transition.

Parameters:
  • graphPtr – [in] Borrowed live graph with current plot bounds.

  • chPtr – [inout] Prepared crosshairs with unchanged style/GC; hotspot, segments and visible state are replaced.

  • hotSpotPtr – [in] Borrowed new hotspot in widget pixels; copied, not retained.

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 CrosshairsOpSpec

Typed command dispatch entry with shared argument validation metadata.

Public Members

Rbc_OpSpecHeader header

Operation name, total argument bounds and usage suffix.

RbcGrHairsOp *proc

Typed command handler for this operation.

struct CrosshairsStruct

Graph-owned crosshair options and mapped XOR drawing state.

Public Members

Tk_OptionTable optionTable

Tk option table for this component configuration lifecycle.

Tcl_Obj *dashesObjPtr

Tk option-managed Tcl representation for dashes; 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 *positionObjPtr

Tk option-managed Tcl representation for position; released with the owning option state.

Point2D hotSpot

Hot spot for crosshairs.

int visible

Internal state of crosshairs.

If non-zero, crosshairs are displayed.

int hidden

If non-zero, crosshairs are not displayed.

This is not necessarily consistent with the internal state variable. This is true when the hot spot is off the graph.

Rbc_Dashes dashes

Dashstyle of the crosshairs.

This represents an array of alternatingly drawn pixel values. If NULL, the hairs are drawn as a solid line

int lineWidth

Width of the simulated crosshair lines.

Segment2D segArr[2]

Positions of line segments representing the simulated crosshairs.

XColor *colorPtr

Foreground color of crosshairs.

GC gc

Graphics context for crosshairs.

Set to GXxor to not require redraws of graph