borland Packages  Class Hierarchy  jbcl.control Package  Index 

NavigatorControl component

java.lang.Object
   +----java.awt.Component
           +----java.awt.Container
                   +----com.sun.java.swing.JComponent
                           +----borland.jbcl.view.BeanPanel
                                   +----borland.jbcl.control.BevelPanel
                                           +----borland.jbcl.control.ButtonBar
                                                   +----borland.jbcl.control.NavigatorControl

About the NavigatorControl component

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 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.


NavigatorControl variables

Variables implemented in this class

Variables implemented in borland.jbcl.control.BevelPanel

Variables implemented in borland.jbcl.control.ButtonBar

Variables implemented in borland.jbcl.view.BeanPanel

Variables implemented in com.sun.java.swing.JComponent

Variables implemented in java.awt.Component

NavigatorControl constructors

NavigatorControl properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in borland.jbcl.control.BevelPanel

Properties implemented in borland.jbcl.control.ButtonBar

Properties implemented in borland.jbcl.view.BeanPanel

Properties implemented in com.sun.java.swing.JComponent

Properties implemented in java.awt.Component

Properties implemented in java.awt.Container

Properties implemented in java.lang.Object

NavigatorControl methods

Methods implemented in this class

Methods implemented in borland.jbcl.control.BevelPanel

Methods implemented in borland.jbcl.control.ButtonBar

Methods implemented in borland.jbcl.view.BeanPanel

Methods implemented in com.sun.java.swing.JComponent

Methods implemented in java.awt.Component

Methods implemented in java.awt.Container

Methods implemented in java.lang.Object

NavigatorControl event listeners


NavigatorControl variables

CANCEL

  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.

DELETE

  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.

DITTO

  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.

FIRST

  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.

INSERT

  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 JBCL 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.

LAST

  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.

NEXT

  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.

POST

  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).

PRIOR

  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.

REFRESH

  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.

SAVE

  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.


NavigatorControl constructors

NavigatorControl()

  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.


NavigatorControl properties

dataSet

 public DataSet getDataSet()
 public void setDataSet(borland.jbcl.dataset.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.

labels

 public void setLabels(java.lang.String[] labels)

This method is a stub and has no functionality.

preferredSize

 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.

NavigatorControl methods

addNotify()

  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()

rebuild()

  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: borland.jbcl.control.ButtonBar.rebuild()


NavigatorControl event listeners

This component is a source for the following event sets. For information on the standard AWT event sets, see Standard Java events.

action

 public synchronized void addActionListener(java.awt.event.ActionListener l)
 public synchronized void removeActionListener(java.awt.event.ActionListener l)

ancestor

 public void addAncestorListener(com.sun.java.swing.event.AncestorListener )
 public void removeAncestorListener(com.sun.java.swing.event.AncestorListener )

component

 public synchronized void addComponentListener(java.awt.event.ComponentListener )
 public synchronized void removeComponentListener(java.awt.event.ComponentListener )

container

 public synchronized void addContainerListener(java.awt.event.ContainerListener )
 public void removeContainerListener(java.awt.event.ContainerListener )

focus

 public synchronized void addFocusListener(java.awt.event.FocusListener )
 public synchronized void removeFocusListener(java.awt.event.FocusListener )

key

 public synchronized void addKeyListener(java.awt.event.KeyListener )
 public synchronized void removeKeyListener(java.awt.event.KeyListener )

mouse

 public void addMouseListener(java.awt.event.MouseListener l)
 public void removeMouseListener(java.awt.event.MouseListener l)

mouseMotion

 public void addMouseMotionListener(java.awt.event.MouseMotionListener l)
 public void removeMouseMotionListener(java.awt.event.MouseMotionListener l)

propertyChange

 public synchronized void addPropertyChangeListener(java.beans.PropertyChangeListener )
 public synchronized void removePropertyChangeListener(java.beans.PropertyChangeListener )

vetoableChange

 public synchronized void addVetoableChangeListener(java.beans.VetoableChangeListener )
 public synchronized void removeVetoableChangeListener(java.beans.VetoableChangeListener )