split-bar

Class

Package: cg

ToC

DocOverview

CGDoc

RelNotes

FAQ

Index

PermutedIndex

Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version

split-bar

The split-bar control can be used to allow the end user to interactively resize multiple tiled windows panes, or to move and resize groups of widgets.

This is done by creating a split-bar widget that lies between other sibling widgets or windows that it should affect. When used to resize window panes, typically you would leave just enough room between the panes to insert the split-bar like another tiled pane. (The parent window does not need to be a dialog, though the split-bar is always a dialog-item.) When used to move and/or resize groups of widgets instead, there may be additional space between the groups of widgets, with the split-bar placed midway in between.

A split-bar can extend across its parent window either horizontally or vertically by setting its orientation property to :horizontal or :vertical.

The simple bar that's drawn for the control can be either visible or invisible while idle, while under the mouse, or while being dragged, according to the properties color-when-idle, color-under-mouse, and color-when-dragging. (A split-bar that's on a form window will always be visible to facilitate laying out the form, so you would need to run the form to check the invisibility.)

The control will display a special mouse cursor when the mouse is over the bar to indicate that a drag can be done when clicking at that location. This allows the user to find a split-bar even when the widget itself is invisible.

You can specify what happens when the user drags a split-bar by setting up simple lists of the widgets or panes that should be resized or moved as the bar is dragged, if that is sufficient. See the widgets-to-move and widgets-to-resize properties. Otherwise an on-change function can be used for customized behavior. A split-bar can resize panes or widgets continuously during the drag, or only once at the end, according to its delayed property.

The split-bar's current position can be controlled programmatically by setting the value property. The widget's value should be a non-negative integer that indicates the distance of a horizontal split-bar from the top edge of the parent window's interior, or the distance of a vertical split-bar from the left edge of the parent window's interior.

When creating a split-bar programmatically and passing the orientation argument as :vertical, you will probably want to also pass the cursor-name argument as :vertical-splitbar-cursor (or the name of a custom cursor), since it will otherwise default to :horizontal-splitbar-cursor. (This is not an issue when creating a split-bar interactively on a form window.)

The Navigator Dialog includes a split-bar example called Two Window-Panes with a Draggable Split-Bar Widget.

Here are the properties of the split-bar:

The class of widget-window that is displayed for a split-bar is split-bar-pane. Typically an application needs to deal only with the dialog-item class, though if you supply an on-redisplay function to draw a split-bar in a custom way, then you draw on the split-bar-pane.