Creating custom user interface

Most jAlbum skins allow users to set skin specific settings on a custom skin tab in the jAlbum settings window. To enable this for your skin too, please follow this guide.

The screenshot below illustrates a custom user interface:

CustomUIShowOff.png

As the skin developer you have the full power of Java/BeanShell at your hands to create any imaginable user interface and the code behind to make it tick. Here is how you do it: Put a "onload.bsh" script file in the skin directory. jAlbum will read this file every time that skin is selected/loaded. Let the script construct the user interface and finally install it inside jAlbum. Here is a minimal example taken from the "Camera Geek" skin.

/** 
 * This script is being run when a skin is selected
 * The script produces a simple custom user interface.
 * Please look at the "ShowOff" skin for a full blown example
 * Author David Ekholm
 */
 
import se.datadosen.component.*;

// Controls that are to be imported into jAlbum as variables
ControlPanel ui = new ControlPanel() {

   JTextField copyright = new JTextField("");
   JCheckBox showLabels = new JCheckBox("Show labels");
   JCheckBox showDates = new JCheckBox("Show dates", true);
   JCheckBox showImageNum = new JCheckBox("Show image numbers", true);
};

// Layout controls easily similar to how text is added in a word processor
ui.add("p", new JLabel("This is a small example of a custom user interface."));
ui.add("p", new JLabel("Copyright"));
ui.add("tab hfill", ui.copyright);
ui.add("p", ui.showLabels);
ui.add("br", ui.showDates);
ui.add("br", ui.showImageNum);

// Finally install components into jAlbum
window.setSkinUI(ui);

jAlbum will create skin variables out of the values of the controls you put inside a ControlPanel class (actually any class implementing the JComponentHolder marker interface). The controls need to be of "Swing" type so use "JButtons" and "JLabels" not "Button" or "Label" classes! If you for instance have a JComboBox control called backgroundColor, you can then refer to its current value as ${backgroundColor} in skin template files like .htt files and .css files.

Controls to variables mapping

The mapping of user interface controls to the corresponding skin variables is performed as follows:

Control type Datatype
JTextField the text (String)
JTextArea the text (String)
JComboBox selected item (String)
JColorSelector html color (String)
JCheckBox selected state (boolean)
ButtonGroup its "actionCommand" (String)
JSpinner current value (int)
JSlider current value (int)

The skin specific settings are persisted with jAlbum's project files. They are prefixed with "skin." to avoid collision with jAlbum variables.

Managing state

Those writing user interfaces know it can be a drag to manage component state, for instance to synchronize the enabled/disabled state of a group of components with the selected state of a checkbox. To simplify this task, jAlbum provides some convenience classes called StateMonitor and ComponentUtilities.

Layout of controls

The example above uses the RiverLayout layout engine of the ControlPanel to lay out controls. RiverLayout works similar to how text is being added to a word processor. Just adding controls will have them flow from left to right (no line wrapping), but adding certain "constraint strings" like "br", "p" and "tab" will affect the layout.

Here is the full set of constraint strings:

Layout control strings
String Meaning
br Add a line break
p Add a paragraph break
tab Add a tab stop (handy for constructing forms with labels followed by fields)
hfill Extend component horizontally
vfill Extent component vertically (currently only one allowed)
left Align following components to the left (default)
center Align following components horizontally centered
right Align following components to the right
vtop Align following components vertically top aligned
vcenter Align following components vertically centered (default)


Although RiverLayout is a flexible and easy to understand layout manager, it has limitations. If you have requirement that go outside what RiverLayout is capable of, we recommend using the MiGLayout layout manager. It is included with jAlbum.