XUL Tutorial - Splitters

There may be times when you want to have two sections of a window where the user can resize the sections. An example is the Mozilla browser window, where you can change the size of the sidebar panel by dragging the bar in-between the two frames. You can also hide the sidebar by clicking the notch.

This feature is accomplished by using an element called a splitter. It creates a skinny bar between two sections which allows the sides to be resized. You can place a splitter anywhere you want and it will allow resizing of the elements that come before it and the elements that come after it in the same box.

When a splitter is placed inside a horizontal box, it will allow resizing horizontally. When a splitter is placed inside a vertical box, it will allow resizing vertically.

Here, four iframes have been created and a splitter has been placed in-between the first and second one. The collapse has been set to a value of before, meaning that if the splitter grippy is clicked on, the first frame would disappear and the splitter and the remaining frames would shuffle to the left.

The splitter has been given a resizeafter value of farthest. This means that when the splitter is dragged, the farthest element after it will change size. In this case, frame 4 will change size.

A value has not been specified for resizebefore so it will default to a value of closest. In this case, there is only one frame before the splitter, so frame 1 will change size.

Frames 2 and 3 will only change size if you drag the splitter far enough to the right that frame 4 has reached its minimum size.

An image of the 4 panels with the splitter resized to the right is shown below. Notice how the middle two panels have not changed size. Only panel 1 and panel 4 have changed size. You can just see part of the fourth panel. If you continue to drag the splitter to the right, the other two panels will shrink.

You can use the style properties such as min-width, max-height on the iframes to specify minimum widths or heights in the box. If you do, the splitter will detect this and not allow the user to drag the splitter past the minimum and maximum sizes.

For example, if you specified a minimum width of 30 pixels on panel 4 above, it would not shrink below that size. The other two panels would have to shrink. If you set the minimum width of panel 1 to 50 pixels, you would only be able to drag the splitter 10 pixels to the left (as it starts at 60 pixels wide). You can still collapse the splitter however.

You can also place more than one splitter in a box if you want, in which case you could collapse different parts of it. Similarly, you do not have to collapse just iframes. Any element can be collapsed.

Modifying a Splitter

A splitter is actually a type of box, meaning that you include other elements inside it. This would allow you to customize the look of the splitter.

If you do not include any content inside the splitter, and you would not normally do so, the default elements will be added. However, this will only apply when the value of collapse is set to either before or after. If you do not set this attribute or set it to a value of none, the default content will not be added. This is so that the user can distinguish between a collapsable an non-collapsable splitter. The default content of a splitter is as follows:

As you can see, an element called a grippy has been added to the splitter, surrounded by two flexible springs. The two springs are used so that grippy is centered. The grippy is, of course, the notch in the middle of the splitter that you can use to collpase the frame beside it.

The grippy is a special element that is essentially a button with some additional behaviour to make it work inside a splitter. You may place the state attribute from the splitter directly on the grippy also. You can customize the grippy much like a regular button. When placed outside a splitter, the grippy element works just like a button.

You might remember that the notch on the side of the toolbar is also called a grippy. Although they are similar in function in that they both collapse something, they are not related in implementation.

You should also notice that orientation inside the splitter is determined by the direction of the splitter. A horizontal splitter will have horizontal orientation and a vertical splitter will have vertical orientation.

Splitter Example

Let's see what the find file dialog looks like with a splitter in it. One possibility would be to add the results of the search in the dialog. We'll add an area in-between the search criteria and the buttons along the bottom. A splitter will allow you to collapse, or hide, the search results.

</tabcontrol>

 
 <iframe src="results.html"/>
 <splitter collapse="before" resizeafter="grow"/>

 <!--spring flex="1"/-->
 

 <box orient="horizontal">

Here, a splitter and an iframe have been added to the dialog. You will also note that the spring has been commented out. We don't need it any more. You can delete it if you want. The content of the frame is contained in a file called 'results.html'. Create this file and put whatever you want in it for now. The iframe will be replaced later with a results list when we know how to create it. For now, it serves to demonstrate the splitter.

The splitter has been set to a collapse value of before meaning that the element just before the splitter will collapse. Here, it is the iframe. As the images below show, when the grippy is clicked, the iframe is collapsed and the buttons shuffle up.

The resizeafter attribute has been set to grow so that the elements after the splitter push themselves down when the splitter is dragged down. This results in the content of the frame growing to any size. It should be noted that the window does not resize itself automatically. You'll also notice that this is a horizontal splitter because it has been placed in a vertical box.

Normal State:
[Image of find files with splitter]

Collapsed State:
[Image of find files with collapsed splitter]