com.borland Packages  com.borland Class Hierarchy

Package com.borland.dbswing


About the com.borland.dbswing package

Note: The dbSwing package is a feature of JBuilder Professional and Enterprise.

The dbSwing package contains components that allow you to make Swing components capable of accessing database data through DataExpress DataSets. 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:

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.

Simplifying development tasks with dbSwing

dbSwing components have been designed to simplify common programming tasks you're likely to encounter as you develop your applications. The following sections describe some of the functionality they offer.

Achieving a consistent appearance among components

A dbSwing component inherits the display mask, edit mask, and constraints on field values from the column (or columns for a 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.

Navigating in a DataSet

The dbSwing components that have the letters "Nav" in their names, such as 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.

Binding to a DataSet automatically

Some dbSwing components can determine appropriate connections to DataExpress components automatically. For example, a JdbStatusLabel 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.

Internationalizing Swing applications with IntlSwingSupport

If the applications you develop are used internationally, you can use dbSwing for assistance. Three Swing components (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.

Localizing a mnemonic in a component

If you want to supply hot keys for UI elements in an international application, dbSwing can help. Each dbSwing component that has a 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.

Monitoring DataSet events

dbSwing's 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.

Disposing of data-aware component resources

If your application creates and disposes of frames containing data-aware components, you should set each data-aware component's dataSet property to null when you no longer need it. Doing so makes the component remove itself as a listener from any DataSets 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.

Automatic closing of DataStores

dbSwing includes a couple of components with special support for developing applications that use DataStores. DBDisposeMonitor, in addition to disposing data-aware component resources, automatically closes DataStores 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 DataStores before exiting. You can also use DBExceptionHandler as an exception handler in your own code.

Customizing the Inspector for dbSwing components

Following the JavaBean standard, properties of dbSwing components are categorized as regular, expert, or hidden. All the properties you will use frequently are regular properties. You can take advantage of this to simplify the design environment. When working in the UI designer, right-click the Inspector and select Property Exposure Level|Regular. The number of properties displayed decreases, helping you to focus on the ones you might want to set. If you select Expert, the default, more properties are shown. If you select Hidden, all the properties of a component are shown.

Issues to be aware of when working with dbSwing

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.

What data-awareness means in a dbSwing component

Most dbSwing data-aware components have a 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:

Data-awareness through models and data binders

The data binders of the 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 DataSets. 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 models
dbSwing model Swing model
DBListModel ListModel
DBPlainDocument PlainDocument
DBTableModel TableModel

dbSwing data binders
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

Working with text

dbSwing provides data-aware extensions of four Swing text components:

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:

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.

File formats

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:

Actions

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:

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.

Working with field values

Display and edit masks customize the text value of a field. ColumnPaintListeners offer another way to customize fields, by changing their appearance.

Display and edit masks

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 ColumnPaintListeners for columns they display. JdbComboBox honors ColumnPaintListeners 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:

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);
  }
}

Working with tables

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.

See also: "Working with tables" in the JdbTable file.

dbSwing and Swing: Which do I use?

JBuilder offers you a choice of dbSwing and Swing. dbSwing offers significant advantages over Swing with increased functionality and data-aware capabilities. If you are considering building new applications, especially those that access databases, dbSwing is probably your best choice.

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 and Swing visual data-aware components
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

dbSwing component naming conventions

The data-aware components that extend 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.

For more information

You can use the AppBrowser's Browse Source function to view the source code for a Swing or dbSwing class, if it is provided in your version of JBuilder. You can then click the Doc tab for reference documentation. To examine some dbSwing samples, go to the samples/dbSwing directory of your JBuilder installation. For information on Swing, go to the JavaSoft web site at www.javasoft.com and search for "Swing".

You can also visit the JBuilder newsgroups. Details on newsgroups can be found at http://www.borland.com/newsgroups.

See also:
Overview of classes in this package
About components and containers
Library overview


Interfaces

Classes and components

  • BorderIcon
  • BorderIconBeanInfo
  • ColumnLayout
  • ColumnLayoutBeanInfo
  • CustomColumnsDescriptor
  • DBButtonDataBinder
  • DBButtonDataBinderBeanInfo
  • DBColumnAwareSupport
  • DBDisposeMonitor
  • DBDisposeMonitorBeanInfo
  • DBEventMonitor
  • DBEventMonitorBeanInfo
  • DBExceptionDialog
  • DBExceptionHandler
  • DBExceptionHandlerBeanInfo
  • DBLabelDataBinder
  • DBLabelDataBinderBeanInfo
  • DBLabelSupport
  • DBListDataBinder
  • DBListDataBinderBeanInfo
  • DBListModel
  • DBListModelBeanInfo
  • DBPasswordDialog
  • DBPasswordPrompter
  • DBPasswordPrompterBeanInfo
  • DBPlainDocument
  • DBRuntimeEvent
  • DBRuntimeSupport
  • DBSliderDataBinder
  • DBSliderDataBinderBeanInfo
  • DBTableModel
  • DBTableModelBeanInfo
  • DBTextDataBinder
  • DBTextDataBinderBeanInfo
  • DBTreeDataBinder
  • DBTreeDataBinderBeanInfo
  • DBTreeNavBinder
  • DBUtilities
  • FontChooser
  • FontChooserBeanInfo
  • IntlSwingSupport
  • IntlSwingSupportBeanInfo
  • JdbCheckBox
  • JdbCheckBoxBeanInfo
  • IntlCheckBoxMenuItem
  • IntlCheckBoxMenuItemBeanInfo
  • JdbComboBox
  • JdbComboBoxBeanInfo
  • JdbEditorPane
  • JdbEditorPaneBeanInfo
  • JdbLabel
  • JdbLabelBeanInfo
  • JdbList
  • JdbListBeanInfo
  • IntlMenu
  • IntlMenuBeanInfo
  • IntlMenuItem
  • IntlMenuItemBeanInfo
  • JdbNavComboBox
  • JdbNavComboBoxBeanInfo
  • JdbNavField
  • JdbNavFieldBeanInfo
  • JdbNavList
  • JdbNavListBeanInfo
  • JdbNavToolBar
  • JdbNavToolBarBeanInfo
  • JdbNavTree
  • JdbNavTreeBeanInfo
  • JdbRadioButton
  • JdbRadioButtonBeanInfo
  • IntlRadioButtonMenuItem
  • IntlRadioButtonMenuItemBeanInfo
  • JdbSlider
  • JdbSliderBeanInfo
  • JdbStatusLabel
  • JdbStatusLabelBeanInfo
  • JdbTable
  • JdbTableBeanInfo
  • JdbTextArea
  • JdbTextAreaBeanInfo
  • JdbTextField
  • JdbTextFieldBeanInfo
  • JdbTextPane
  • JdbTextPaneBeanInfo
  • JdbToggleButton
  • JdbToggleButtonBeanInfo
  • JdbTree
  • JdbTreeBeanInfo
  • LRUCache
  • RepeatButton
  • RepeatButtonBeanInfo
  • StatusLabelEvent
  • TableCurrentRowRenderer
  • TableFastStringRenderer
  • TableHeaderRenderer
  • TableImageEditor
  • TableImageReadOnlyEditor
  • TableMaskCellEditor
  • TableRowHeader
  • TableRowNoRenderer
  • TableScrollPane
  • TableScrollPaneBeanInfo
  • TextIcon
  • TextIconBeanInfo
  • ToolBarLayout

  • Overview of classes in the com.borland.dbswing package