Scrollbars

PSPDFKit comes with out-of-the-box scrollbars indicating the current scroll position and remaining scroll range (i.e. the remaining pages in the document). You can change the scrollbar's default visual appearance, turn scrollbars off if you don't need them, or replace them completely with your own custom scrollbar logic using scroll event listeners.

Disabling Scrollbars

By default, the PdfFragment shows vertical and horizontal scrollbars. If you are using the PdfActivity, you can disable these scrollbars by setting PdfActivityConfiguration.Builder#scrollbarsEnabled to false:

1
2
3
val config = PdfActivityConfiguration.Builder(context)
    .scrollbarsEnabled(false)
    .build()
Copy
1
2
3
4
final PdfActivityConfiguration config
    = new PdfActivityConfiguration.Builder(context)
        .scrollbarsEnabled(false)
        .build();

If you are using the PdfFragment instead of the activity, you can disable scrollbars using the equivalent method PdfConfiguration.Builder#scrollbarsEnabled.

1
2
3
val config = PdfConfiguration.Builder()
    .scrollbarsEnabled(false)
    .build()
1
2
3
4
final PdfConfiguration config
    = new PdfConfiguration.Builder()
        .scrollbarsEnabled(false)
        .build();

Styling the scrollbars

It is possible to change the appearance of scrollbars by using a custom theme. Set the pspdf__documentViewStyle attribute of the theme to a style containing all your desired scrollbar properties. Since PSPDFKit uses the default scrollbars of the View class, you can use all of the existing scrollbar properties defined by that class.

Copy
styles.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- Your custom PSPDFKit theme. -->
<style name="MyApp.Theme" parent="Theme.AppCompat.NoActionBar">
    <item name="pspdf__documentViewStyle">@style/MyApp_DocumentViewStyle</item>
</style>

<!-- Your scrollbar styles can go here. -->
<style name="MyApp_DocumentViewStyle">
    <item name="android:scrollbarSize">6dp</item>
    <item name="android:scrollbarThumbVertical">@color/my_scrollbar_color</item>
    <item name="android:scrollbarThumbHorizontal">@color/my_scrollbar_color</item>
    <item name="android:scrollbarStyle">insideOverlay</item>
    <item name="android:scrollbars">horizontal|vertical</item>
</style>

The above scrollbar style only contains a subset of the existing scrollbar properties. For a full list of available style attributes have a look at the available View attributes in the official Android documentation. If you are interested in some live example, check out the DarkThemeExample inside the catalog app.

Tip: If you are interested in the default scrollbar style, see @style/PSPDFKit.DocumentView, which is automatically used by PSPDFKit if your theme does not define a different style.

Document scroll listeners

If the default scrollbars don't provide the features your app requires, you can use a DocumentScrollListener to observe scrollbar events on the fragment. Once you register the listener using PdfFragment#addDocumentScrollListener it receives all raw scrollbar events for consumption of your own scrollbar code.

1
2
val myListener: DocumentScrollListener = MyScrollListener()
fragment.addDocumentScrollListener(myListener)
1
2
final DocumentScrollListener myListener = new MyScrollListener();
fragment.addDocumentScrollListener(myListener);

Note: To prevent undesired leaks, the PdfFragment removes all registered DocumentScrollListener instances inside its #onDetach method. This means that you need to register your listener every time the fragment is attached to your activity (for example at activity creation time). You are encouraged to manually unregister document scroll listener if you do not longer need them using PdfFragment#removeDocumentScrollListener.

Scrollbar events

Document scrollbar events consist of three different values. A DocumentScrollListener will receive those values inside its #onDocumentScrolled method. For each value there is a X and Y dimension, since the document can scroll both vertically and horizontally. The received values are expressed in an arbitrary 0-based unit, and should only be treated in relation to each other. The values are:

  • Range: The total scrollable range inside the document. Range is expressed by maxX and maxY.
  • Offset: The current scrollbar position, is always inside the range. Offset is expressed by currX and currY.
  • Extend: The relative size of the scrollbar, compared to the total range. Extend is expressed by extendX and extendY.
Copy
1
2
3
override fun onDocumentScrolled(fragment: PdfFragment, currX: Int, currY: Int, maxX: Int, maxY: Int, extendX: Int, extendY: Int) {
    // Your custom scrollbar code.
}
Copy
1
2
3
4
@Override
public void onDocumentScrolled(@NonNull PdfFragment fragment, int currX, int currY, int maxX, int maxY, int extendX, int extendY) {
    // Your custom scrollbar code.
}

The current document scrolling state (dragged, settling, idle) is represented by the ScrollState enum type. The DocumentScrollListener can observe changes of the document scroll state inside its #onScrollStateChanged method.

1
2
3
override fun onScrollStateChanged(fragment: PdfFragment, state: ScrollState) {
    // Consume scroll state changes here.
}
Copy
1
2
3
4
@Override
public void onScrollStateChanged(@NonNull PdfFragment fragment, @NonNull ScrollState state) {
    // Consume scroll state changes here.
}

If you want to see a live demo of custom scrollbar events, have a look a the VerticalScrollbarExample inside the catalog app. It shows how to use the new scroll API together with the VerticalScrollBar widget, to allow quick document navigation.