jbcl.control Package
java.lang.Object +----java.awt.Component +----java.awt.Container +----javax.swing.JComponent +----com.borland.jbcl.view.BeanPanel +----com.borland.jbcl.control.BevelPanel +----com.borland.jbcl.control.ButtonBar +----com.borland.jbcl.control.NavigatorControl
Variables Constructors Properties Methods Event Listeners
Implements AccessListener, DataSetAware, NavigationListener, StatusListener, BlackBox, ActionListener, ImageObserver, MenuContainer, Serializable, EventListener
The NavigatorControl
is a component that is used to
navigate or move through the data in a DataSet
and
perform operations on the data, such as inserting new data or
posting changes made to an existing row of data. It contains
multiple preset buttons that the user clicks to generate specific
actions on the data in the DataSet
and is located on the
JBCL page of the JBuilder Component Palette. The default buttons
of the NavigatorControl
are:
The NavigatorControl
is used with a data-aware
control through which you display data in a DataSet
for
editing or for viewing. When linked to the same DataSet
as the data-aware control, the navigator and data-aware control
move together. For example, if the user clicks the
First button of the NavigatorControl
, the data displayed
in the data-aware control changes to that of the first record of
the shared DataSet
.
You link the NavigatorControl
to a DataSet
using its dataSet
property. You can link only one DataSet
to a NavigatorControl
at a time. However, you can change
the dataSet
property to redirect the navigator to a new
source or instantiate several navigator objects.
You can also customize the buttons on the NavigatorControl
.
To hide a button, call the isButtonVisible(false)
method. To disable a button and still have the button visible,
call the isButtonEnabled(false)
method. To add a custom
button of your own, use either the addImageButton()
or addTextButton()
methods. This is behavior inherited from its superclass
com.borland.jbcl.control.ButtonBar
;
see that component for more complete information about
customizing the buttons on the navigator.
When the NavigatorControl
is bound to a TableDataSet
,
the Save Changes and Refresh buttons are dimmed to indicate these
features are not available through the navigator. The
functionality provided by these buttons apply to DataSet
objects whose data source is a SQL server database.
If your application involves tables linked in a master-detail relationship,
the fetchAsNeeded
property of the MasterLinkDescriptor
affects
how the Save and Refresh buttons of the NavigatorControl
behave.
If fetchAsNeeded
is true,
each set of details is saved and refreshed individually when the user
navigates to the corresponding master record. When fetchAsNeeded
is
false, all details for all masters are saved and refreshed together.
However, while this process makes sense, it can cause an unexpectedly loss of unsaved changes with master-details. With master-detail relationships, saving changes made to each DataSet
correctly involves saving the changes in a particular order to maintaining data integrity. For example, if the non-linking columns of a detail DataSet
are updated, and its corresponding master is deleted, if you do not save
the changes in the correct order, you may end up with an orphaned detail record. Depending on your data, this may or may not be acceptable. To prevent this and other such data loss conditions, use the Database.saveChanges
method to save your changes when working with linked DataSets
.
public static final String CANCEL = Res.getString(Res.Cancel1)
The actionId associated with the "Cancel" button of
the NavigatorControl
. When this button is clicked, the
modifications made to the current row of data are discarded. The
data for the row is restored to the way it was when the current
edit began or if a post occurred during the current edit, to the
state of the data when the last post occurred.
public static final String DELETE = Res.getString(Res.Delete)
The actionId associated with the "Delete" button of
the NavigatorControl
. When this button is clicked, the
current row of the navigator's DataSet
is deleted. If
the control that displays your data is linked to the same DataSet
as the navigator, its display may or may not change to reflect
the newly deleted record. This depends on the implementation of
the data-aware control that you are using.
public static final String DITTO = Res.getString(Res.Ditto)
The actionId associated with the "Ditto" button of
the NavigatorControl
. When this button is clicked, the
data for the current field (the intersection of the current row
and column) is copied from the row above it.
public static final String FIRST = Res.getString(Res.First)
The actionId associated with the "First" button of
the NavigatorControl
. When this button is clicked, the
row position of the navigator's DataSet
moves to the
first row of the DataSet
. If the control that displays
your data is linked to the same DataSet
as the
navigator, its display changes to the data in the first row of
the DataSet
automatically.
public static final String INSERT = Res.getString(Res.Insert)
The actionId associated with the "Insert" button of
the NavigatorControl
. When this button is clicked, a new
(blank) row is added to the navigator's DataSet
. If the
GridControl
is used to display your data and it is
linked to the same DataSet
as the navigator, this blank
record is displayed automatically, allowing for data entry. If
you are using another data-aware control, you may or may not see
this blank record in the control's UI. This depends on the
implementation of the data-aware control that you are using.
public static final String LAST = Res.getString(Res.Last)
The actionId associated with the "Last" button of
the NavigatorControl
. When this button is clicked, the
row position of the navigator's DataSet
moves to the
last row of the DataSet
. If the control that displays
your data is linked to the same DataSet
as the
navigator, its display changes to the data in the last row of the
DataSet
automatically.
public static final String NEXT = Res.getString(Res.Next)
The actionId associated with the "Next" button of
the NavigatorControl
. When this button is clicked, the
row position of the navigator's DataSet
moves to the
next row of the DataSet
. If the control that displays
your data is linked to the same DataSet
as the
navigator, its display changes to the data in the next row of the
DataSet
automatically.
public static final String POST = Res.getString(Res.Post)
The actionId associated with the "Post" button of
the NavigatorControl
. When this button is clicked, the
row of data that is being edited is saved to the DataSet
.
Editing is typically done through a data-aware control that
shares the same DataSet
as the navigator.
Depending on the view settings of the data-aware control's DataSet
,
when changes to the data in a row are posted, the row may
disappear (if it doesn't meet the filter criteria) or flyaway to
a new position within the data in the Control (depending on the
sorting criteria).
public static final String PRIOR = Res.getString(Res.Prior)
The actionId associated with the "Prior" button of
the NavigatorControl
. When this button is clicked, the
row position of the navigator's DataSet
moves to the
previous row of the DataSet
. If the control that
displays your data is linked to the same DataSet
as the
navigator, its display changes to the data in the previous row of
the DataSet
automatically.
public static final String REFRESH = Res.getString(Res.Refresh)
The actionId associated with the "Refresh" button of
the NavigatorControl
. When this button is clicked, the
data that displays in your data-aware control is refreshed from
its data source. When the navigator is bound to a TableDataSet
,
this button is dimmed to show that this functionality is
unavailable.
public static final String SAVE = Res.getString(Res.Save)
The actionId associated with the "Save" button of
the NavigatorControl
. When this button is clicked, the
data is saved back to the data source. When the navigator is
bound to a TableDataSet
, this button is dimmed to show
that this functionality is unavailable.
public NavigatorControl()
Creates a NavigatorControl
object with default
properties and adds the following buttons: First, Prior, Next,
Last, Insert, Delete, Post, Cancel, Save, and Refresh.
public DataSet getDataSet() public void setDataSet(DataSet newDataSet)
Stores the DataSet
that provides the source of the
data within which the NavigatorControl
navigates.
The NavigatorControl
does not display data from the DataSet
.
However, it is linked to the current row position of the DataSet
.
When you click a button on the NavigatorControl
, the row
position of the DataSet
moves. For example, if you click
the Next
button, the current position of the DataSet
moves to the following row. If a data-aware control such as a
grid is also attached to the same DataSet
as the
navigator, the grid automatically navigates to the data in the
new row position.
public void setLabels(String[] labels)
This method is a stub and has no functionality.
public Dimension getPreferredSize()Read-only property that returns the preferred size to use when creating this component. This property is used by the JBuilder design tools.
public void addNotify()
Notifies the NavigatorControl
that it has been added
to a container. This method is always called after a component
has been added to a container. The addNotify()
method
also opens the (optional) DataSet
specified in its dataSet
property.
Overrides: java.awt.Panel.addNotify()
protected void rebuild()
Protected method that rebuilds the NavigatorControl
.
This method disables the Save and Refresh buttons if the NavigatorControl
is bound to a DataSet
that does not support such
functionality, for example, a TableDataSet
component.
Overrides: com.borland.jbcl.control.ButtonBar.rebuild()
public synchronized void addActionListener(ActionListener l) public synchronized void removeActionListener(ActionListener l)
public void addAncestorListener(javax.swing.event.AncestorListener ) public void removeAncestorListener(javax.swing.event.AncestorListener )
public synchronized void addComponentListener(java.awt.event.ComponentListener ) public synchronized void removeComponentListener(java.awt.event.ComponentListener )
public synchronized void addContainerListener(java.awt.event.ContainerListener ) public synchronized void removeContainerListener(java.awt.event.ContainerListener )
public synchronized void addFocusListener(java.awt.event.FocusListener ) public synchronized void removeFocusListener(java.awt.event.FocusListener )
public synchronized void addInputMethodListener(java.awt.event.InputMethodListener ) public synchronized void removeInputMethodListener(java.awt.event.InputMethodListener )
public synchronized void addKeyListener(java.awt.event.KeyListener ) public synchronized void removeKeyListener(java.awt.event.KeyListener )
public void addMouseListener(MouseListener l) public void removeMouseListener(MouseListener l)
public void addMouseMotionListener(MouseMotionListener l) public void removeMouseMotionListener(MouseMotionListener l)
public synchronized void addPropertyChangeListener(java.beans.PropertyChangeListener ) public synchronized void removePropertyChangeListener(java.beans.PropertyChangeListener )
public synchronized void addVetoableChangeListener(java.beans.VetoableChangeListener ) public synchronized void removeVetoableChangeListener(java.beans.VetoableChangeListener )