Welcome to the user guide for the JPopupSlider Swing Component. This guide will help to get you started with this cool component that helps you to reduce the amount of screen space taken up by a slider.
There are 4 constructors for the JPopupSlider. Although they all take different parameters, they all have the same final effect - creating a JPopupSlider with a data model containing the data needed for controlling the slider. The simplest constructor takes no arguments:
JPopupSlider mySlider = new JPopupSlider();
This constructs a default data model (known as a PopupNumberModel) with some default values. There are 4 important numbers for the number model:
When using the no-args constructor, these values default to 0, 100, 0 and 10. The PopupNumberModel is based on the SpinnerNumberModel class used by the JSpinner component.
The other constructor allow you to specify these 4 variables as either Integers or Doubles, or provide an already created PopupNumberModel.
Your JPopupSlider can present the popup slider window in 4 different directions. The direction is set like so:
mySlider.setDirection(JPopupSlider.DIRECTION_UP);
The 4 directions are represented by the following constants:
JPopupSlider.DIRECTION_UP; (Default value) JPopupSlider.DIRECTION_DOWN; JPopupSlider.DIRECTION_LEFT; JPopupSlider.DIRECTION_RIGHT;
Changing the direction of the slider will also change the direction that the arrow on the button points in. This provides an extra visual hint to your users.
In addition to the direction of the popup slider, you can change the way the popup window is positioned when the user clicks on the button. The available modes are:
JPopupSlider.FULL_UP;
JPopupSlider.PARTIAL_UP; (Default value)
FULL_UP mode draws the popup slider window in the same location each time, with the minimum value end closest to the slider button. PARTIAL_UP mode positions the popup slider window at a point where the actual slider is level with the mouse button. The slider mode is changed using the following method:
mySlider.setPopupMode(JPopupSlider.FULL_UP);
JPopupSlider fires 2 types of events - ActionEvents and ChangeEvents. An ActionEvent is fired when the popup button is pressed. ChangeEvents are fired when the value of the slider is changed.
You can register your ActionListeners and ChangeListeners using the following methods:
addActionListener(ActionListener a); addChangeListener(ChangeListener c);
There are also methods to remove these listeners, and get an array containing all currently registered listeners. Using these commands, you can make the JPopupSlider more interactive, which will be discussed later in this user guide.
There are a number of options for altering the way both the initial arrowed button and the popup slider window are drawn.
By changing the borders used to draw the button, you can easily alter not only the appearance, but also the apparent behavior of the button. To set the borders, use the following three methods:
setRaisedBorder(Border b); setLoweredBorder(Border b); setDisabledBorder(Border b);
You can alter the appearance of these parts of the slider window:
The window width - mySlider.setPopupWidth(20); The window height - mySlider.setPopupHeight(128); The color outlining the window - mySlider.setPopupOutlineColor(Color.black); The slider bar color - mySlider.setBarColor(Color.white);
There are corresponding get methods of each of those elements.
A common usage for the JPopupSlider is to place it next to a JSpinner. This provides the user with a means of fine-tuning the value from the slider, or quickly increasing the value from the spinner. This can be seen to great effect in our AdvancedColorChooser component.
To achieve this effect, you need to register listeners against each component - one to change the value of the JSpinner when the JPopupSlider is changed, and one to change the value of the JPopupSlider when the JSpinner is changed.
mySpinner.addChangeListener(new ChangeListener() { public void stateChanged(ChangeEvent e) { if (e.getSource() == mySpinner) { mySlider.setValue(mySpinner.getValue()); } } }); mySlider.addChangeListener(new ChangeListener() { public void stateChanged(ChangeEvent e) { if (e.getSource() == mySlider) { mySpinner.setValue(mySlider.getValue()); } } });
Obviously you can perform any additional steps you require after the values have been set. For altering the display of a JLabel, you only need the listener on the JPopupSlider.
Like most of the SyGem Swing Components, the JPopupSlider has been created as a JavaBean, making it simple to use in conjunction with your favourite Java IDE. All you need to do is import the JPopupSlider JAR file into the IDE, and it should become available in the component palette of your choice. Please refer to the instruction manual for your IDE for more details on using and importing JavaBeans.
I hope you enjoy using the JPopupSlider - if you need any help using this or any of our components, please email us: jpopupslider@sygem.com