ToolbarCoordinator

SAM hook for main-toolbar item clicks — Java-friendly wrapper over ToolbarAction.ItemClicked.

SAM hook for taps on the main toolbar's navigation icon — Java-friendly wrapper over ToolbarAction.NavigationClicked.

Identity of the binder currently authorized to write through this coordinator. null means no binder is bound — actions registered in that state are unbound and survive writer swaps (used for test setup and pipeline-stage registrations).

The currently displayed contextual (special-mode) toolbar, or null when none is shown. Driven by per-mode binders (annotation, document editing, content editing) via showContextualToolbar / hideContextualToolbar.

Optional host-supplied grouping override for contextual toolbars, or null (the default) to use the SDK preset for the current capacity. Read by the contextual toolbar composable on every (re-)measure; snapshot-backed so a provider registered or cleared while a bar is shown regroups it immediately. Like action lambdas, the provider is never persisted — hosts re-register it on restore (ADR-Toolbar-4).

State of the document title overlay rendered below the main toolbar row (see com.pspdfkit.compose.toolbar.composables.NutrientDocumentTitleOverlay). Distinct from ToolbarFrame.title, the title shown in the toolbar row itself.

Observable frame-level toolbar state (visibility, height, position, title).

Observable, pre-grouped collection of visible and overflow toolbar items.

Optional caller-supplied color override for the main toolbar. null (the default) means the renderer falls back to the XML-derived defaults (getUiColors()), preserving the legacy theming path. A non-null value lets a host theme the toolbar programmatically with a Compose UiColorScheme (e.g. getComposeUiColors() or a fully custom scheme) without going through XML attributes.

The active inline-search session, or null when no search host is bound. The main toolbar renders the inline search bar (instead of its items) while the session's isActive is true. Set by the fragment-flavor search controller; host-agnostic (see ToolbarSearchSession).

Claim the active-writer slot for writerId. Last-acquirer wins: any actions registered by the previous writer are evicted from the registry. Unbound registrations survive.

Register an interceptor consulted before any addActionListener listener. Returning true consumes the action: no later interceptor and no listener (including the SDK's own handlers) sees it. This is the replacement for the removed View AnnotationToolbar.OnMenuItemClickListener's consume-by-returning-true contract — use it to gate tools (e.g. show a paywall instead of activating a tool).

Register a listener for ToolbarActions emitted by composables.

Observes the contextual toolbar's state — shown/hidden (null), which bar (ContextualToolbarState.kind), items, docking position, draggability. The callback-based counterpart of collecting contextualToolbar, for hosts without a coroutine scope (and the replacement for observing the removed View OnContextualToolbarLifecycleListener/OnContextualToolbarPositionListener).

Register handler for main-toolbar ToolbarAction.ItemClicked events. Clicks originating from a contextual toolbar (their ToolbarAction.ItemClicked.kind is non-null) are not forwarded — observe those with addActionListener, or veto them with addActionInterceptor. Returns a ToolbarSubscription the host must close on teardown (same lifecycle contract as addActionListener).

Register handler for ToolbarAction.NavigationClicked — taps on the icon set via setMainToolbarNavigationIcon. Same lifecycle and ownership contract as addItemClickHandler: in PdfActivity / PdfUiFragment the SDK registers its own handler and forwards to com.pspdfkit.ui.PdfUi.setOnToolbarNavigationClickListener; call this directly only when you own the coordinator.

Tear down the coordinator. After close the scope is no longer used, all listeners are cleared, and any further dispatch call is a no-op.

Composable-facing: emit a user-initiated action.

Invoke the lambda registered for actionId, if any. Silent no-op when no registration exists — pipeline stages can fire actions during initial render before binders have registered, and that must not crash.

Hides the contextual toolbar. No-op when none is shown.

Register a click handler for the action identified by actionId.

Release the active-writer slot iff writerId is currently the active writer. Calls from non-active writers (a stale PdfFragment binder that already lost its slot to a swap) are silent no-ops.

Counterpart to saveState.

Snapshot for process-death restoration.

Restricts the docks the user may drag any contextual toolbar to — the Compose counterpart of the View ToolbarCoordinatorLayout.LayoutParams.allowedPositions a host set on the annotation toolbar. Applied to the bar shown now and to every bar shown later, so it survives mode changes; null (the default) clears the restriction.

Updates the shown contextual toolbar's most-recently-used item ranking (group representatives when no child is selected — see ContextualToolbarState.defaultChildIds). Silent no-op when none is shown.

Toggles the shown contextual toolbar's draggability (drag handle + drop zones) — the Compose counterpart of the View ContextualToolbar.setDraggable. Silent no-op when none is shown.

Sets (or clears, with null) the contextual toolbar grouping provider.

Moves the shown contextual toolbar to position. Silent no-op when none is shown.

Sets the document title overlay's title text and whether it is visible. The SDK drives this from the document title and its visibility conditions; Compose-only hosts can drive it directly.

Sets (or clears, with null) the programmatic main-toolbar color override.

The host's veto over the main toolbar's visibility — the Compose counterpart of the View MainToolbar.setForcedVisibility(GONE) hosts used to keep the SDK's bar hidden for good.

Sets the window insets the main toolbar reserves for its content (default ToolbarInsets.StatusBars). Pass ToolbarInsets.None when the toolbar is hosted away from the top edge of the window — e.g. an embedded com.pspdfkit.ui.PdfFragment below other chrome — so it does not add a spurious status-bar inset on top of the host's own spacing.

Java-friendly producer API for the main toolbar (used by PdfUiImpl now that the View toolbar and its bridge are gone). These wrap updateItems / updateFrame so the Java host doesn't have to construct Kotlin lambdas or call ToolbarFrame.copy.

Sets the main toolbar's navigation (up / back) icon and its accessibility label, or null to remove the affordance — the Compose counterpart of the AppCompat Toolbar.setNavigationIcon. The SDK's own toolbar renders it at the leading edge through com.pspdfkit.compose.toolbar.composables.NutrientMainToolbarNavigationIcon, the default navigationIcon slot of com.pspdfkit.compose.toolbar.composables.NutrientMainToolbar; a tap arrives as ToolbarAction.NavigationClicked (see addNavigationClickHandler).

Sets the main toolbar title, or null to clear it.

The producer's show/hide request for the main toolbar (immersive / inline-search visibility), rewritten by the SDK on every UI-visibility recompute. An embedding host that wants the bar hidden regardless uses setMainToolbarHostVisible, which this request is combined with.

Registers a legacy MenuItemGroupingRule with the Compose annotation creation toolbar — the deprecated successor of the View AnnotationToolbar.setMenuItemGroupingRule. Equivalent to the kind-scoped overload with ContextualToolbarKind.Annotation. Pass null to clear.

Registers a legacy MenuItemGroupingRule for one contextual toolbar kind — the deprecated successor of setting a rule on that kind's View toolbar instance (AnnotationToolbar, DocumentEditingToolbar). Only PresetMenuItemGroupingRule subclasses are honored (their getGroupPreset() is pure data); custom groupMenuItems(...) overrides cannot be bridged. Pass null to clear that kind's rule.

Registers (or clears, with null) the inline-search session.

Shows state as the contextual toolbar, replacing any currently shown one (a direct switch keeps the main-toolbar visibility interplay stable, matching the View ToolbarCoordinatorLayout behavior). A docking position saved for the same ContextualToolbarState.kind overrides state's position; positions saved for other kinds stay pending.

Transforms the shown contextual toolbar's items. Silent no-op when none is shown.

Producer-facing: replace the current frame.

Producer-facing: replace the current items.