Skip to contents

Typed panel references

Source: R/panel-ref.R
panel-ref.Rd

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, rail = NULL)

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

is_panel_ref(x)

as_panel_ref(
  id,
  block_ids = character(),
  ext_ids = character(),
  near = NULL,
  side = NULL,
  size = NULL,
  rail = 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.

rail

The edge to park the panel on, left or right. Mutually exclusive with near / side.

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 / rail, move consumes near / side / rail – 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.

The rail hint parks a panel on one of the view's edges (see rail()), which is the one destination the tree cannot express, so it excludes near and side. Keeping the two apart matters beyond the pairing: side is a direction relative to a near anchor inside the splitview, a rail position is an edge of the whole view, and both spell left and right.

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", rail = "left")
#> <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