--- title: "Annotation Toolbar: Item Grouping" canonical_url: "https://www.nutrient.io/guides/android/samples/annotation-toolbar-item-grouping-kotlin/" md_url: "https://www.nutrient.io/guides/android/samples/annotation-toolbar-item-grouping-kotlin.md" last_updated: "2026-11-02T14:08:15.330Z" description: "Reorganize contextual menu items on the annotation toolbar." --- # Annotation Toolbar: Item Grouping Reorganize contextual menu items on the annotation toolbar. [Get Started](https://www.nutrient.io/sdk/android/getting-started.md) [All Samples](https://www.nutrient.io/guides/android/samples.md) [Download](https://www.nutrient.io/guides/android/downloads.md) [Launch Demo](https://www.nutrient.io/demo/) --- ```kotlin /* * Copyright © 2016-2026 PSPDFKit GmbH. All rights reserved. * * The PSPDFKit Sample applications are licensed with a modified BSD license. * Please see License for details. This notice may not be removed from this file. */ @file:Suppress("DEPRECATION") package com.pspdfkit.catalog.examples.java import android.content.Context import android.net.Uri import android.os.Bundle import android.util.Log import android.widget.Toast import com.pspdfkit.catalog.R import com.pspdfkit.catalog.SdkExample import com.pspdfkit.catalog.tasks.ExtractAssetTask import com.pspdfkit.catalog.ui.CustomAnnotationCreationToolbarGroupingRule import com.pspdfkit.compose.toolbar.adapter.ToolbarSubscription import com.pspdfkit.compose.toolbar.state.ContextualToolbarKind import com.pspdfkit.compose.toolbar.state.ToolbarAction import com.pspdfkit.compose.toolbar.state.ToolbarIcon import com.pspdfkit.compose.toolbar.state.ToolbarItem import com.pspdfkit.configuration.activity.PdfActivityConfiguration import com.pspdfkit.jetpack.compose.toolbar.nutrientToolbarCoordinator import com.pspdfkit.jetpack.compose.toolbar.setMenuItemGroupingRule import com.pspdfkit.ui.PdfActivity import com.pspdfkit.ui.PdfActivityIntentBuilder import kotlinx.collections.immutable.mutate /** * Example of how to alter contextual toolbar menu items structure. Displayed on the annotation * creation toolbar. */ class AnnotationToolbarGroupingExample(context: Context) : SdkExample( context, R.string.annotationToolbarGroupingExampleTitle, R.string.annotationToolbarGroupingExampleDescription, ) { override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) { // We use a custom utility class to extract the example document from the assets. ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile -> val intent = PdfActivityIntentBuilder.fromUri(context, Uri.fromFile(documentFile)).configuration(configuration.build()).activityClass(AnnotationToolbarGroupingActivity::class.java).build() context.startActivity(intent) } } /** * This example shows how to add items to the annotation creation toolbar and apply a custom * grouping rule. See [CustomAnnotationCreationToolbarGroupingRule] for the applied grouping. */ class AnnotationToolbarGroupingActivity : PdfActivity() { /** Click subscription on the toolbar coordinator; closed in [onDestroy]. */ private var actionSubscription: ToolbarSubscription? = null /** Contextual-toolbar state subscription; closed in [onDestroy]. */ private var changeSubscription: ToolbarSubscription? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // The activity-scoped toolbar coordinator is the state container PdfActivity's Compose // toolbars run on — customizing the contextual (annotation) toolbar goes through it. val coordinator = nutrientToolbarCoordinator() // Register the grouping rule that tells the toolbar how to group its menu items. This // uses the deprecated MenuItemGroupingRule bridge so existing // PresetMenuItemGroupingRule subclasses keep working; new code should implement // ContextualToolbarGroupingProvider and register it with // coordinator.setContextualToolbarGroupingProvider(...) instead. coordinator.setMenuItemGroupingRule(this, CustomAnnotationCreationToolbarGroupingRule(this)) // The SDK rebuilds the annotation toolbar's item list every time the mode is entered, // so we observe the contextual toolbar state and (re-)apply our customizations on // every show. This replaces the legacy onPrepareContextualToolbar hook for the // annotation toolbar. The change listener needs no coroutine scope — it fires // synchronously on registration (with the current state) and on every change; a // View-based host just closes the subscription in onDestroy. changeSubscription = coordinator.addContextualToolbarChangeListener { state -> // The state carries which bar is shown and where it is docked; null means no // contextual toolbar is visible. Log.i(LOG_TAG, "Contextual toolbar changed: kind=${state?.kind} position=${state?.position}") if (state?.kind!= ContextualToolbarKind.Annotation) { return@addContextualToolbarChangeListener } // Append our custom "Bookmark" item — guarded so state updates after the // initial show (e.g. our own edit below) don't add it twice. if (state.items.none { it.id == R.id.pspdf_menu_custom }) { coordinator.updateContextualItems { items -> items.add( ToolbarItem.Button( actionId = "catalog.custom_bookmark", id = R.id.pspdf_menu_custom, contentDescription = "Bookmark", icon = ToolbarIcon.Resource(R.drawable.ic_bookmark), position = ToolbarItem.ItemEdge.Start, ), ) } } // The Compose counterpart of the legacy ContextualToolbar.setDraggable(false): // hides the drag handle and pins the toolbar to its current position. coordinator.setContextualToolbarDraggable(false) // Note: the legacy setUseBackButtonForCloseWhenHorizontal behavior is built in — // a top-docked bar leads with a back arrow, a side-docked one shows the circled // X. AnnotationToolbar.setShouldShowStylusButton(false) has no Compose // equivalent: the stylus toggle appears automatically while a stylus is // connected. } // Handle clicks on our custom item. Group taps and submenu child taps arrive as // SubmenuChildClicked, direct item taps as ItemClicked — our grouping rule keeps the // item standalone, but matching both is the robust pattern. actionSubscription = coordinator.addActionListener { action -> val clickedId = when (action) { is ToolbarAction.ItemClicked -> action.id is ToolbarAction.SubmenuChildClicked -> action.childId else -> null } if (clickedId == R.id.pspdf_menu_custom) { Toast.makeText(this, "Custom Action clicked", Toast.LENGTH_SHORT).show() // You can even hide menu items. This shows how to toggle the image menu item // by clicking on the custom button. Hidden items keep their slot logic but are // removed from the row, like View.GONE on the legacy toolbar. coordinator.updateContextualItems { items -> items.mutate { list -> val index = list.indexOfFirst { it.id == com.pspdfkit.R.id.pspdf__annotation_toolbar_item_image } if (index!= -1) { val item = list[index] list[index] = item.withVisible(!item.state.isVisible) } } } } } } private companion object { const val LOG_TAG = "CustomToolbarGrouping" } override fun onDestroy() { super.onDestroy() actionSubscription?.close() changeSubscription?.close() actionSubscription = null } /** Returns a copy of the item with [ToolbarItem.state]'s visibility flipped to [visible]. */ private fun ToolbarItem.withVisible(visible: Boolean): ToolbarItem = when (this) { is ToolbarItem.Button -> copy(state = state.copy(isVisible = visible)) is ToolbarItem.Toggle -> copy(state = state.copy(isVisible = visible)) is ToolbarItem.Submenu -> copy(state = state.copy(isVisible = visible)) } } } ``` This code sample is an example that illustrates how to use our SDK. Please adapt it to your specific use case. --- ## Related pages - [Add LTV to Existing Signature](/guides/android/samples/add-ltv-to-existing-signature-kotlin.md) - [AES Encrypted File](/guides/android/samples/aes-encrypted-file-java.md) - [AI Assistant (Multiple Documents, Compose)](/guides/android/samples/ai-assistant-multiple-documents-compose-kotlin.md) - [AI Assistant (Multiple Documents, ViewPager)](/guides/android/samples/ai-assistant-multiple-documents-viewpager-kotlin.md) - [AI Assistant (Single Document)](/guides/android/samples/ai-assistant-single-document-kotlin.md) - [Annotation Configuration](/guides/android/samples/annotation-configuration-kotlin.md) - [Annotation Creation](/guides/android/samples/annotation-creation-kotlin.md) - [Annotation Flags](/guides/android/samples/annotation-flags-kotlin.md) - [Annotation Overlay](/guides/android/samples/annotation-overlay-java.md) - [Annotation Rendering](/guides/android/samples/annotation-rendering-kotlin.md) - [Annotation Selection Styling](/guides/android/samples/annotation-selection-styling-kotlin.md) - [Annotation Sidebar](/guides/android/samples/annotation-sidebar-kotlin.md) - [Annotation Toolbar: Custom Items](/guides/android/samples/annotation-toolbar-custom-items-kotlin.md) - [Annotation Toolbar: User-Editable Tools](/guides/android/samples/annotation-toolbar-user-editable-tools-kotlin.md) - [Annotations with Transparency](/guides/android/samples/annotations-with-transparency-kotlin.md) - [Application Policy](/guides/android/samples/application-policy-kotlin.md) - [Bookmark Highlighting](/guides/android/samples/bookmark-highlighting-kotlin.md) - [Compose Image Document](/guides/android/samples/compose-image-document-kotlin.md) - [Compose Navigation](/guides/android/samples/compose-navigation-kotlin.md) - [Compose PDF Viewer](/guides/android/samples/compose-pdf-viewer-kotlin.md) - [Construction Floor Plan](/guides/android/samples/construction-floor-plan-kotlin.md) - [Custom Activity Form Editing](/guides/android/samples/custom-activity-form-editing-java.md) - [Custom Annotation Inspector](/guides/android/samples/custom-annotation-inspector-java.md) - [Custom Data Provider](/guides/android/samples/custom-data-provider-kotlin.md) - [Custom Download Dialog](/guides/android/samples/custom-download-dialog-java.md) - [Custom Electronic Signature](/guides/android/samples/custom-electronic-signature-java.md) - [Custom Form Highlight Color](/guides/android/samples/custom-form-highlight-color-java.md) - [Custom Layout](/guides/android/samples/custom-layout-kotlin.md) - [Custom Note Hinter](/guides/android/samples/custom-note-hinter-kotlin.md) - [Custom Outline Provider](/guides/android/samples/custom-outline-provider-kotlin.md) - [Custom Page Templates](/guides/android/samples/custom-page-templates-java.md) - [Custom Search UI (Compose)](/guides/android/samples/custom-search-ui-compose-kotlin.md) - [Custom Search UI (Views)](/guides/android/samples/custom-search-ui-views-java.md) - [Custom Settings, Info and Outline UI](/guides/android/samples/custom-settings-info-and-outline-ui-kotlin.md) - [Custom Sharing Dialog](/guides/android/samples/custom-sharing-dialog-java.md) - [Custom Sharing Menu](/guides/android/samples/custom-sharing-menu-java.md) - [Custom Stamp Annotations](/guides/android/samples/custom-stamp-annotations-java.md) - [Digital Signature (Basic)](/guides/android/samples/digital-signature-basic-kotlin.md) - [Digital Signature (Manual)](/guides/android/samples/digital-signature-manual-kotlin.md) - [Digital Signature (Third-Party)](/guides/android/samples/digital-signature-third-party-kotlin.md) - [Digital Signature (Two-Step)](/guides/android/samples/digital-signature-two-step-kotlin.md) - [Disabled Annotation Property](/guides/android/samples/disabled-annotation-property-java.md) - [Document Comparison](/guides/android/samples/document-comparison-kotlin.md) - [Document Download](/guides/android/samples/document-download-kotlin.md) - [Document from Canvas](/guides/android/samples/document-from-canvas-kotlin.md) - [Document Processing](/guides/android/samples/document-processing-kotlin.md) - [Document Sharing](/guides/android/samples/document-sharing-java.md) - [Document Switcher](/guides/android/samples/document-switcher-java.md) - [DocumentView Composable](/guides/android/samples/documentview-composable-kotlin.md) - [DocumentView in a Dialog](/guides/android/samples/documentview-in-a-dialog-kotlin.md) - [Download Progress](/guides/android/samples/download-progress-kotlin.md) - [Dynamic Pages on Scroll](/guides/android/samples/dynamic-pages-on-scroll-kotlin.md) - [E-Learning](/guides/android/samples/e-learning-kotlin.md) - [Electronic + Digital Signing](/guides/android/samples/electronic-digital-signing-kotlin.md) - [External Document](/guides/android/samples/external-document-kotlin.md) - [File Annotation Creation](/guides/android/samples/file-annotation-creation-kotlin.md) - [Filterable Thumbnail Grid](/guides/android/samples/filterable-thumbnail-grid-kotlin.md) - [Form Click Intercept (Compose)](/guides/android/samples/form-click-intercept-compose-kotlin.md) - [Form Creation](/guides/android/samples/form-creation-kotlin.md) - [Form Filling](/guides/android/samples/form-filling-kotlin.md) - [Forms with JavaScript](/guides/android/samples/forms-with-javascript-kotlin.md) - [Fragment Runtime Configuration](/guides/android/samples/fragment-runtime-configuration-kotlin.md) - [Generate PDF Report](/guides/android/samples/generate-pdf-report-kotlin.md) - [Hide and Reveal Areas](/guides/android/samples/hide-and-reveal-areas-kotlin.md) - [HTML-to-PDF Conversion](/guides/android/samples/html-to-pdf-conversion-kotlin.md) - [Image Document](/guides/android/samples/image-document-kotlin.md) - [Inline Multimedia](/guides/android/samples/inline-multimedia-kotlin.md) - [Instant Document JSON](/guides/android/samples/instant-document-json-kotlin.md) - [Instant JSON Attachment](/guides/android/samples/instant-json-attachment-kotlin.md) - [JavaScript Actions](/guides/android/samples/javascript-actions-kotlin.md) - [JavaScript Calculator](/guides/android/samples/javascript-calculator-kotlin.md) - [JavaScript Form Filling](/guides/android/samples/javascript-form-filling-kotlin.md) - [Kiosk Grid](/guides/android/samples/kiosk-grid-kotlin.md) - [LTV Signature](/guides/android/samples/ltv-signature-kotlin.md) - [Main Toolbar: Custom Layout & Items](/guides/android/samples/main-toolbar-custom-layout-items-kotlin.md) - [Main Toolbar: FAB Menu (M3 Expressive)](/guides/android/samples/main-toolbar-fab-menu-m3-expressive-kotlin.md) - [Main Toolbar: Floating Pill (M3 Expressive)](/guides/android/samples/main-toolbar-floating-pill-m3-expressive-kotlin.md) - [Measurement Tools](/guides/android/samples/measurement-tools-kotlin.md) - [Memory Pressure Recovery](/guides/android/samples/memory-pressure-recovery-kotlin.md) - [Merge Documents](/guides/android/samples/merge-documents-kotlin.md) - [Multimedia Annotations](/guides/android/samples/multimedia-annotations-kotlin.md) - [Multiple Documents (Compose Pager)](/guides/android/samples/multiple-documents-compose-pager-kotlin.md) - [OCR](/guides/android/samples/ocr-kotlin.md) - [Overlay Views](/guides/android/samples/overlay-views-kotlin.md) - [Overlay Visibility](/guides/android/samples/overlay-visibility-kotlin.md) - [Password Protected PDF](/guides/android/samples/password-protected-pdf-kotlin.md) - [PDF from Image](/guides/android/samples/pdf-from-image-kotlin.md) - [PdfFragment](/guides/android/samples/pdffragment-kotlin.md) - [PdfUiFragment](/guides/android/samples/pdfuifragment-kotlin.md) - [Playground](/guides/android/samples/playground-kotlin.md) - [Popup Toolbar: Custom Items](/guides/android/samples/popup-toolbar-custom-items-kotlin.md) - [Programmatic Zoom](/guides/android/samples/programmatic-zoom-kotlin.md) - [Reader View](/guides/android/samples/reader-view-kotlin.md) - [Remote URL](/guides/android/samples/remote-url-kotlin.md) - [Replace and Refresh Documents](/guides/android/samples/replace-and-refresh-documents-kotlin.md) - [Runtime Configuration](/guides/android/samples/runtime-configuration-kotlin.md) - [Scientific Paper](/guides/android/samples/scientific-paper-kotlin.md) - [Screen Reader](/guides/android/samples/screen-reader-java.md) - [Search Indexing](/guides/android/samples/search-indexing-kotlin.md) - [Selection Customization](/guides/android/samples/selection-customization-java.md) - [Signature Parcelize](/guides/android/samples/signature-parcelize-kotlin.md) - [Signature Storage Database](/guides/android/samples/signature-storage-database-kotlin.md) - [Sound Extraction](/guides/android/samples/sound-extraction-kotlin.md) - [Split Screen (Compose)](/guides/android/samples/split-screen-compose-kotlin.md) - [Split View](/guides/android/samples/split-view-java.md) - [Tabbed Documents (Compose)](/guides/android/samples/tabbed-documents-compose-kotlin.md) - [Tabbed Documents](/guides/android/samples/tabbed-documents-kotlin.md) - [Tabbed Documents (Persistent)](/guides/android/samples/tabbed-documents-persistent-kotlin.md) - [Text Field Suggestions](/guides/android/samples/text-field-suggestions-kotlin.md) - [Thumbnail Bar Modes](/guides/android/samples/thumbnail-bar-modes-kotlin.md) - [Try Instant](/guides/android/samples/try-instant-kotlin.md) - [UI View Modes](/guides/android/samples/ui-view-modes-kotlin.md) - [Vertical Scrollbar](/guides/android/samples/vertical-scrollbar-java.md) - [Watermarks](/guides/android/samples/watermarks-kotlin.md) - [XFDF Import/Export](/guides/android/samples/xfdf-import-export-kotlin.md)