What is it?
The ScrollArea widgets enable you to show content on a page that is larger than widget itself, or even larger than the screen. There are three ScrollArea widgets that behave identically except for constraints on their scrollability:
|HScrollArea||Enables the user to scroll horizontally|
|VScrollArea||Enables the user to scroll vertically|
|HVScrollArea||Enables the user to scroll in both dimensions simultaneously|
In this document, we will use the HVScrollArea widget. We'll also use the following image - feel free to download it.
Then upload this (or another large image) to your app using the Files tool. See the help on the Image widget if you are not sure how to do this.
How do I use it?
Go to the Layout tool and click on the ScrollArea tab in the widgets panel on the left. Remember that clicking on the 'i' button will give you some more information on the widget. Then scroll down the right hand side of the sub-panel until HVScrollArea comes into view.
Drag the HVScrollArea widget from the widget panel onto the page canvas:
The area outlined in yellow is the selected HVScrollArea widget. You can now resize and reposition the widget if you like.
To add content to the HVScrollArea, click on the button labelled Edit in the middle of the widget. The central panel on the Layout tool now changes to become a canvas for the HVScrollArea widget rather than for the page it is on.
We want to put the image of Whitby Abbey on this canvas. Knowing the image is 900x600px, use the property panel to set the canvas height and width of the HVScrollArea canvas to those dimensions:
Unless you have a very large screen, the HVScrollArea canvas in the middle of the Layout tool has probably acquired scroll bars now to let you move around the canvas.
Now add an Image widget to the canvas by clicking the Image tab in the widgets panel and dragging the widget icon to the ScrollArea canvas.We need that to be 900x600px too, but rather than use the property panel, we will use a handy shortcut. Select the image widget and click on the Dock button in the menu just above the panels.
Select Fill from the dropdown and the Image widget will expand to fill the whole of the HVScrollArea canvas. With the Image widget still selected, go to the Settings tab of the property panel and use the image dropdown to select the file you have uploaded. Set the image size dropdown to stretch so that the image fills the Image widget. Finally, click the Back to page Page 1 button at the top of the ScrollArea canvas.
It is probably worth recapping what we have now. On the page is a HVScrollArea with width and height both set to 320px. Inside that HVScrollArea is a canvas with dimensions 900x600px. On that canvas is an Image widget also of size 900x600px which is set to show your uploaded image. The end effect of that arrangement is that you will see only a portion of the image on the page:
Now if your preview the app by clicking the Preview button, you should be able to scroll around the image within the part of the page defined by the HVScrollArea widget:
Note that the scrollbars that appear in the preview are different to those that appear on the real device. In fact, for the HVScrollArea, no scrollbars appear at all. That difference between the preview and the device is one that we will try to iron out in a future update to preview..
And that's it. In this simple example, we added only one Image widget to the HVScrollArea canvas. However, there is no limitation to a single widget. You can add as many other widgets as you like - even other ScrollArea widgets - just as you can for a page canvas. We encourage you to explore further.
What properties does it have?
A ScrollArea widget's set of properties are a bit different from other widgets. The HVScrollArea itself has very few properties - just those needed to specify its size, position and visibility. These few properties behave just as for other widgets.
However, the canvas within the HVScrollArea widget (revealed when you click on the Edit button) also has a set of properties. For the most part, these are also shared with other widgets. There are two more specific properties in its Settings tab:
The width of the canvas within the ScrollArea upon which you can place widgets
The height of the canvas within the ScrollArea upon which you can place widgets
Remember that these are not the same properties as the width and height of the HVScrollArea itself, which define the viewport though which the canvas is viewed.
How can I use it in code?
At the moment, it is not possible to interact with any of the ScrollArea widgets through code. That capability is something we hope to make available in a future update.