Customizing Menus

You can modify PSPDFKit’s menus by adding new actions or removing existing actions. For code examples, see CustomActionsExample (Java) or CustomActionsKotlinExample (Kotlin) from our example catalog.

Modifying the Action Bar

If you are using the PdfActivity or a custom subclass of this activity, PSPDFKit will automatically show toolbar actions based on the loaded configuration. PSPDFKit uses the default support Toolbar widget together with a dynamically populated Menu.

Default actions: Annotation editing, outline, searching, sharing, thumbnails, and the overflow menu.

Adding Custom Actions

To add custom actions to existing actions, you need to use a custom activity class and override the #onPrepareOptionsMenu method:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
class CustomActivity : PdfActivity() {
    public override fun onPrepareOptionsMenu(menu: Menu): Boolean {
        // Call the super implementation so PSPDFKit can add its own icons to the menu. This has
        // to be called first or your own menu items won't appear.
        super.onPrepareOptionsMenu(menu)

        // Add your custom actions to the menu. We recommend inflating them from a menu resource,
        // but you could also create them programmatically.
        menuInflater.inflate(R.menu.custom_menu, menu)

        // Make sure to return true if you want the ActionBar to display your actions.
        return true
    }
}
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
public class CustomActivity extends PdfActivity {
    @Override public boolean onPrepareOptionsMenu(Menu menu) {
        // Call the super implementation so PSPDFKit can add its own icons to the menu. This has
        // to be called first or your own menu items won't appear.
        super.onPrepareOptionsMenu(menu);

        // Add your custom actions to the menu. We recommend inflating them from a menu resource,
        // but you could also create them programmatically.
        getMenuInflater().inflate(R.menu.custom_menu, menu);

        // Make sure to return true if you want the ActionBar to display your actions.
        return true;
    }
}

ℹ️ Note: Your activity has to override the #onPrepareOptionsMenu method (not the #onCreateOptionsMenu method) in order to make the activity show the actions.

Specifying the Position for Custom Actions

To add a custom action at a specific position, your activity has to override the #onGenerateMenuItemIds() method. From there, you can control at which position the custom item should be inserted. Below is an example of how to insert a custom menu item directly after the outline button:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class CustomActivity : PdfActivity() {
    override fun onGenerateMenuItemIds(menuItems: MutableList<Int>): List<Int> {
        // First, we get an index of the outline button.
        val indexOfOutlineButton = menuItems.indexOf(PdfActivity.MENU_OPTION_OUTLINE)

        // Add items after the outline button.
        menuItems.add(
            indexOfOutlineButton + 1,
            R.id.custom_action // Your custom action ID.
        )

        // Return the new order for menu items.
        return menuItems
    }
}
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public class CustomActivity extends PdfActivity {
    @Override
    public List<Integer> onGenerateMenuItemIds(@NonNull List<Integer> menuItems) {
        // First, we get an index of the outline button.
        int indexOfOutlineButton = menuItems.indexOf(MENU_OPTION_OUTLINE);

        // Add items after the outline button.
        menuItems.add(
            indexOfOutlineButton + 1,
            R.id.custom_action // Your custom action ID.
        );

        // Return the new order for menu items.
        return menuItems;
    }
}

Default Menu Option IDs

Here are the IDs for all the menu options from the main action bar. You can reference them using PdfActivity:

ID Default Action
MENU_OPTION_EDIT_ANNOTATIONS Enters annotation editing mode.
MENU_OPTION_OUTLINE Shows PdfOutlineView with bookmarks, document info, an outline, and the annotation list.
MENU_OPTION_SEARCH Enters the search document contents mode.
MENU_OPTION_SETTINGS Shows the document settings menu.
MENU_OPTION_SHARE Shows the share dialog.
MENU_OPTION_THUMBNAIL_GRID Enters document editor mode.

Removing Default Actions

To remove default actions (search, share, document settings, etc.), you need to override the #onPrepareOptionsMenu method and find the action you want to modify by its ID. Here is an example that hides the search action:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
class CustomActivity : PdfActivity() {
    public override fun onPrepareOptionsMenu(menu: Menu): Boolean {
        // Call the super implementation so PSPDFKit can add its own icons to the menu. This has
        // to be called first or your changes will be overwritten.
        super.onPrepareOptionsMenu(menu)

        // Finds the search action by its ID and hides it.
        menu.findItem(PdfActivity.MENU_OPTION_SEARCH).isVisible = false

        // Make sure to return true to apply your changes.
        return true
    }
}
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
public class CustomActivity extends PdfActivity {
    @Override public boolean onPrepareOptionsMenu(Menu menu) {
        // Call the super implementation so PSPDFKit can add its own icons to the menu. This has
        // to be called first or your changes will be overwritten.
        super.onPrepareOptionsMenu(menu);

        // Finds the search action by its ID and hides it.
        menu.findItem(PdfActivity.MENU_OPTION_SEARCH).setVisible(false);

        // Make sure to return true to apply your changes.
        return true;
    }
}

ℹ️ Note: Your activity has to override the #onPrepareOptionsMenu method (not the #onCreateOptionsMenu method) in order to make the activity apply the desired changes.

Keep in mind that manipulating menu items through #onPrepareOptionsMenu will not affect certain initialization steps performed for actions they represent, and it will still be possible to trigger those actions programmatically. For example, removing the search action as described above will still initialize SearchView under the hood, and it can still be invoked programmatically.

If you want not only to remove a certain action from the menu but also to completely disable the functionality it represents, use one of the following PdfActivityConfiguration options:

Configuration Option Result
disableAnnotationEditing() Disables annotation editing and removes all related UI elements.
disableOutline() Disables the outline and removes all related UI elements.
disableSearch() Disables search functionality and removes all related UI elements.
hideSettingsMenu() Removes the settings menu.
setEnabledShareFeatures(ShareFeatures.none()) Disables share functionality and removes all related UI elements.
hideThumbnailGrid() Disables the thumbnail grid and removes all related UI elements.

Customizing the Document Settings Menu

You can control which items will be shown in a document settings menu (see the default version below).

To specify which items should be shown in this menu, use PdfActivityConfiguration.Builder#setSettingsMenuItems. For example, the following code will result in the settings menu showing only the page transition, page layout, and document theme:

Copy
1
2
3
4
5
6
configuration.setSettingsMenuItems(EnumSet.of(
    SettingsMenuItemType.THEME,
    SettingsMenuItemType.PAGE_LAYOUT,
    SettingsMenuItemType.PAGE_TRANSITION
    )
)
Copy
1
2
3
4
5
6
configuration.setSettingsMenuItems(EnumSet.of(
    SettingsMenuItemType.THEME,
    SettingsMenuItemType.PAGE_LAYOUT,
    SettingsMenuItemType.PAGE_TRANSITION
    )
)

The result will look like the following.

To exclude the settings menu completely, you can use PdfActivityConfiguration.Builder#hideSettingsMenu:

1
configuration.hideSettingsMenu()
1
configuration.hideSettingsMenu()

Adding an Action to the Share Menu

By overriding the #onPrepareOptionsMenu method, you can also add actions to submenus — for example, to the share menu. To do so, first fetch the menu item via its ID, PdfActivity.MENU_OPTION_SHARE, and then add your action to its submenu:

1
2
val shareMenu = menu.findItem(PdfActivity.MENU_OPTION_SHARE).subMenu
shareMenu.add(0, R.id.my_custom_action, 0, "My custom share action")
Copy
1
2
final SubMenu shareMenu = menu.findItem(PdfActivity.MENU_OPTION_SHARE).getSubMenu();
shareMenu.add(0, R.id.my_custom_action, 0, "My custom share action");