com.borland Packages com.borland Class Hierarchy
com.borland.dbswing
package
The dbSwing
package contains components that allow you to make Swing components capable of accessing database data through DataExpress DataSet
s. It provides a rich set of components that make it easier to use Swing features or provide additional capabilities Swing components don't have.
dbSwing components support JDK 1.2.2 and JDK 1.3 only.
dbSwing components can be grouped into these categories:
The dbSwing and More dbSwing pages of the component palette contain many components you can use to create user interfaces (UI) for your applications. These components can display data from, and write data to, data sets. JdbTable
, JdbList
, and JdbSlider
are examples of this type of component.
Utilities
The dbSwing package contains utility components to aid application development. Examples are DBExceptionHandler
, which handles DataSet
exceptions, and DBPasswordPrompter
, a DBPasswordDialog
that prompts for a user name and password to access a DataExpress Database
.
Name | DataExpress utility | DataStore utility |
---|---|---|
DBDisposeMonitor |
X | X |
DBEventMonitor |
X | |
DBExceptionHandler |
X | X |
DBPasswordPrompter |
X | |
DBPasswordDialog |
X | |
LRUCache |
X |
Models and data binders
The model and data binder components are used internally by the dbSwing visual components to make them data-aware. For example, JdbList
is an extension of JList
, but with the addition of DBListDataBinder
and DBListModel
to it, JdbList
gains read and write access to a specified data set and can fill its list from another data set. While data-aware dbSwing components have default data binders and/or models, you can use data binder and model components with your own components that extend Swing to make them data-aware too.
DBButtonDataBinder |
DBListDataBinder |
DBSliderDataBinder |
DBTreeDataBinder |
DBDataBinder |
DBListModel |
DBTableModel |
DBTreeNavBinder |
DBLabelDataBinder |
DBPlainDocument |
DBTextDataBinder |
Visual components that aren't data-aware
Even if you're not interested in connecting your applications to a database, you'll find the added functionality and improvements in dbSwing over Swing compelling. For example, TableHeaderRenderer
can be used to add multi-line column headers to a Swing JTable
component.
Internal use classes
The following classes in this package are used internally by classes in
this and other com.borland
packages. These classes are not intended for general use and are therefore not documented. Do not use these classes directly in your application.
DBLabelSupport |
DBRuntimeEvent |
DBRuntimeSupport |
TableMaskCellEditor |
BeanInfo classes
BeanInfo classes specify how a bean appears in visual tools such as JBuilder. The following BeanInfo
classes are in this package:
You can find samples of dbSwing components in the samples/dbSwing directory of your JBuilder installation, if you have installed the JBuilder samples. You may need to download the samples separately, if you don't have them.
JdbTable
) it's bound to. It also inherits visual properties such as caption
, font
, color
, and alignment
from its column if they're not set in the component. This makes it easy to provide a consistent appearance for all components bound to a column. If a property is set on the component, that value takes precedence over the column's property setting.
DataSet
JdbNavComboBox
, are used to navigate through the bound DataSet
. A "Nav" component has most of the properties and behavior of the component it's based on, but there are some differences. For example, JdbNavList
and JdbNavComboBox
don't use pick lists; they always fill their list from the DataSet
and column they navigate in. To view and edit data in the bound DataSet
, use the corresponding component that doesn't have "Nav" in the name, such as JdbList
.
DataSet
automaticallyJdbStatusLabel
or JdbNavToolBar
sets its focusedDataSet
property to any DataSet
that has focus. This is especially convenient if your application has multiple JdbTables
and you want them to share the same JdbNavToolBar
. You don't have to write the code to switch between the tables. Similarly, a DBEventMonitor
reports DataSet
events without needing to be bound explicitly to a particular DataSet
.
JFileChooser
, JColorChooser
, and JOptionPane
) display text strings in their user interfaces. Java 2 includes translations of these text strings for English and Japanese only. If you try to display one of these components in any other locale, such as French or German, the dialog box components display English strings. Borland ships translations of these strings for French and German, and also several other languages. All you need to do to access them is to drop the dbSwing IntlSwingSupport
component into your application and set IntlSwingSupport
's locale
property to the appropriate locale. This needs to be done before you drop the JFileChooser
, JColorChooser
, or JOptionPane
components into your application.
text
property also has a textWithMnemonic
property that lets you put an ampersand (&) in the text to indicate the component's mnemonic. JBuilder displays the & character as an underline in the UI designer and at runtime. Keeping the text and the mnemonic together make it easier for a translator creating a localized version of an application to select an appropriate mnemonic for the translated text.
DBEventMonitor
allows you to trace the flow of DataSet
events fired during an application session. You'll find this information helpful when you are trying to determine when and why DataSet
event handlers in your application are invoked.
dataSet
property to null
when you no longer need it. Doing so makes the component remove itself as a listener from any DataSet
s or models, ensuring that objects no longer in use can be recycled by the garbage collection mechanism. dbSwing provides the DBDisposeMonitor
component, which does all this for you automatically. Simply set its dataAwareComponentContainer
property to the container that will be monitored. Then, when that container is disposed, DBDisposeMonitor
sets the dataSet
property of all data-aware controls in the container to null
.
DataStore
s. DBDisposeMonitor
, in addition to disposing data-aware component resources, automatically closes DataStore
s as part of its clean-up. You'll find this handy when you are building applications that use a DataStore
, since you don't have to write any code to close the DataStore
when an application's main frame is closed. Simply add a DBDisposeMonitor
to the frame, and when the frame is closed, DBDisposeMonitor
automatically closes the DataStore
for you.
DBExceptionHandler
, dbSwing's default exception handler, optionally displays an Exit button allowing a user to exit an application when an unexpected exception occurs. By default, DBExceptionHandler
automatically closes any open DataStore
s before exiting. You can also use DBExceptionHandler
as an exception handler in your own code.
Scrolling behavior is not available by default in any Swing component or dbSwing extension. To get scrolling behavior, add the Swing or dbSwing component to a JScrollPane
. JdbTextArea
, JdbTextPane
, JdbEditorPane
, JdbList
, JdbTree
, JdbTable
, and the corresponding "Nav" components should usually be placed in scroll panes.
The components of the dbSwing
package support Java 2 only.
dataSet
property and a columnName
property. These properties bind the component to a specific DataSet
, and within that DataSet
, a specific Column
. (Some components work with all the columns of a DataSet
, and therefore have a dataSet
property only.)
There are two types of data-awareness in dbSwing components; some components use one type while others use both:
DataSet
and Column
to set a value in the component and to specify which DataSet
and Column
to write values to.
Filling the list of data displayed in the component from a DataSet
and usually from a specific Column
in the DataSet
.
dbSwing
package supply the first type of data-awareness while the models provide the second. Each data-aware dbSwing visual component has an appropriate built-in data binder or model and some have both.
Components that have a data binder can have an initial value set in the component that comes from the bound DataSet
Column
, and then when the user edits this initial value, the value can be written back to the DataSet
Column
. Data binders allow DataSet
values to be edited without the developer having to write a line of code. An example of a component with a data binder is a JdbTextField
or JdbRadioButton
. These components handle just one piece of data at a time so they don't require a model.
Controls that use a model can obtain the data they display from a DataSet
. Both JdbList
and JdbComboBox
use a built-in data model. Both of these can display the data in a specific column of a DataSet
. The standard way to fill the lists of these components is to define a pick list on their bound-to columns. For information about defining pick lists on columns, use the online Help index to search for pick lists; you'll find several topics that describe working with pick lists and columns. If you have installed the JBuilder samples, the samples/dbSwing/PickLists directory of your JBuilder installation contains a project (picklists.jpr) that demonstrates the use of pick lists.
Controls such as JdbList
and JdbComboBox
use both data binders and models: they have two levels of data-awareness. While their data binders connect them with a DataSet
and Column
, the model provides the data displayed in their lists from a pick list used by the bound Column
. This pick list gives the components access to a second DataSet
. You can also fill the list using the items
property.
Nearly all of the dbSwing data-aware components use a data binder to display data in the component and write it back to the DataSet
. The one exception is JdbTable
, which uses only a model that identifies the DataSet
to fill the table and to write the edited values back to.
You can instantiate binders and models yourself to override their default behavior or to connect your own components to DataExpress DataSet
s. For example, if you have written your own component that extends a Swing component and want to make your component data-aware, select an appropriate data binder from the dbSwing Models page of the component palette, drop it onto the UI designer, and bind it to your component. When you specify values for the dataSet
and columnName
properties, your component is now data-aware. The data binder automatically synchronizes the display and editing of data in your component with the bound DataSet
.
Likewise, by dropping an appropriate model in the UI designer or component tree, connecting the model with the component, and setting the model's dataSet
property and its columnName
property, if it has one, you provide the means to fill your component with data from the specified DataSet
. A model updates itself automatically to changes in its corresponding DataSet
, such as row filtering, row sorting, the insertion and deletion or rows, and so on.
If a component you have written doesn't extend Swing, but uses a Swing model, you can still make the component data-aware. You can connect the Swing model to a data binder by setting properties of the data binder. For example, you can use DBListDataBinder
to make any component that uses the Swing ListModel
component data-aware by setting the data binder's listModel
property, then setting the columnName
and dataSet
properties of the data binder. When you use this method to achieve data-awareness, you must remember to open the DataSet
yourself. Also your component won't get the benefit of all the inherited visual properties, as it would if your component extended a Swing component.
The following tables list the models and data binders of dbSwing and explain how they relate to Swing components:
dbSwing model | Swing model |
---|---|
DBListModel |
ListModel |
DBPlainDocument |
PlainDocument |
DBTableModel |
TableModel |
dbSwing data binder | Bindable Swing components | Bound Swing model interfaces |
---|---|---|
DBButtonDataBinder |
AbstractButton subclasses: JButton , JToggleButton , JCheckBox , JRadioButton |
ButtonModel |
DBLabelDataBinder |
JLabel and its subclasses |
N/A |
DBListDataBinder |
JList and its subclasses |
ListModel and ListSelectionModel |
DBSliderDataBinder |
JSlider and its subclasses |
BoundedRangeModel |
DBTextDataBinder |
JTextComponent subclasses: JTextField , JTextArea , JTextPane , JEditorPane |
Document |
DBTreeDataBinder |
JTree and its subclasses |
TreeModel and TreeSelectionModel |
JdbTextField
- Displays and edits a single line of text. (JdbTextField
can display data of many types, but this section focuses on its text-handling capabilities.) Font and color attributes are set on the component and apply to all text displayed.
JdbTextArea
- Allows multi-line display and editing of plain text. The text may include tab characters and carriage returns.
JdbTextPane
- Displays and edits multi-line plain or styled text. In styled text, font and color attributes are applied to blocks of text and saved with the text.
JdbEditorPane
- Primarily used to display HTML pages. It also supports some HTML editing as well as the displaying and editing of text and RTF (rich text format).
Because JdbTextArea
, JdbTextPane
, and JdbEditorPane
treat Enter and Tab as text characters, these keystrokes are not available for navigation. To navigate out of a multi-line text component, use Ctrl+Enter, Ctrl+Tab, and Ctrl+Shift+Tab. This is a standard Swing key mapping and works throughout dbSwing. Similarly, these components use Up, Down, PgUp, and PgDn to navigate within the current field value. When they are bound to a DataSet
, navigation to the next and previous rows of the DataSet
, usually done with PgUp and PgDn, uses Ctrl+PgUp and Ctrl+PgDn instead.
Each text component provides a pop-up menu of editing and formatting actions such as Cut, Copy, Paste, Open, Save, Undo, and Redo. There are properties that allow you to disable menu commands individually or to suppress the menu completely. Available menu commands vary according to the component. These are the Open and Save options for each component:
JdbTextField
: None
JdbTextArea
: Text files (extension must be .txt)
JdbTextPane
: Text files (.txt) and Java serialized objects (.ser). Text may also be styled and saved in a DataSet
.
JdbEditorPane
: Text files (.txt), serialized objects (.ser), rich text format (.rtf), and HTML files (.html). Files can be loaded from the Open|File menu command, which displays a file browser, or from Open|URL, which takes a URL such as these: file:D:\JBuilder3\Readme.txt or http://www.borland.com. JdbEditorPane
can't load a file from one format and save it to another.
Edits made to a text component are not automatically saved to its DataSet
column. You can completely undo edits for the currently focused component by pressing the Esc key. To save changes to the column, press Enter in a JdbTextField
, or Ctrl+Enter in all other text components. Changes are automatically saved when the currently focused text component loses focus or is navigated. You can change this behavior using the postOnFocusLost
and postOnRowPosted
properties, which are both true
by default.
Most applications that manipulate text, store that text in a DataSet
. The DataSet
can either be persisted in a DataStore
, or loaded from, and saved back to, a server table. Although text can occasionally be loaded from or saved to files, the DataSet
is the primary repository for data. In some cases, this DataSet
already exists; in others, the application must create it. Following are the supported file formats, the text components that are appropriate for each, and a description of how to load and work with text of that format:
JdbTextArea
component to display and edit it. Use a STRING column. dbSwing creates a Swing document from it when it loads the component. Don't put the text strings in an OBJECT column because a String
is not appropriate for a document object. For this format, there are no special rules for working with the column.
Styled text: This is not a file format but a Swing document type. Using styled text is appropriate if you want fonts and colors but don't need to save to a file. Use an OBJECT column and load like this:
String text = "This will become styled text in an Object column of a data set"; DefaultStyledDocument swingDoc = new DefaultStyledDocument(); swingDoc.insertString(0, text, null); myDataSet.setObject("Styled Text Column", (Object) swingDoc);Display and edit styled text in a
JdbTextPane
. The font and color menu commands are available and the styles in the text are saved to the DataSet
. Save is available by default, but styles in the text are lost if you save to a TXT file.
RTF: RTF is a standard file format for styled text. The JdbEditorPane
component supports the color, font, font size, and bold and italic attributes in RTF files. RTF keywords that Swing doesn't understand are ignored when opening a file and are lost if the text is saved. All style information is lost when styled text is saved to a TXT file, which only supports plain text. Put the RTF text in a column of data type Variant.OBJECT and display it in a JdbEditorPane
. If you initialize the application by loading the DataSet
with plain text, you must convert each text String
into an object that implements the Document
interface and supports RTF text. Code like this will do that:
jdbEditorPane1.setContentType("text/rtf"); Document document = jdbEditorPane1.getEditorKit().createDefaultDocument(); document.insertString(0, "Ordinary text to put into an RTF document via JdbEditorPane", null); myDataSet.setObject("RTF Column", document);
HTML: You might expect JdbEditorPane
to handle RTF and HTML data similarly because it can display and edit both formats and both formats support styled text. But this is not the case. If you want to edit styled text, RTF is the preferred format. When working with HTML, think of JdbEditorPane
as a simple HTML viewer. JdbEditorPane
does have several features that set it apart from the other dbSwing text components, however, and that make it work well as an HTML viewer:
editable
property is false
by default.
It is allowed to load files even when it is not editable.
In addition to the usual dataSet
and columnName
properties, it has a second property that binds it to a column: columnNameURL
. This property specifies the column containing the URL of the HTML page stored in columnName
.
It can automatically save newly loaded HTML pages to its DataSet
. This behavior is controlled by the enableURLAutoCache
property. When enableURLAutoCache
is true
, a new row is added to the JdbEditorPane
's DataSet
whenever an HTML page not already in the DataSet
is fetched through a hyperlink. enableURLAutoCache
is true
by default.
A JdbEditorPane
alone is a very simple HTML browser. To load an HTML page, right-click the JdbEditorPane
and select Open URL. Follow links from there or right-click again to open a new file. To cache HTML pages, add a DataSet
with a String
column (set the JdbEditorPane
's columnNameURL
property to this column) and an Object
column (set the columnName
property to this column). To display the URL of the loaded HTML page and allow navigation to a previously loaded page, add a JdbNavComboBox
.
Another way to build a simple browser, if you want the application to determine what content is loaded into the JdbEditorPane
, is to provide a DataSet
with a String
column filled with URLs. When a JdbEditorPane
bound to a DataSet
encounters a row in which its columnName
column is empty but its columnNameURL
column is not empty, it loads the specified HTML page. To reload a page when you know its content has changed, use the setPageURL()
method.
JdbEditorPane
supports simple HTML tags. It can sometimes open a more complex HTML file by ignoring tags it doesn't understand. These tags are omitted when the text is saved back to an HTML file. JdbEditorPane
might throw an exception and fail to load a complex HTML file.
When a JdbEditorPane
is editable, you can modify the text of the page. However, its editing support, which it inherits from JEditorPane
, does not provide a mode in which you can edit tags. Also, images and other parts of the HTML page are displayed in live components in the JEditorPane
, which can make editing difficult. So editing HTML is not recommended.
SER: JdbTextPane
and JdbEditorPane
can save their contents to files as Java serialized objects. These files are usually given the .ser extension. This is not a text format in the same sense that TXT, RTF, and HTML are; it is a way of saving text in any of these formats to a file. Because no translation from one format to another occurs, all text style information is preserved when saving text, so the data can be loaded back into a JdbTextPane
or JdbEditorPane
unchanged. Note, however, that the .ser extension may be used when serializing an object of any class, but only files containing Swing document objects can be loaded into dbSwing text components. You must ensure that a SER file's contents are appropriate for loading into JdbTextPane
or JdbEditorPane
.
Each text menu command is a class that extends javax.swing.Action
, and there are public static references to these classes in DBTextDataBinder
. Actions bundle together code to perform an operation, such as opening or saving a file, with a text description of that operation, an icon representing it, or both. You can easily add an action to a JMenu
, JPopupMenu
, JToolBar
, or any class that extends one of them. Since actions can contain both a text description and an icon, you can add the same action to various UI components, both a menu and a toolbar, for example, without duplicating code. To add an action to a menu or toolbar and change its text, use code like this:
JMenuItem item = jMenu1.add(DBTextDataBinder.LOADFILE_ACTION); item.setText("Open"); JButton button = jToolBar1.add(DBTextDataBinder.FONTDIALOG_ACTION); button.setText(""); // only show icons, not text, on toolbar button = jToolBar1.add(DBTextDataBinder.LOADFILE_ACTION); button.setText("");When an action is invoked, it operates on the component that has focus, if it can, subject to these rules:
javax.swing.JTextComponent
, and several actions are more restricted.
For some actions, the component must be bound to a DataSet
column.
For some actions, the component must be editable.
The component's current document type must support the action.
If an application contains several dbSwing text components, an action may be able to operate on all of them. If you want it to operate on certain components only, write code to check which component has focus. For instance, if the action is invoked by a button, check which component has focus in the button's ActionListener
. Note that disabling a menu command for a text component takes it off the component's pop-up menu but does not prevent the corresponding DBTextDataBinder
action from operating on the component. For example, setting a component's enableClearAll
property to false
doesn't prevent DbTextDataBinder.ClearAllAction
from clearing it.
Display and edit masks customize the text value of a field. ColumnPaintListeners
offer another way to customize fields, by changing their appearance.
Display masks let you control formatting of numeric, date/time, String,
and boolean data. For example, a BigDecimal
value that represents money
can be formatted with a currency symbol and a date can be formatted to
include the day of the week and the full name of the month. Edit masks
add the ability to display the literal characters in the expected input
and validate type-in character by character.
To use masks, set the displayMask
and/or editMask
property of the corresponding DataSet
Column
. Masks will be used when the column is bound to a JdbTextField
or JdbTable
.
For more information on these properties, see "Edit masks" in the Database Application Developer's Guide and "String-based patterns."
If you do not provide a display mask, a default one is used. If you do not provide an edit mask, the display mask is used to parse and format data values, but does not validate input character by character. If you supply an edit mask, you will see it when you navigate within a value or
begin to edit it by typing either Ctrl+Enter or a text character.
The current field value will be formatted according to the edit mask and displayed
in the mask. To end edit mode, press Enter or Tab. This triggers validation of the value entered and, if it's incomplete or invalid, displays an error message on your JdbStatusLabel
or in an error dialog.
ColumnPaintListener
A ColumnPaintListener
gives you access to field values just before they are displayed and lets you customize their color, font, and other properties. Like a mask, a ColumnPaintListener
is defined for a DataSet
Column
and its effect is seen in the components the column is bound to.
JdbTable
, JdbTextField
, and JdbList
honor ColumnPaintListener
s for columns they display. JdbComboBox
honors ColumnPaintListener
s for columns in its drop-down list, but not its selected value - that is, the listeners must be defined on columns in the the picklist DataSet
.
Like a cell renderer, a ColumnPaintListener
gives you a field value just before it is displayed and lets you customize its
color, font, and other properties. The parameters passed to you are very similar to those for a cell renderer. A ColumnPaintListener
differs from a cell renderer in several ways:
Variant
. In a cell renderer it's a String
, formatted according to the display mask.
ColumnPaintListener
is defined on a Column
object, not on a component.
Column
's painting or editing event.
ColumnPaintListener
can customize the display of the cell being edited.
To define a ColumnPaintListener
, write an event handler for its painting
event (used when column values are displayed) and/or its editing event
(used only on the value being edited). Both give the value to be displayed as a Variant
. You can even modify the value that painting()
passes to you before it's displayed, but this only changes the display, not the stored value.
In this example, ColumnPaintListener
's painting event is used to display negative values in a numeric column in red:
columnPaint_painting(DataSet dataSet, Column column, int row, Variant value, CustomPaintSite paintSite) { if (value.getAsInt() < 0) { paintSite.setForeground(Color.red); } }
JdbTable
enhances JTable
, its corresponding Swing component, by adding
the ability to easily display and edit data from a DataExpress DataSet
.
JdbNavToolBar
is very often used with JdbTable
. JdbNavToolBar
automatically detects and binds to the active component's DataSet
. It can be used to navigate, insert and delete rows, and save DataSet
changes back to a server, and also provides visual indications of editing status and row position.
JdbTable
file.
dbSwing is entirely lightweight, provides look-and-feel support for multiple platforms, and has strong conformance to Swing standards.
The following table lists the visual data-aware dbSwing components and their counterparts in Swing:
dbSwing | Swing |
---|---|
JdbCheckBox |
JCheckBox |
JdbComboBox |
JComboBox |
JdbEditorPane |
JEditorPane |
JdbLabel |
JLabel |
JdbList |
JList |
JdbNavComboBox |
N/A |
JdbNavField |
N/A |
JdbNavList |
N/A |
JdbNavToolBar |
JToolbar |
JdbNavTree |
N/A |
JdbRadioButton |
JRadioButton |
JdbSlider |
JSlider |
JdbStatusLabel |
N/A |
JdbTable |
JTable |
JdbTextArea |
JTextArea |
JdbTextField |
JTextField |
JdbTextPane |
JTextPane |
JdbToggleButton |
JToggleButton |
JdbTree |
JTree |
javax.swing
components have names that begin with the letters "Jdb". Examples are JdbCheckBox
and JdbTable
.
The data binders and models and other types of classes that provide database support are prefaced with the letters "DB", such as DBButtonDataBinder
and DBTableModel
.
The components that aren't data-aware or don't provide database support do not begin with any special letter combination. Examples are BorderIcon
and FontChooser
.
The dbSwing
package includes navigation components that navigate through a DataSet
rather than provide view and edit access to the data. These components use navigation binders instead of data binders. They all have the letters "Nav" somewhere in their name. Examples are JdbNavField
, JdbNavToolBar
, and JdbNavList
.
The components that provide internationalization support begin with the letters "Intl", such as IntlSwingSupport
and IntlMenu
.
Components that begin with the word "Table" are components you can use with Swing's JTable
to provide new capabilities such as multi-line column headings, the use of an icon of your choice to indicate current row location, and the numbering of rows as the row header. dbSwing's JdbTable
use these components by default, but you can use them independently with the non-data-aware JTable
. Examples include TableRowHeader
and TableCurrentRowRenderer
.
You can also visit the JBuilder newsgroups. Details on newsgroups can be found at http://www.borland.com/newsgroups.
Overview of classes in this package
About components and containers
Library overview
com.borland.dbswing
package