Bar element C reference
See Bar elements for configuration boundaries, grouping passes, mapped storage, rendering and cleanup. These routines
belong to rbcGrBar.c. The exported Rbc_ names are internal cross-module services, not additions to the public
vector stubs API. Namespaces below disambiguate private documentation symbols; they do not change C linkage.
Bar grouping state
-
struct FreqKey
Bar grouping key for an abscissa and axis pair.
Axis identities distinguish otherwise equal X values belonging to different mappings.
-
struct FreqInfo
Accumulated state for bars sharing a grouping key.
Stored in the graph-owned frequency array and indexed by its frequency table; mapping resets count and lastY.
Public Members
-
Tcl_Size freq
Number of bars sharing the abscissa and axes.
-
double sum
Sum of grouped ordinates used when determining stacked limits.
-
Tcl_Size count
Number of group entries already placed during the current mapping pass.
-
double lastY
Previous stacked ordinate used to place the next bar.
-
Tcl_Size freq
Configuration and pens
- group Bar configuration and pen lifecycle
Internal constructors and staged configuration; no public stubs are added.
Functions
-
static int IsBarPenPrefix(const char *string, Tcl_Size length, const char *fullName)
Recognize a nonempty, case-sensitive prefix of a color keyword.
The borrowed strings must contain at least their stated lengths. Returns a boolean; an empty spelling and a spelling longer than fullName fail.
- Parameters:
string – [in] Borrowed candidate spelling, readable for length bytes.
length – [in] Candidate byte count; nonpositive or overlong spellings do not match.
fullName – [in] Borrowed NUL-terminated keyword spelling.
-
static int GetBarPenColorFromObj(Tcl_Interp *interp, Tk_Window tkwin, Tcl_Obj *objPtr, XColor **colorPtrPtr)
Resolve an optional error color into a staged resource.
NULL or an empty object yields NULL; a nonempty prefix of defcolor yields COLOR_DEFAULT. Other spellings acquire a Tk color reference. Returns TCL_OK and writes colorPtrPtr on success, or TCL_ERROR with an interpreter diagnostic and the output unchanged. Release acquired colors with FreeBarPenColor.
- Parameters:
interp – [in] Borrowed interpreter receiving color errors; see Interpreter arguments.
tkwin – [in] Borrowed live Tk window used to acquire a color reference.
objPtr – [in] Borrowed option object; NULL and empty mean no explicit color.
colorPtrPtr – [out] Required output slot; unchanged on failure. Successful values require sentinel-aware release.
-
static void FreeBarPenColor(XColor *colorPtr)
Release an acquired color while accepting the default sentinel.
NULL and COLOR_DEFAULT are no-ops. Does not clear the caller’s pointer or release a retained option object.
- Parameters:
colorPtr – [in] Owned Tk color reference to release, or NULL/COLOR_DEFAULT for no release.
-
static const XColor *GetBarColor(Graph *graphPtr, const BarPen *penPtr, const XColor *colorPtr, XColor *fallbackPtr)
Resolve a bar color consistently for native GCs and renderer output.
Borrows the pen and candidate color. NULL and COLOR_DEFAULT inherit the foreground, then the border color, then screen black. Returns a borrowed color or initializes and returns caller-owned fallback storage. The caller must keep fallback alive while the renderer uses the returned pointer. Accepting a candidate color also supports ConfigurePen before commit.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
penPtr – [in] Borrowed configured concrete bar pen; drawing resources must remain valid throughout the call.
colorPtr – [in] Borrowed candidate color, NULL or COLOR_DEFAULT; no reference is acquired.
fallbackPtr – [out] Required caller storage if all inherited colors are absent; retain through renderer use.
-
static int ConfigurePen(Graph *graphPtr, Pen *penPtr)
Validate and replace a bar pen’s derived drawing resources.
Tk has already installed candidate option fields. Validate opacity, label offset, command prefix, format, rotation, pixel widths, show masks and shadow before replacing any derived resource. Acquire all replacement GCs before freeing the old ones. Returns TCL_OK on commit; TCL_ERROR frees staged colors and leaves derived resources unchanged. The caller owns rollback of the candidate Tk option fields. Validation does not invoke the value-label command. Works for named pens and the element’s embedded pen.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
penPtr – [inout] Common header of a concrete bar pen with candidate Tk option fields already installed.
-
static void DestroyPen(Graph *graphPtr, Pen *penPtr)
Release bar-pen resources derived outside the Tk option table.
Frees text-style drawing resources, fill/error GCs, the derived error color and shadow color, clearing released pointers. Does not free the pen record, name, or Tk-managed option resources; shared pen/element teardown owns those. The embedded pen must not be freed as a standalone allocation.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
penPtr – [inout] Concrete bar pen header whose derived resources are released; allocation and Tk option fields remain.
-
static void InitPen(BarPen *penPtr, const Tk_OptionSpec *optionSpecs, unsigned int flags)
Initialize methods and fallback fields in a zeroed bar pen.
The caller supplies storage and a non-NULL option specification. Installs configuration/destruction callbacks and initializes text style and flags. Does not apply Tk defaults, allocate drawing GCs or register a named pen.
- Parameters:
penPtr – [inout] Caller-owned zeroed concrete storage; initialized in place, not registered.
optionSpecs – [in] Non-NULL option template retained by pointer; must outlive the pen.
flags – [in] Initial common pen flags, such as NORMAL_PEN or ACTIVE_PEN.
-
Pen *Rbc_BarPen(const char *penName)
Allocate an unregistered named bar pen for shared pen creation.
Returns the common Pen header of owned, zeroed concrete storage with a copied name. The exact name activeBar selects active option defaults; other names select normal defaults. Allocation is asserted. The shared pen manager must initialize options, register/configure the pen and own its eventual destruction. This is an internal constructor, not a stubs API.
- Parameters:
penName – [in] Borrowed NUL-terminated name copied into the new pen; exact activeBar selects active defaults.
-
static int ConfigureBar(Graph *graphPtr, Element *elemPtr)
Stage element dependencies before committing bar configuration.
Called after Tk installs candidate options. Rejects nonfinite width and offset; a finite nonpositive element width retains graph-width fallback. Prepares changed data, pens, axes, state, tags and styles, then configures the embedded pen if needed. Commits dependencies and synchronizes retained data objects only after fallible preparation succeeds. Updates the palette default pen and sets MAP_ITEM for mapping-related changes. Returns TCL_OK on success; TCL_ERROR frees prepared candidates and leaves Tk option rollback to the caller. Data preparation can evaluate expressions: ordinary rollback is not a guarantee against arbitrary callback side effects.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
elemPtr – [inout] Common header of a live bar element with candidate Tk fields and option-mask state.
-
Element *Rbc_BarElement(Graph *graphPtr, const char *name, Rbc_Uid classUid)
Allocate an unconfigured bar element for shared element creation.
Returns the common Element header of owned zeroed storage, or NULL on allocation failure. Copies name and initial label, borrows graph/class identity, installs bar methods, initializes the embedded normal pen and creates an empty palette. The caller must apply options, configure and register the element, or release it through shared element teardown. Ordinary paired X/Y counting is used; no complex point-count hook is set.
- Parameters:
graphPtr – [in] Borrowed owning graph retained by the unconfigured element.
name – [in] Borrowed NUL-terminated name copied into both initial name and label.
classUid – [in] Borrowed stable element-class identity installed in the common header.
-
void Rbc_BarFontsChanged(Graph *graphPtr)
Refresh label text styles after a graph font change.
Visits bar pens in the named-pen table and embedded pens in the element table, including elements outside the display list. Resets each text style with a non-NULL font. Borrows graph-owned records; does not rebuild bar geometry, select active pens or itself schedule a redraw.
- Parameters:
graphPtr – [inout] Live graph with valid pen/element tables and Tk window; label styles are refreshed.
-
static int IsBarPenPrefix(const char *string, Tcl_Size length, const char *fullName)
Grouping and placement
- group Bar layout internals
Private data-space placement and mapped geometry services.
Source arrays and graph records are borrowed; these helpers do not invoke Tcl callbacks.
Functions
-
static int GetTrackBarMode(Graph *graphPtr, Axis *yAxis)
Select the owning track override or the graph bar mode.
The borrowed Y axis must be live. A nonnegative track barMode overrides the graph mode; axis identity, rather than this helper, isolates grouping. No state is changed.
- Parameters:
graphPtr – [in] Borrowed graph supplying the fallback bar mode.
yAxis – [in] Live owning Y axis; its track may override the graph mode.
-
static int Round(double x)
Round a bounded pixel distance with half values away from zero.
The caller must supply a finite value whose adjusted value fits in int. This helper does not clamp or report conversion errors.
- Parameters:
x – [in] Finite pixel distance whose half-adjusted value is representable as int.
-
static int GetBarArrayByteCount(Tcl_Size count, size_t elementSize, size_t *bytesPtr)
Validate a Tcl_Size array count before size_t multiplication.
Rejects negative counts, zero element size and multiplication overflow. Returns TCL_OK and writes bytesPtr on success (including a zero count), otherwise TCL_ERROR with the output unchanged. No interpreter diagnostic or allocation is performed.
- Parameters:
count – [in] Nonnegative number of array entries; zero is accepted.
elementSize – [in] Positive byte size of one entry.
bytesPtr – [out] Required output slot for the product; unchanged on error.
-
static void CheckStacks(Graph *graphPtr, Axis2D *pairPtr, double *minPtr, double *maxPtr)
Expand Y limits using precomputed totals for one axis pair.
Only operates in the effective stacked mode with duplicate metadata. Reads matching records in graph-owned freqArr; negative totals may lower minPtr, nonnegative totals may raise maxPtr. Requires Rbc_ComputeStacks first. Does not reset counters or inspect intermediate cumulative heights.
- Parameters:
graphPtr – [in] Borrowed graph with current frequency metadata and computed stack sums.
pairPtr – [in] Borrowed axis pair selecting the matching duplicate records.
minPtr – [inout] Required current Y minimum; may be lowered by negative totals.
maxPtr – [inout] Required current Y maximum; may be raised by nonnegative totals.
-
static double GetBarBaseline(Element *elemPtr)
Return the configured baseline with the historical log fallback.
Uses one when the Y axis is logarithmic and the configured baseline is nonpositive. Borrows the live element, graph and Y axis; no state is changed.
- Parameters:
elemPtr – [in] Borrowed bar element with live graph and selected Y axis.
-
static double BarAnchorOffset(const Bar *barPtr, double width)
Return the anchor displacement for the full data-X interval.
Left gives zero, right gives width and center gives half width. Apply before grouped subdivision. Width is the caller’s effective bar width; this helper neither validates it nor advances grouping counters.
- Parameters:
barPtr – [in] Borrowed bar supplying alignment.
width – [in] Effective data-X width of the full bar/group interval, before subdivision.
-
static int PlaceBar(Graph *graphPtr, Bar *barPtr, Tcl_Size index, int clip, Point2D *firstPtr, Point2D *secondPtr)
Compute one bar’s data-space corners and consume its group position.
Apply each element’s width, alignment and offset before subdivision. Duplicate keys use the original X value and both axis identities. Successful grouped placement advances count or lastY; this is not a pure query. Reset grouping state before a new ordered pass. Log-invalid and nonfinite input, invalid full X intervals, viewport rejection and stack overflow are skipped. Corners are not screen mapped or reordered for negative-height bars.
- Parameters:
graphPtr – Borrowed graph with initialized grouping state.
barPtr – Borrowed bar element and axis pair.
index – Valid index in both source arrays.
clip – Reject full X intervals outside linear-axis viewport limits.
firstPtr – Receives the lower X edge and placed data-value Y.
secondPtr – Receives the upper X edge and baseline or previous stack Y.
- Returns:
TRUE for a placement; FALSE leaves the output corners unchanged.
-
static void GetBarExtents(Element *elemPtr, Extents2D *extsPtr)
Compute bar data limits and translated error limits.
Includes full anchored X intervals, baseline rules and duplicate stack totals. Calls PlaceBar without viewport rejection to advance group state even when error bars retain data positioning. In bar positioning mode, owns a temporary per-source translation array and frees it after expanding error limits. The caller must reset group state before the ordered pass.
- Parameters:
elemPtr – Borrowed bar element.
extsPtr – Receives bounds, or sentinel empty bounds without paired data.
-
static void ClosestBar(Graph *graphPtr, Element *elemPtr, ClosestSearch *searchPtr)
Search mapped bar rectangles while retaining source identity.
Interior hits have zero distance; other candidates use rectangle edges. rectToData translates mapped order back to source order. Reported X and Y are original data values, not shifted centers or cumulative stack values. No arrays are allocated and no graph state is changed.
- Parameters:
graphPtr – Borrowed graph (unused by this search).
elemPtr – Borrowed bar element with current mapped rectangles.
searchPtr – In/out search; replaced only for a strictly closer hit.
-
static void MapBar(Graph *graphPtr, Element *elemPtr)
Replace bar display geometry from source data and group state.
Allocates owned rectangles and original-source indices, places bars in order, maps corners and bounds coordinates before integer conversion. Owns temporary error translations and style lookup storage; frees both after mapping errors and grouping geometry by pen. Active rectangles are rebuilt when explicit active indices exist. This consumes group state and must run in the ordered mapping pass, after its reset. Renderer clipping is separate from the window bounds used here to keep integer conversion safe.
- Parameters:
graphPtr – Borrowed graph in the element’s mapping viewport.
elemPtr – Borrowed bar element whose old geometry is discarded.
-
void Rbc_InitFreqTable(Graph *graphPtr)
Rebuild duplicate-X grouping metadata for displayed bar elements.
Releases previous graph-owned metadata first. Ordinary normal mode needs no table; trackgraphs still need one for local overrides. Counts finite paired samples with valid log-Y values, using source X and both axis identities; normalizes signed zero. Only duplicate keys receive persistent records, owned by freqArr and borrowed by hash entries. nStacks indicates persistent table initialization. Does not apply width/offset/alignment or compute stack sums. The graph must retain axes throughout metadata use.
- Parameters:
graphPtr – [inout] Live graph with displayed bars and axes; previous grouping metadata is replaced.
-
void Rbc_ComputeStacks(Graph *graphPtr)
Accumulate signed source-Y totals for duplicate grouping keys.
Requires current frequency metadata. Resets sums, then visits displayed bars and valid pairs in display-list order. Ordinary nonstacked graphs return early; trackgraphs compute all duplicate totals and CheckStacks chooses where to use them. Sums are ordinary double additions, without PlaceBar’s overflow rejection or separate positive/negative accumulation. Does not alter placement counters or source data.
- Parameters:
graphPtr – [inout] Graph with current duplicate metadata and source arrays; sums are replaced, placement cursors retained.
-
void Rbc_ResetStacks(Graph *graphPtr)
Reset mutable group placement cursors before an ordered pass.
Sets every duplicate record’s lastY and count to zero, retaining sums, frequencies and axis identities. A missing/empty array is a no-op. Call before an extents or mapping traversal, not between members of a group.
- Parameters:
graphPtr – [inout] Graph with initialized duplicate metadata, or an empty array; only placement cursors are reset.
-
static int GetTrackBarMode(Graph *graphPtr, Axis *yAxis)
Geometry and lifetime
- group Bar geometry ownership
Mapped arrays, style views, active selections and concrete element cleanup.
Functions
-
static void ClearPalette(Rbc_Chain *palette)
Invalidate rectangle and error-segment counts in every style.
The palette and styles are borrowed. Slice pointers are not cleared or freed; their zero counts prevent use until remapping replaces the views. Pen references and weight ranges are retained.
- Parameters:
palette – [inout] Initialized chain of bar styles; counts are cleared while pointers and pen references remain.
-
static Point2D *NewBarErrorOffsets(Tcl_Size nPoints)
Allocate per-source error translations initially marked invalid.
Returns an owned Point2D array with both coordinates set to NaN in every slot, or NULL if the byte count is invalid. Allocation uses ckalloc; this is not a recoverable allocator-failure interface. The caller frees the array after mapping or expanding error limits.
- Parameters:
nPoints – [in] Source-slot count; each allocated slot starts with NaN X/Y offsets. Invalid size returns NULL.
-
static void SetBarErrorOffset(Bar *barPtr, Tcl_Size index, const Point2D *firstPtr, const Point2D *secondPtr, Point2D *offsets)
Store the placed-center and placed-value displacement of one sample.
All pointers are borrowed and index must be valid in both source arrays and offsets. Corners must come from PlaceBar before swapping Y edges or screen mapping. Averages X endpoints as two halves and subtracts source X; subtracts source Y from the first corner’s Y. Does not allocate or validate.
- Parameters:
barPtr – [in] Borrowed bar with original X/Y arrays.
index – [in] Original source index valid in both source arrays and offsets.
firstPtr – [in] Borrowed placed lower-X/value-Y corner before screen mapping or Y-edge swaps.
secondPtr – [in] Borrowed placed upper-X/baseline-Y corner from the same placement.
offsets – [inout] Caller-owned per-source array; only the entry at index is overwritten.
-
int Rbc_GetBarRectangle(Element *elemPtr, Tcl_Size dataIndex, Extents2D *extsPtr)
Look up mapped bounds by original source index.
The non-NULL element must be a bar; no class check or remapping occurs. Returns TRUE and writes physical window bounds on a match. Returns FALSE for missing geometry, invalid arguments or an unmapped index, leaving output unchanged. Bounds include placement, inversion and mapping’s window clamp, but are not intersected with the final renderer plot clip. Borrows all storage and does not invoke callbacks.
- Parameters:
elemPtr – [in] Borrowed bar element with current mapped storage; NULL returns FALSE, other classes are invalid.
dataIndex – [in] Original source index, not a mapped rectangle index; negative values return FALSE.
extsPtr – [out] Required output for success; NULL returns FALSE. Bounds remain unchanged on a miss.
-
static void MergePens(Bar *barPtr, PenStyle **dataToStyle)
Group rectangles and errors into palette slices with source maps.
Requires a nonempty palette and a dataToStyle entry for each referenced source index. With one style, installs borrowed views without copying. Otherwise allocates replacement arrays, visits styles in palette order, preserves order within each style and replaces the owned geometry and index maps together. Styles borrow slices, never own them. Invalid byte counts cause an early return; there is no Tcl error result. Does not change source vectors or the separately copied active geometry.
- Parameters:
barPtr – [inout] Mapped bar with nonempty palette; owned geometry/index arrays may be replaced together.
dataToStyle – [in] Borrowed source-indexed style lookup covering every referenced source sample.
-
static void MapActiveBars(Bar *barPtr)
Rebuild the explicit active subset from mapped source indices.
Frees previous active arrays first. For positive nActiveIndices, copies matching rectangles in mapped order and retains original source indices; repeated requests do not duplicate a rectangle. Unmapped requests yield no rectangle. Clears ACTIVE_PENDING even for empty or size-invalid output. Negative all-active mode is handled by drawing/export, not copied here.
- Parameters:
barPtr – [inout] Mapped bar with active selection; old active arrays are freed and ACTIVE_PENDING cleared.
-
static void ResetBar(Bar *barPtr)
Discard owned mapped geometry and invalidate palette views.
Clears palette counts, frees normal/active rectangles, error segments and their source-index maps, then zeros the owning pointers and counts. Does not clear borrowed style pointers, free source vectors, release pens or discard the active-index selection. Used before remapping and at teardown.
- Parameters:
barPtr – [inout] Live bar owning mapped arrays; source data, pens and active-index selection are retained.
-
static void DestroyBar(Graph *graphPtr, Element *elemPtr)
Release concrete bar dependencies without freeing the element record.
Drops axis and named-pen references, destroys the embedded pen’s derived resources, detaches all source slots and frees mapped geometry, active selection, palette and tags. Source-vector creators retain ownership of their vectors. Shared element teardown handles Tk-managed options, names and the concrete record allocation; this callback must not free them.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
elemPtr – [inout] Common bar header; dependencies and mapped storage are released, concrete allocation remains.
-
struct BarPen
A concrete bar pen with a first-member Pen header.
Tk owns direct option resources; ConfigurePen/DestroyPen own derived colors and drawing GCs.
Public Members
-
Tcl_Obj *borderWidthObjPtr
Tk option-managed Tcl representation for border width; released with the owning option state.
-
Tcl_Obj *errorBarCapObjPtr
Tk option-managed Tcl representation for error bar cap; released with the owning option state.
-
Tcl_Obj *errorBarColorObjPtr
Tk option-managed Tcl representation for error bar color; released with the owning option state.
-
Tcl_Obj *errorBarWidthObjPtr
Tk option-managed Tcl representation for error bar width; released with the owning option state.
-
Tcl_Obj *showErrorBarsObjPtr
Tk option-managed Tcl representation for show error bars; released with the owning option state.
-
Tcl_Obj *showValuesObjPtr
Tk option-managed Tcl representation for show values; released with the owning option state.
-
Tcl_Obj *valueRotateObjPtr
Tk option-managed Tcl representation for value rotate; released with the owning option state.
-
Tcl_Obj *valueShadowObjPtr
Tk option-managed Tcl representation for value shadow; released with the owning option state.
-
XColor *fgColor
Configured fill color.
-
Tk_3DBorder border
Tk-managed 3D border for the bar fill and relief.
-
int borderWidth
Bevel thickness in pixels.
-
int relief
Tk bar relief selector.
-
Pixmap stipple
Retained fill stipple bitmap, or None.
-
double fillOpacity
Fill alpha; borders and annotations remain opaque.
-
GC gc
Owned native fill GC.
-
int errorBarShow
Bit mask selecting X and Y error bars.
-
int errorBarLineWidth
Error stroke width in pixels.
-
int errorBarCapWidth
Requested error cap width in pixels; mapping resolves automatic widths.
-
XColor *errorBarColor
Configured error color; COLOR_DEFAULT requests the element fallback.
-
GC errorBarGC
Owned GC for native error strokes.
-
int valueShow
Bit mask selecting X and Y coordinates in labels.
-
char *valueFormat
Option-managed numeric format string.
-
Tcl_Obj *valueCommandObjPtr
Tk option-managed Tcl representation for value command; released with the owning option state.
-
Tcl_Obj *valueOffsetObjPtr
Tk option-managed Tcl representation for value offset; released with the owning option state.
-
Tcl_Obj *borderWidthObjPtr
-
struct BarPenStyle
A weighted palette entry borrowing a concrete pen and mapped array slices.
Counts delimit valid views; the containing element owns the arrays.
-
struct Bar
A concrete bar element with a first-member Element header and embedded pen.
Owns normal/active rectangles and source-index maps; common error arrays reside in the Element header.
Public Members
-
Tcl_Size *rectToData
Owned map from each displayed rectangle to its source sample index.
-
BarRectangle *rectangles
Array of rectangles comprising the bar segments of the element.
-
int padX
Spacing on either side of bar.
-
double barWidth
Requested bar width in X data units; zero inherits graph width.
-
int barAlign
Anchor of the full group interval.
-
int errorBarPosition
Data coordinates or final bar placement.
-
double barOffset
Translation in data X coordinates.
-
Tcl_Size nActive
Number of mapped active rectangles.
-
BarRectangle *activeRects
Owned mapped active rectangle array.
-
Tcl_Size *activeToData
Owned map from active rectangles to source indices.
-
Tcl_Size *rectToData
-
static void ClearPalette(Rbc_Chain *palette)
Screen drawing and document output
- group Bar screen and document output
Renderer adapters; value-label callbacks require stable drawing records.
Functions
-
static void DrawSymbol(Graph *graphPtr, Drawable drawable, Element *elemPtr, int x, int y, int size, int width, int height)
Draw a square legend sample using the normal pen.
Borrows graph, drawable and element. Skips zero opacity or absent colors. Preserves integer centering and size-minus-one geometry. Tries the renderer legend adapter, then the screen fallback when unhandled. The sample is independent of data rectangles, active/style pens and plot placement.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
drawable – [in] Borrowed compatible legend destination.
elemPtr – [in] Borrowed bar element with configured normal pen.
x – [in] Legend-sample center X in destination pixels.
y – [in] Legend-sample center Y in destination pixels.
size – [in] Nominal square sample size; integer centering and size-minus-one geometry are preserved.
width – [in] Destination drawable width passed to the legend renderer adapter.
height – [in] Destination drawable height passed to the legend renderer adapter.
-
static void DrawBarSegments(Graph *graphPtr, Drawable drawable, BarPen *penPtr, BarRectangle *rectangles, Tcl_Size nRects)
Submit one bar rectangle batch with its pen style.
Borrows rectangles and pen resources; opens and closes a screen bar context around the complete batch. The outer element drawing scope supplies track/plot clipping, including borders. Does not map or copy geometry.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
drawable – [in] Borrowed compatible screen destination; outer caller supplies plot/track clipping.
penPtr – [in] Borrowed configured concrete bar pen; drawing resources must remain valid throughout the call.
rectangles – [in] Borrowed mapped rectangle array with nRects entries.
nRects – [in] Nonnegative rectangle count; not a source-sample or segment count.
-
static void DrawBarValues(Graph *graphPtr, Drawable drawable, Bar *barPtr, BarPen *penPtr, BarRectangle *rectangles, Tcl_Size nRects, const Tcl_Size *rectToData)
Draw source-value labels anchored to mapped rectangles.
The borrowed rectangle and source-index arrays must correspond. Obtains one owned label reference per rectangle and releases it after use; empty text is skipped. Inversion and the source value relative to the effective baseline choose the anchor edge. Adds the pen offset, checks int bounds and truncates screen coordinates. Label commands may execute Tcl: callers must keep graph, pen, element and geometry live and unchanged throughout drawing; this loop adds no preservation against callback mutation.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
drawable – [in] Borrowed compatible screen destination; outer caller supplies plot/track clipping.
barPtr – [in] Borrowed bar with source arrays stable across label callbacks.
penPtr – [in] Borrowed configured concrete bar pen; drawing resources must remain valid throughout the call.
rectangles – [in] Borrowed mapped rectangle batch, stable throughout label evaluation.
nRects – [in] Nonnegative number of rectangles and matching source-index entries.
rectToData – [in] Borrowed parallel map to valid original X/Y indices; not palette-relative indices.
-
static void DrawBarErrorSegments(Graph *graphPtr, Drawable drawable, BarPen *penPtr, const Segment2D *segments, Tcl_Size count)
Draw one error-stroke batch with screen color and width defaults.
Borrows pen and segments. NULL/default color falls back to foreground, then border color, then screen black. Supplies at least one pixel to the stroke renderer and the configured GC for native drawing. Closes any returned context; an unavailable context produces no strokes. Does not map errors.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
drawable – [in] Borrowed compatible screen destination; outer caller supplies plot/track clipping.
penPtr – [in] Borrowed configured concrete bar pen; drawing resources must remain valid throughout the call.
segments – [in] Borrowed mapped independent error strokes, including any cap segments.
count – [in] Nonnegative number of segment records, not the number of source errors.
-
static void DrawNormalBar(Graph *graphPtr, Drawable drawable, Element *elemPtr)
Draw palette-grouped bars, errors and labels in that order.
Requires current geometry and style slices. Each style draws rectangles, enabled X errors, enabled Y errors, then labels. Advances the parallel rectToData slice by each style’s rectangle count. The caller supplies the clipping/lifetime scope; label commands can execute Tcl and must not mutate the borrowed drawing records.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
drawable – [in] Borrowed compatible screen destination; outer caller supplies plot/track clipping.
elemPtr – [inout] Mapped bar with current palette slices and parallel source maps; callbacks must not mutate them.
-
static void DrawActiveBar(Graph *graphPtr, Drawable drawable, Element *elemPtr)
Draw active rectangles and labels with the active pen.
A missing active pen or zero selection draws nothing. Positive selection rebuilds ACTIVE_PENDING geometry on demand; a negative selection draws all mapped rectangles. Does not overlay active error bars. Borrows records and inherits DrawBarValues callback restrictions.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
drawable – [in] Borrowed compatible screen destination; outer caller supplies plot/track clipping.
elemPtr – [inout] Mapped bar with stable drawing dependencies; pending active geometry may be rebuilt.
-
static void SymbolExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, Element *elemPtr, double x, double y, int size)
Export a normal-pen legend sample through the selected backend.
Skips zero opacity or absent colors. With stipple and no foreground, promotes background to stipple foreground and leaves gaps transparent. Borrows style resources and closes the symbol context after one point; does not emit data rectangles or relief borders.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
exportPtr – [inout] Borrowed initialized export context; outer caller owns clipping and document finalization.
elemPtr – [in] Borrowed bar element with configured normal pen.
x – [in] Mapped sample center X in export pixel coordinates.
y – [in] Mapped sample center Y in export pixel coordinates.
size – [in] Nominal square legend sample size in pixels.
-
static void SegmentsExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, BarPen *penPtr, BarRectangle *rectPtr, Tcl_Size nRects)
Export filled rectangles and optional relief borders for one pen.
Borrows the mapped rectangle batch. Normalizes stipple colors, opens one fill context and skips rectangles with dimensions below one. Preserves the historical one-pixel fill inset. Positive opacity enables fills; nonflat borders use the original dimensions and can remain visible at zero fill opacity. No colors means no output. Closes its context before returning; plot/track clipping belongs to the outer export scope.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
exportPtr – [inout] Borrowed initialized export context; outer caller owns clipping and document finalization.
penPtr – [in] Borrowed configured concrete bar pen; drawing resources must remain valid throughout the call.
rectPtr – [in] Borrowed mapped rectangle batch; array extent must permit nRects-entry traversal.
nRects – [in] Nonnegative rectangle count; each rectangle with a dimension below one is skipped.
-
static void BarValuesExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, Bar *barPtr, BarPen *penPtr, BarRectangle *rectangles, Tcl_Size nRects, const Tcl_Size *rectToData)
Export source-value labels at mapped bar anchors.
Uses the same source-index lookup and baseline/inversion anchor rule as DrawBarValues, retaining floating-point output coordinates. Borrows drawing records, releases each acquired label object and closes the output context. Label commands may execute Tcl and must not mutate owners or geometry or enter nested event loops. Empty labels are skipped.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
exportPtr – [inout] Borrowed initialized export context; outer caller owns clipping and document finalization.
barPtr – [in] Borrowed bar with source arrays stable across label callbacks.
penPtr – [in] Borrowed configured concrete bar pen; drawing resources must remain valid throughout the call.
rectangles – [in] Borrowed mapped rectangle batch, stable throughout label evaluation.
nRects – [in] Nonnegative number of rectangles and matching source-index entries.
rectToData – [in] Borrowed parallel map to valid original X/Y indices; not palette-relative indices.
-
static void ActiveBarExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, Element *elemPtr)
Export selected or all active rectangles and their labels.
Uses the active pen if present. Positive selection rebuilds pending active geometry; negative selection uses the full mapped arrays. Zero selection emits nothing. Does not export active errors. Requires the outer export clip and the label-callback lifetime contract of BarValuesExport.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
exportPtr – [inout] Borrowed initialized export context; outer caller owns clipping and document finalization.
elemPtr – [inout] Mapped bar with stable drawing dependencies; pending active geometry may be rebuilt.
-
static void NormalBarExport(Graph *graphPtr, Rbc_ExportContext *exportPtr, Element *elemPtr)
Export palette-grouped bars, error strokes and value labels.
Borrows current style slices and corresponding source-index ranges. Uses the shared bar color fallback for errors and passes the configured width to export stroke contexts. Labels may execute Tcl; the outer caller must maintain the drawing records and export clip throughout.
- Parameters:
graphPtr – [in] Borrowed live owning graph providing Tk, display and renderer context.
exportPtr – [inout] Borrowed initialized export context; outer caller owns clipping and document finalization.
elemPtr – [inout] Mapped bar with current palette slices and parallel source maps; callbacks must not mutate them.
-
static void DrawSymbol(Graph *graphPtr, Drawable drawable, Element *elemPtr, int x, int y, int size, int width, int height)