How to create a Scrollable Components-Composite

Examples.gpr (guiTranslationExample)

The SizeRatio property we used in the previous example does not only help us when sizing a single component but also when dynamically sizing a group of components that should be laid out on a panel residing in JScrollPane.

Look at the image on the left side (displaying the guiTranslationExample-JFrame from the Examples.gpr GUI Project-file) that shows three panels with dialog components arranged within a JScrollPane one below the other. If the (combined) height of these panels exceeds a maximum visible height, a scrollbar appears and the user is able to scroll to the component of his interest.

So what we want to achieve is to have a screen form of variable size with an arrangement of components adjusting themselves. But the height of these components should be fixed and only their width should change in dependency of the frame width. Moreover if the height of all the contained components together exceeds the height of visibility they should be scrollable to visibility on demand (there is of course as well the possibility to scroll them as fixed witdths horizontally, but that's not within the focus of this chapter).

In order to demonstrate our intention the guiTranslationExample-JFrame contained in the Examples.gpr GUI Project-file (to be found in the SpeedJG home directory) is used. The picture below shows all the components in their parent-child dependency that are involved in this scenario, together with their properties that are of particular importance in this regard.

Examples.gpr (guiTranslationExample)
  1. The top level component of course is a JScrollPane (named spFieldEdit in our example).
  2. Within this JScrollPane a JPanel (pnFieldEdit) is enclosed with Box_Axis_Y Layout. Thus every component added to it will be laid out below the one before; and thus we are able to add more than one component group to be considered when measuring the height. Additionally this JPanel will dynamically adjust its width if the width of the JScrollPane changes; and the width of the JScrollPane changes if its scrollbar becomes visible or if its parent component changes its width. If at runtime the preferred height of all component groups laid out within this pnFieldEdit exceeds the visible height of the JScrollPane, the latter enables its scroll feature.
  3. Next in the hierarchy we find some JPanels each arranging a group of dialog components. One of these, the pnCustomerData JPanel, will be regarded now as follows.
    • The preferred- minimum- and maximum-height is set as fixed height of 84. Thus if this would be the only JPanel laid out in its parent container, the JScrollPane would begin to scroll if it's visible height falls below 84.
    • The height is set to 84 because this JPanel shall contain four lines of components, each with a height of 20. The remainder of 4 is because this JPanel has a border of size 2 (2 at the top and 2 at the bottom).
    • The Layout is set to Flow-Layout without any gaps. Thus you can add components one by one, and if there is lack of space within the current row the next component added will be laid out in the next row. Because this JPanel has a height of 80 (without the border) we can place four rows of components in it if they are not higher than 20 (or a fourth of 80 resp.).
  4. At last we insert the single form components one by one, each with a SizeRatio height of one fourth (80 / 4 = 20) of the parent pnCustomerData JPanel. The first is the lbName JLabel with a SizeRatio width of one sixth and the second the tfName JTextField with a SizeRatio width of five sixth of their parent container. Thus these two exactly fit into and fill in the first row of the pnCustomerData JPanel, and the rest of the components are added analogously.

When working with this GUI builder tool you see that the component editors of SpeedJG make extensive use of the feature described in this chapter.