I was somewhat surprised to find that JavaFX does not come with a scrollbar component out of the box (if you’re reading this from the future, I’m currently using JavaFX 1.1 with NetBeans 6.5.1.) There are some examples out there for rolling your own — which I haven’t personally tested — such as using a SwingSlider, a component sadly unavailable on the Mobile profile, or a customized mouse-aware Rectangle, but I wanted to create something as near to the desktop experience as I could (easily) manage. If you’re looking for a free vertical scrollbar solution for your JavaFX Mobile application, please read on.
Update: Good news! JavaFX 1.2 has built-in support for scrollbars (and a number of other controls) in the new javafx.scene.control package. These are available in the common profile as well as the desktop profile, so mobile developers now have a set of skinnable GUI controls that should work consistently across the desktop, the web, and mobile devices.
How to use
It’s quite likely that if you’re reading this you’re already familiar with the operation of a scrollbar, so I’ll skip that bit. This particular implementation contains the latest in scrollbar technology, such as adjusting the height of the cursor to match the size of the display relative to the size of the document and performing page up/page down operations when the scrollbar is clicked between the cursor and the top/bottom of the bar. I’ve commented the source quite thoroughly, so hopefully you’ll find it fairly straightforward to use and modify as you wish, but here’s how it works out of the box:
- Copy VerticalScrollBar.fx into your project. Remember to change the “package” line near the top of the file to fit your project layout.
- Create the object, passing any of the following parameters:
- x: “x” position of scrollbar on screen (bar is 10 pixels wide)
- y: “y” position of scrollbar on screen
- height: Height of scrollbar on screen
- areaHeight: Height of on-screen display (visible area of document)
- rangeLow: Lowest setting on scrollbar (typically should be 0.0)
- rangeHigh: Highest setting on scrollbar (typically height of document)
- value: Current value of the scrollbar (position in document).
- clickStep: Number of pixels to scroll when up/down arrow clicked on scrollbar
- Create the document. This can be Text, Group, or any other type of Node. If your viewing area doesn’t extend from the top to the bottom of the screen, you may need to set the clip property on your document object(s) to prevent the document from overwriting other items on the screen when it is translated. You can see this in action in the Main.fx file.
- Bind the translateY instance variable of the document to thevalue variable of the scrollbar.
- Notify the scrollbar of the height of the document. This takes two steps — first, set the rangeHigh instance variable of the scrollbar to the layoutBounds.height variable of the document. Then call the update() function in the scrollbar. This causes the scrollbar to recalculate the height of the cursor.
Everything you need for the scrollbar is in the VerticalScrollBar.fx file (ScrollbarApp/src/e11/ScrollbarApp/VerticalScrollBar.fx in the .zip file). There is also a Main.fx file that contains a demonstration of the scrollbar in action. Besides showing the regular features of the scrollbar in the demo, I’ve also taken the opportunity to map keyboard events to it. The graphic at right shows which keys on the emulated cellphone correspond to which features of the scrollbar. Because JavaFX sends keyboard events to the object with focus, I have opted not to have the scrollbar trap the events itself, but to make public clickUp(), clickDown(), pageUp(), and pageDown() functions that you can call from your own keyboard events. It just seems cleaner, especially on a cellphone setup where buttons are limited.
There were a few things I noticed while putting this together that, while not directly relevant to scrollbars, seemed worth mentioning as far as JavaFX development goes. For one, manipulating translateY seems faster than manipulating y on a Rectangle object. Also, Text behaves differently on mobile than in the web browser or on the desktop; I like to use “\n\n” for paragraph breaks, but it only seems to work properly on the mobile platform (elsewhere, it doesn’t create a blank line.) I also found that, while Text can wordwrap, it doesn’t handle pairs of spaces as I’d expect. If I use two spaces after the period at the end of sentences, JavaFX will sometimes break the spaces such that one line ends with a space and the next begins with a space. Finally, clipping seems to behave differently on other profiles than mobile. I guess what I’m trying to say is that this demo breaks badly when I run it on anything other than mobile, so your mileage may vary.
Anyway, I’m releasing this scrollbar code to the public domain. Please use it and improve it as you’d like.
e11_scrollbar_0.1.zip 20,448 bytes
Vertical Scrollbar for JavaFX source code