Typed panel references

blk() and ext() construct references to a block or extension panel for the views$mod panel-op grammar (see board_update). They are the public currency: a caller names a block or extension by its id, never the block_panel- / ext_panel- wire prefix – the ref is the codec, and as.character() on one yields the canonical panel-id encoding.

Usage

blk(id, near = NULL, side = NULL, size = NULL)

ext(id, near = NULL, side = NULL, size = NULL)

is_panel_ref(x)

as_panel_ref(
  id,
  block_ids = character(),
  ext_ids = character(),
  near = NULL,
  side = NULL,
  size = NULL
)

# S3 method for class 'panel_ref'
as.character(x, ...)

Arguments

id

A block or extension id. For blk() / ext() a bare id (not the wire-prefixed panel id); as_panel_ref() additionally accepts an already wire-prefixed panel id or a panel_ref.

near

A ref or bare id to anchor placement against.

side

Placement direction relative to near: one of within, left, right, above, below.

size

Target size ratio in (0, 1) – consumed by resize, and recorded on add for a later size-on-create pass.

x

An object.

block_ids, ext_ids

Character vectors partitioning the id namespace that as_panel_ref() resolves a bare id against.

...

Ignored.

Value

blk(), ext() and as_panel_ref() return a panel_ref. as.character() on one returns its canonical panel id, and is_panel_ref() returns a boolean.

Details

Each ref optionally carries its own placement hint, so a verb's operands are an unnamed list of self-describing refs: add = list(blk("a", near = "b", side = "right"), ext("dag")). Which hint fields are meaningful depends on the verb – add consumes near / side / size, move consumes near / side – and a hint on a ref used where no placement happens (rm, select, a near anchor, or the dock_grid() / panels() authoring DSL) is a loud error. Because the hints are constructor arguments, a misspelled one (blk("a", sise = 0.4)) fails at the call site with R's own unused-argument error, before any payload exists.

Bare id strings are accepted as sugar wherever a ref is, resolved block-first with a hard error only on a true cross-namespace clash (an id that is both a block and an extension), which then demands a typed ref.

as_panel_ref() is the programmatic form of that sugar: given a bare id and the block_ids / ext_ids partitioning a board's namespace, it returns the correctly-typed blk() / ext() ref (carrying any placement hint), applying the same block-first precedence and the same cross-namespace clash error. An already wire-prefixed panel id, or an existing panel_ref, resolves to the matching ref unchanged.

Examples

blk("my_block", near = "other_block", side = "right")
#> <panel_ref> block_panel-my_block 
ext("dag")
#> <panel_ref> ext_panel-dag 
as.character(blk("my_block"))
#> [1] "block_panel-my_block"

as_panel_ref("my_block", block_ids = "my_block")
#> <panel_ref> block_panel-my_block 
as_panel_ref("dag", block_ids = "my_block", ext_ids = "dag")
#> <panel_ref> ext_panel-dag