labkit.app.plot.fitCanvasToSource

Inputs

ax

UI axes whose parent is a uigridlayout created for a LabKit preview.

width

Positive finite source-canvas width in pixels.

height

Positive finite source-canvas height in pixels.

Name-Value Arguments

margin

Preferred empty margin around the frame in pixels. Default: 24.

maxScale

Largest allowed ratio between displayed and source dimensions. Default: 1, so the helper does not enlarge the source canvas.

Outputs

applied

true when the grid and axes positions were updated; false when the axes, parent grid, dimensions, or available space were unsuitable.

frame

Scalar struct with width, height, ratio, position, scale, and pixelPosition fields. It is an empty struct when applied is false.

Description

fitCanvas centers the axes in the middle row and column of a three-by-three flexible grid and preserves the requested aspect ratio. The helper keeps one managed parent-position listener with the axes and reapplies the most recent canvas request after host resizing. It returns false instead of throwing when the host has not been laid out yet or is smaller than the minimum usable preview area.

Failure Behavior

Invalid axes, host grids, source dimensions, or insufficient available space return applied=false and frame=struct(). Malformed or unsupported name-value arguments throw labkit:app:plot:InvalidOptions or labkit:app:plot:InvalidOption.

Typical Call

[ok, frame] = labkit.app.plot.fitCanvasToSource(ax, 720, 540);