Customizing the toolbar in our UWP viewer

Nutrient comes with a very useful toolbar by default, but it’s also important for individuals to modify toolbar items to suit their needs. As such, it’s possible to add, remove, and reorder all the buttons on the toolbar, and there are also more advanced options, like the responsive grouping of buttons and custom icons.

Adding a toolbar item

The next section covers how to add a toolbar item.

Built-in toolbar items

There are many built-in toolbar items available. A list of these can be found in the API reference. The following code shows how to add a single built-in item:

var toolbarItems = PdfView.GetToolbarItems();
toolbarItems.Add(new PagerToolbarItem());
await PdfView.SetToolbarItemsAsync(toolbarItems);

In some instances, you might want to configure how the toolbar looks or set it up in a particular order. To do this, you can create an IList of IToolbarItems and pass this to PdfView.SetToolbarItemsAsync. The ordering of the buttons is determined by the order of the container:

var defaultToolbarItems = new List<IToolbarItem>
{
    new SidebarThumbnailsToolbarItem(),
    new SidebarDocumentOutlineToolbarItem(),
    new SidebarAnnotationToolbarItem(),
    new PagerToolbarItem(),
    new LayoutConfigToolbarItem(),
    new PanToolbarItem(),
    new ZoomOutToolbarItem()
};
await PdfView.SetToolbarItemsAsync(defaultToolbarItems);

Some built-in items are automatically grouped together with a dropdown arrow. For example, all the sidebar options are located under the same button, all line drawing annotations will be grouped together, and the highlighter and ink tool can be found under the same button.

Also note that excluding annotation items will not affect the user’s editing capabilities for existing annotations of the specified type. This guide offers more information on controlling annotation editing capabilities.

Custom toolbar items

Along with the useful built-in toolbar items, we have also made it possible to provide your own custom toolbar items. Currently, you can define a ButtonToolbarItem and a ToggleButtonToolbarItem. The ButtonToolbarItem is a one-shot button that has no state, whereas the ToggleButtonToolbarItem has a state in which it can either be selected or not. This will be shown in the UI via a change of color. These buttons are added in the same way, so we’ll only show the ButtonToolbarItem example here:

var toolbarItem = new ButtonToolbarItem()
{
    Attributes =
    {
        Id = "id",
        Title = "title",
        ClassName = "class-name",
        ResponsiveGroup = "responsive-group",
        MediaQueries = new List<string> { "max-width" },
    },
    Disabled = false,
    Icon = new Uri("ms-appx-web:///Assets/ToolbarIcons/status_completed.svg")
};
toolbarItem.OnItemPressEvent += ToolbarItem_OnPressAsync;

var toolbarItems = PdfView.GetToolbarItems();
toolbarItems.Add(toolbarItem);
await PdfView.SetToolbarItemsAsync(toolbarItems);

Set the Id to ensure the correct onPress listener is called, and set a Title to be shown. Note that if an Icon is defined, the title will be used to show a hint if the mouse hovers over the icon button. OnItemPressEvent has a function callback assigned to receive notifications when the user clicks the custom button. The toolbar item can then be inserted into the list of toolbar items. The position of the item in the list determines the position where it appears on the toolbar. The Selected property of ToggleButtonToolbarItem denotes whether or not the item is selected. It can also be queried at runtime.

Removing a toolbar item

Removing an item from the toolbar is even simpler than adding an item is:

var toolbarItems = PdfView.GetToolbarItems();
toolbarItems.RemoveAt(0);
await PdfView.SetToolbarItemsAsync(toolbarItems);

The code above will remove the item at position zero, i.e. it will remove the item at the start of the toolbar. Extra logic can be applied to find the required item and remove it from the list before SetToolbarItemsAsync.

Reordering the toolbar items

As seen when adding and removing items, the order is determined by the order an item is inserted into the list. As such, you can simply reorder the items on the toolbar by reordering the items in the list. The following example shows how to randomly shuffle the items on the toolbar:

var toolbarItems = PdfView.GetToolbarItems();
var shuffledList = toolbarItems.OrderBy(a => Guid.NewGuid()).ToList();
await PdfView.SetToolbarItemsAsync(shuffledList);

Responsive group

As the size of screen is not often known, it is great to have the ability to dynamically hide toolbar items dependent upon a given metric. With Nutrient, you can define a ResponsiveGroupToolbarItem item that other IToolbarItems can reference in order to create a collapsed grouping:

var responsiveGroup = new ResponsiveGroupToolbarItem
{
    Attributes =
    {
        Id = "my-group",
        MediaQueries = new List<string> { "(max-width:4000px)" },
        Title = "Responsive"
    }
};

var toolbarItem = new PagerToolbarItem
{
    Attributes =
    {
        ResponsiveGroup = "my-group"
    }
};
toolbarItem.OnItemPressEvent += ToolbarItem_OnPressAsync;

var toolbarItems = PdfView.GetToolbarItems();
toolbarItems.Insert(0, responsiveGroup);
toolbarItems.Add(toolbarItem);
await PdfView.SetToolbarItemsAsync(toolbarItems);

If the view is less than 600px wide, then the ResponsiveGroupToolbarItem will be shown at index 0. When the responsive group button is pressed, the custom button is revealed. But when the view is larger than 600px wide, the button will be shown as normal.

Dropdown group

The grouping of toolbar items can save space in the toolbar and make for logical grouping specific to your custom UI. A good example of this is how, by default, Ink, Highlighter, and TextHighlighter appear as one item with an arrow by the side.

It’s possible to override this behavior and/or create your own groupings.

To add your own group, simply set the DropdownGroup string. Each subsequent item that also has a DropdownGroup of the same string will be grouped together:

// Create an arrow toolbar item in the dropdown group of `my-group`.
var arrowToolbarItem = new ArrowToolbarItem()
{
    Attributes =
    {
        DropdownGroup = "my-group",
    }
};

Some default items are already part of a default dropdown group. To override this behavior, simply set DropdownGroup with an empty string:

// Create an ellipse toolbar item without a dropdown group.
var ellipseToolbarItem = new EllipseToolbarItem()
{
    Attributes =
    {
        DropdownGroup = "",
    }
};