codly.callout-config
Describes a content row attached to a source line in a code block. Use it in the callouts field of codly.new.
Signature
codly.callout-config(line: int, body: content, align: auto, breakable: auto, inset: auto, fill: auto, stroke: auto, source-indent: auto, placement: auto, bubble-gap: auto, pointer: auto, pointer-align: auto, pointer-size: auto, pointer-height: auto, pointer-width: auto, pointer-offset: auto, bubble-align: auto, bubble-fill: auto, bubble-stroke: auto, bubble-inset: auto, bubble-outset: auto, bubble-radius: auto, bubble-width: auto)All fields are named. A dictionary with line and body keys can also be used as a callout entry.
Fields
| Field | Type | Default / required | Meaning |
|---|---|---|---|
line |
int |
Required, named | Attached source line, one-based and positive. |
body |
content |
Required, named | Content displayed in the callout. |
align |
none | alignment | auto |
auto |
Cell alignment; auto inherits the codly.callout setting. |
breakable |
none | bool | auto |
auto |
Whether the cell can break across pages; auto inherits the codly.callout setting. |
inset |
none | length | dictionary | auto |
auto |
Cell padding; auto inherits the codly.callout setting. |
fill |
none | paint | auto |
auto |
Cell background; auto inherits the codly.callout setting. |
stroke |
none | stroke | auto |
auto |
Cell border; auto inherits the codly.callout setting. |
source-indent |
bool | auto |
auto |
Whether plain callouts retain source indentation and reserve the gutter columns. Pointed bubbles keep their character anchors. |
placement |
"above" | "below" | auto |
auto |
Whether the callout appears above or below its source line. |
bubble-gap |
length | dictionary | auto |
auto |
Minimum horizontal and vertical separation between bubbles. A length sets both axes; omitted dictionary axes use 0.5em. |
pointer |
none | int | auto |
auto |
One-based character anchor in the source line; zero selects the line start. none disables the pointed bubble. |
pointer-align |
"start" | "center" | "end" | auto |
auto |
Preferred alignment of the bubble around its source character, clamped to the available row. |
pointer-size |
length | auto |
auto |
Default arrow height and half-base width. |
pointer-height |
length | auto |
auto |
Arrow height; auto uses pointer-size. |
pointer-width |
length | auto |
auto |
Full arrow base width; auto uses twice pointer-size. |
pointer-offset |
length | auto |
auto |
Horizontal tip shift from the source character; positive moves right, negative moves left. Clamped to the bubble without moving its body. |
bubble-align |
alignment | auto |
auto |
Alignment of content inside the bubble, independent of grid cell alignment. |
bubble-fill |
none | paint | auto |
auto |
Fill shared by the bubble body and pointer. |
bubble-stroke |
none | stroke | auto |
auto |
Stroke around the single bubble and pointer outline. |
bubble-inset |
length | dictionary | auto |
auto |
Padding inside the bubble body. |
bubble-outset |
length | dictionary | auto |
auto |
Additional painted extent around the padded body, reserved in the row. |
bubble-radius |
length | auto |
auto |
Corner radius of the bubble body. |
bubble-width |
length | ratio | auto |
auto |
Preferred padded body width; auto fits the content within the available row. |
Behavior
An entry’s auto style values inherit from codly.callout; bubble styles can then inherit from codly.bubble. Explicit entry values take precedence. Cell fill and stroke accept none to disable painting. A pointed bubble uses one shared outline and paint for its body and arrow, and wraps its content at the available width.
Pointer positions count characters in the source line after a diff marker is removed; they are one-indexed, with zero denoting the start. The pointer follows the rendered character when source text wraps. Consecutive bubbles on the same side with matching cell styles share a row when their outlines fit; overlaps use another lane in declaration order.
Negative pointer positions, dimensions, insets, outsets, and gaps are invalid. bubble-gap dictionaries accept only x and y, whose omitted values default to 0.5em.
Example: Basic Usage
#import "@preview/codly:2.0.0" as codly
#codly.new(
```py
if ready:
start()
```,
callouts: (
codly.callout-config(
line: 2,
pointer: 5,
body: [This call runs when the input is ready.],
bubble-width: bubble-width,
bubble-fill: aqua.lighten(80%),
),
),
)Edit & run on your device
The controls supply the example variables. Their definitions are hidden here; Copy code includes the current values and your edits.
