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:
- Spacing between rows increases slightly, but the last row, which contains a large
JdbTextArea, gets most of the additional height.
- All columns except the first share the additional width; because the JdbTextArea
spans six columns, it increases in size the most.
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.