Project Notes


Project: dbSwing: Buttons and Slider Sample
Author: JBuilder Team
Company: borland.com
Description:
This sample shows how JdbCheckBox, JdbToggleButton, JdbRadioButton, or JdbSlider can be used to display and edit the contents of a column that has only a small number of valid values. The sample displays the values written to its data set as you manipulate the buttons and slider and lets you see the effect of different settings of the unknownDataValueMode property.

What this sample demonstrates

The JdbCheckBox, JdbToggleButton, and JdbRadioButton components

The JdbSlider component

Using GridBagLayout

Working with icons in JBuilder

A dockable and floatable toolbar

The textWithMnemonic property

Other design-time notes

Setup

This sample doesn't use any saved data. It does use a data set because it is demonstrating data-aware components. Data entered is saved as long as the application is running, but it is lost when it is shut down.

The JdbCheckBox, JdbToggleButton, and JdbRadioButton components

These components are useful when a field is allowed to have only a small number of values - usually two for JdbCheckBox and JdbToggleButton, and maybe as many as eight for JdbRadioButton sets. Through text or graphics, they tell what the valid values are and limit input to those values. Our goal here is to show how these components look and work when they are used to display and edit values in columns of a DataSet. We see how they interpret data of various data types, how the selectedValue and unselectedValue properties are used, how they handle unexpected data values, and how they interact with Column's max, min, and default properties. For notes on specific components, see the explanations that are displayed at runtime as you move among the components.

We've placed a JdbTextField beside each checkbox, button (or set of buttons), and slider component. Each JdbTextField is bound to the same data set column as its corresponding component. The JdbTextField displays the column's value as text while the checkbox, button, or slider displays it visually. You can set a value using a checkbox, button, or slider and check in the JdbTextField that the column gets the right value, or enter a value in the JdbTextField and check that its corresponding component adjusts accordingly. You can also use the JdbTextField to enter a value outside the checkbox, button, or slider's set of valid values, and see that it handles the input according to the setting of its unknownDataValueMode property.

The JdbSlider component

Like a button, a slider allows a restricted set of input values; the difference is that its values are always a range of numbers. This sample demonstrates the same data-awareness concepts for JdbSlider as for buttons: how the component displays and sets data set values, handles unexpected data values, and interacts with its column's min, max, and default properties.

Using GridBagLayout

The frame's components are laid out in seven rows and seven columns. (Visually, there are three major columns, but to the layout there are seven). When the frame is resized:

Working with Icons in JBuilder

Swing makes it easy to display an icon along with or instead of text on a button, menu, or label. JBuilder's UI Designer can write the appropriate code for you. An icon is associated with a component by a property - for instance, JLabel's icon property - so you don't see it in the component tree. Just add your GIF or JPEG files to your project from the Project | Add to Project menu command. Now, when you set a property in the Designer that takes an icon, they'll be displayed in the property editor.

Note that in Swing, the little checkable box that gives a JCheckBox component its name is an icon. If you set a JCheckBox's icon property, your icon is not displayed beside that box, but replaces it. The same is true for JRadioButton and the dbSwing classes that extend Swing buttons. The radio buttons in this application provide an example. Be sure this is the effect you want when you add icons to check boxes and radio buttons. Also notice that icons give the only visual indication that a check box or radio button's state has changed, so if you set the icon property for one of these components, you should also set its selectedIcon property.

You can store GIFs and JPEGs in a column of a data set and display them in a JdbLabel. Make the data type of the column Variant.INPUTSTREAM and set the JdbLabel's columnNameIcon property to it. The icon is read-only by default, but it can be made "editable" - meaning that you open a file chooser and select a new GIF or JPEG to store in that field of the data set. The dbSwing TextPane sample uses a JdbLabel to display images.

Dockable and floatable toolbar

By default, Swing toolbars are dockable and floatable: you can click on an empty area in the toolbar (not on a button) and drag it to the side or bottom of its frame to dock it there, or drop it anywhere else to float in its own window. To put a floating toolbar back in its frame, close it. When you close the application, a floating toolbar is also closed. To prevent a toolbar from floating, set its floatable property to false.

Removing the toolbar from its container, or even moving it to a new location within the container, can drastically change the layout of the remaining components. For example, a toolbar that is docked at the south side of a BorderLayout will compete with any component already there. This application's toolbar is floatable. To prevent unexpected layout changes when it is floated, we've used what looks like an extra panel in ButtonsFrame.java. If you design ButtonsFrame.java, you will see in the Component Tree that the frame itself contains only the toolbar and statusPanel, while statusPanel contains a JdbStatusLabel and the rest of the design. This leaves the east, west, and south sides of the frame's border layout free as sites where the toolbar can be docked without affecting statusPanel.

The textWithMnemonic property

Whenever a Swing component has a text and a mnemonic property, dbSwing adds a textWithMnemonic property that lets you set them both in one place. This is intended mainly as a convenience when an application is localized. Having the text and its mnemonic together makes it easier to chose an appropriate and unique mnemonic when translating the text. We've used textWithMnemonic throughout this sample, so you can navigate to and edit every column using just the keyboard. For most components, the appropriate Alt+accelerator key combination sets the component's value immediately. For the JdbSlider, we set both the textWithMnemonic and labelFor properties of its label, so Alt+S selects the slider. Once it's selected, Left, Right, Home, and End set its value.

Design-time notes

There are a lot of components in this application and we've set a least a couple of properties for each one, so there's a fair amount of code. But virtually every line of it except the event handlers can be - and was - generated by the Designer. The best way to study the code may be to check in the Inspector what interesting properties have been set for each component. (Note that the Inspector shows non-default property values in bright blue.)

We've sorted the lines of code, separated groups with blank lines, and commented major groups. If you build this sample from scratch in the Designer, your code won't be so well organized unless you work very, very systematically.

One "label", productTextArea, uses a JdbTextArea just to get word-wrap. (We use a JdbTextArea rather than a JTextArea because JdbTextArea word-wraps by default.) We have to set the background, font, and opaque properties to get the desired look, and also set editable to false. When text is wrapped, you never get a horizontal scrollbar, only a vertical one. You don't have to set any JScrollPane properties to make this happen.