> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/xamarin/viewer/new-ui-integration-x.md).

# Integrate the new Viewer UI

Learn how to integrate the new Viewer UI in Xamarin.Android with this comprehensive guide. Follow step-by-step instructions for adding the viewer with the new UI and migrating from your existing viewe

{% tabs %}
{% tab title="Android" %}

## Integrate the new Viewer UI in Xamarin.Android

If you are newly adding the document viewer into your app, you can follow this guide to add the viewer with the new UI. If you are looking to migrate from the your viewer in your app to use the new UI, you can follow this ui migration guide.

## Integrate via Fragment

To use the new drop-in viewer fragment, create a [`PdfViewCtrlTabHostFragment2`](https://sdk.apryse.com/api/xamarinandroid/tools/api/pdftron.PDF.Controls.PdfViewCtrlTabHostFragment2.html) using the new `ViewerBuilder2` class.

{% code lineNumbers="true" %}

```csharp
// Add a viewer fragment to the layout container in the specified 
// activity, and returns the added fragment
public PdfViewCtrlTabHostFragment2 AddViewerFragment(int fragmentContainer, 
            AppCompatActivity activity, Android.Net.Uri fileUri, String password)
{
    // Create the viewer fragment
    PdfViewCtrlTabHostFragment2 fragment = (PdfViewCtrlTabHostFragment2)ViewerBuilder2.WithUri(fileUri, password).Build(activity);

    // Add the fragment to the layout fragment container
    activity.SupportFragmentManager.BeginTransaction()
            .Replace(fragmentContainer, fragment)
            .Commit();

    return fragment;
}
```

{% endcode %}

## Integrate via Activity

A new builder class `DocumentActivity.IntentBuilder` has been added to help you more easily customize the activity document viewer. You can also use this new builder to specify the viewer to use the new UI as follows:

{% code lineNumbers="true" %}

```csharp
private void OpenContentUriDocument(Context context, Android.Net.Uri contentUri)
{
    Intent intent = DocumentActivity.IntentBuilder.FromActivityClass(this, Java.Lang.Class.FromType(typeof(DocumentActivity)))
        .WithUri(contentUri)
        .UsingNewUi(true)
        .Build();
    StartActivity(intent);
}
```

{% endcode %}

## Building a custom annotation toolbar

Buttons in the annotation toolbar can be customized using the `AnnotationToolbarBuilder` API. The buttons on the annotation toolbar are contained in two groups: the scrollable region (left) and the sticky region (right). The scrollable region can contain any number of buttons and scrolling is used to access buttons that are off-screen. Buttons in the sticky region will always show on the screen and will not be scrollable.

For example, built-in PDF tool buttons can be added to a viewer as follows:

{% code lineNumbers="true" %}

```csharp
// Supply a unique tag for the toolbar that will be referenced internally
AnnotationToolbarBuilder builder = AnnotationToolbarBuilder.WithTag("my_unique_annotate_toolbar_tag")
    // Set a display name for this toolbar
    .SetToolbarName("Text Annotate")
    // Adds three tool buttons (text highlight, freehand highlight, and text underline) to the scrollable region (left)
    .AddToolButton(ToolbarButtonType.TextHighlight, DefaultToolbars.ButtonId.TextHighlight.Value())
    .AddToolButton(ToolbarButtonType.FreeHighlight, DefaultToolbars.ButtonId.FreeHighlight.Value())
    .AddToolButton(ToolbarButtonType.TextUnderline, DefaultToolbars.ButtonId.TextUnderline.Value())
    // Adds two tool buttons (undo and redo) to the sticky region
    .AddToolStickyButton(ToolbarButtonType.Undo, DefaultToolbars.ButtonId.Undo.Value())
    .AddToolStickyButton(ToolbarButtonType.Redo, DefaultToolbars.ButtonId.Redo.Value());

// Then supply the builder to ViewerConfig, which will be passed on to your viewer
ViewerConfig config = new ViewerConfig.Builder()
    // Add out custom annotation toolbar
    .AddToolbarBuilder(builder)
    // Other ViewerConfig settings...
    .Build();
```

{% endcode %}

Afterwards, you can supply this `AnnotationToolbarBuilder` to the viewer `using the ViewerConfig class`.

If you would like to add a button with custom functionality, you can add a generic button as so:

{% code lineNumbers="true" %}

```csharp
AnnotationToolbarBuilder.WithTag("my_unique_annotate_toolbar_tag")
        // Here we add a button with custom title, icon, and an id of 1000. 
        // This id will be referenced when implementing callbacks
        .AddCustomButton(Resource.String.custom_title, Resource.Drawable.custom_icon, 1000);
```

{% endcode %}

Then you can listen for annotation toolbar button events by adding a `PdfViewCtrlTabHostFragment2.TabHostListener`:

{% code lineNumbers="true" %}

```csharp
mPdfViewCtrlTabHostFragment.ToolbarOptionsItemSelected += (sender, e) =>
{
    // The button id defined previously in the AnnotationToolbarBuilder
    var id = e.P0.ItemId;
    e.Handled = false;
};
```

{% endcode %}
{% endtab %}

{% tab title="iOS" %}

## Integrate the new Viewer UI in Xamarin.iOS

{% hint style="warning" %}
**If you are migrating from an existing implementation, please see the migration guide.**
{% endhint %}

## Single document viewer

Follow the existing guides, using a `PTDocumentController` instead of a `PTDocumentViewController`.

## Tabbed document viewer

Create a `PTTabbedDocumentViewController` as described in the guides, and then set its `viewControllerClass` property to the `PTDocumentController` class:

{% code lineNumbers="true" %}

```csharp
tabbedDocumentViewController.ViewControllerClass = new ObjCRuntime.Class(typeof(PTDocumentController));
```

{% endcode %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apryse.com/xamarin/viewer/new-ui-integration-x.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.