Adding a List or Slider Component

List components provide a list of items for the user to select. Slider components show a range of selection values or show progress for the duration of an operation. VisualAge provides list and slider beans from the com.sun.java.swing and java.awt packages. Although Swing and AWT beans can be mixed, it is inadvisable.

You can add a list or slider bean to enable the user to select an item or value.

  1. Add one of the following list or slider beans:


    Bean Description
    JComboBox or Choice A selectable list with an entry field
    JList or List A selectable list of choices
    JProgressBar A progress indicator
    JScrollBar or Scrollbar A scrolling component
    JSlider A selection component for a range of values

  2. Define initial characteristics of the component.

    Making a JList bean scrollable
    An AWT List implements scrolling, duplicating the capability of a ScrollPane. A JList does not implement scrolling itself, but uses the scrolling capability of a JScrollPane in which it is placed. If you want a JList to be scrollable, drop it in a JScrollPane.

    Defining choices for a JComboBox, Choice, JList, or List bean
    For all of these components, you can specify choices using an initialization method. For a JList, you can alternatively define the list in a ListModel. Add the list model class to the free-form surface. Then, connect the list model's this property to the JList's model property.

    To specify the choices using an initialization method, follow these steps:

    1. After adding the bean, note its name. If you select the bean, its name appears in the Visual Composition Editor status area.

    2. Save your composite bean.

    3. On the Methods page, add a method to initialize the choices. The method signature should look like this:
      void initializeChoices(choiceType myChoices); 
      

      Specify the appropriate class for the choiceType:

      • com.sun.java.swing.JComboBox
      • com.sun.java.swing.JList
      • java.awt.Choice
      • java.awt.List

    4. Enter code in the initialization method to add choices. For a JComboBox, Choice, or List bean, use the addItem() method:
      myChoices.addItem("East");
      myChoices.addItem("West");
      myChoices.addItem("South");
      myChoices.addItem("North");
      

      For a JList bean, use the setListData() method:

      String[] data = {"East", "West", "South", "North"};
      myChoices.setListData(data); 
      

    5. Modify the get method for the bean you are initializing, for example, getJComboBox1(). In user code block 1, add code to call the initialization method you just created. The method call should look like this:
      initializeChoices(instanceName); 
      

      Specify the instance name for the bean as the instanceName argument for the method call. The default instance name is something like ivjJComboBox1, ivjChoice1, ivjJList1, or ivjList1.

    Defining the selection mode for a JList or List bean
    You can define a list to allow either a single selection or multiple selections. With single selection, the previous selection is deselected when the user selects another choice. Multiple selection differs between JList and List beans.

    • The JList bean supports two modes of multiple selection. Select one of the following choices for the selectionMode property in the JList property sheet:
      • SINGLE_SELECTION--allows only one choice to be selected at a time
      • SINGLE_INTERVAL_SELECTION--allows a range of choices to be selected
      • MULTIPLE_INTERVAL_SELECTION--allows multiple choices to be selected, individually or in ranges

    • The List bean supports only one mode of multiple selection. Select one of the following choices for the multipleMode property in the List property sheet:
      • False--allows only one choice to be selected at a time
      • True--allows multiple choices to be individually selected

    Allowing text entry in a JComboBox bean
    Set the editable property to True in the property sheet.

    Defining the orientation of a JProgressBar, JSlider, JScrollBar, or ScrollBar bean
    Select a choice for the orientation property in the property sheet. The orientation choices are VERTICAL and HORIZONTAL.

    Defining the value range for a JProgressBar, JSlider, JScrollBar, or ScrollBar bean
    Set the minimum and maximum properties in the property sheet.

    Defining the initial value of a JProgressBar, JSlider, JScrollBar, or ScrollBar bean
    Set value property in the property sheet. The initial value determines the initial progress, selection, or scrolling position in the value range.

    Defining tick marks or values for a JSlider bean
    To define the value increment between tick marks, set the majorTickSpacing and minorTickSpacing properties in the JSlider property sheet. To automatically adjust a user selection to the closest tick mark, set the snapToTicks property to True. To show the tick marks, set the paintTicks property to True. To show the tick values, set the paintLabels property to True. To reverse the minimum and maximum ends of the slider, set the inverted property to True.

    Defining scrolling increments for a JScrollBar or ScrollBar bean
    To define the value change when the user clicks on a scroll arrow, set the unitIncrement property in the ScrollBar property sheet. To define the value change when the user clicks in the scroll bar range away from the scroll box, set the blockIncrement property.

    Defining tool tip text
    For Swing components, you can specify tool tip text, also known as fly-over text or hover help. Enter text for the toolTipText property in the component's property sheet.

    Defining initial availability
    By default, the component is initially enabled for user interaction. To initially disable the component, set the enabled property to False in the component's property sheet.

  3. Provide runtime logic for the component.

    Obtaining the selected choice or value
    Connect a property representing the selection to a target property. Then, open properties for the connection and select a source event that indicates when the selection changes.
    Bean Source property Source event
    JComboBox selectedItem itemStateChanged
    Choice selectedItem itemStateChanged
    JList selectedValue or selectedValues valueChanged
    List selectedItem or selectedItems itemStateChanged
    JProgressBar value stateChanged
    JSlider value stateChanged
    JScrollBar value adjustmentValueChanged
    ScrollBar value adjustmentValueChanged

    To get the value of the selected choice, connect the Choice selectedItem property to the value target. To get the index of the selected choice, connect the Choice selectedIndex property to the value target.

    Getting the value that a user enters in a JComboBox bean
    If you set the editable property of a JComboBox bean to True, the user can enter a value instead of selecting a choice from the list. To get an entered value, do the following:

    1. Tear off the editor property of the JComboBox bean.

    2. Tear off the editorComponent property of the torn-off editor property.

    3. Connect the keyReleased event of the torn-off editorComponent property to the property that is to receive the entered value.

    4. Connect the value parameter of the previous connection to the item property of the torn-off editor property.

    Calling a method when the value changes
    To call a method when the value changes, connect a source event that indicates when the selection changes to the method.

    Obtaining the selected index or indexes for a JComboBox, Choice, JList, or List bean
    Connect the selectedIndex or selectedIndexes property to the value target. Then, open properties for the connection and select a source event that indicates when the selection changes.

    Setting the value of a JProgressBar bean
    Connect the value to the JProgressBar value property. Then, open properties for the connection and select a source event that indicates when the selection changes.

    Disabling or enabling a component
    Connect a related event to the component's enabled property. Specify the parameter value for this connection in one of the following ways:

    • To disable the component, open the connection's properties and set the parameter value to False.

    • To enable the component, open the connection's properties and set the parameter value to True.

    • To set the new state from another Boolean property, connect the parameter to the other Boolean property.

For examples, see the BookmarkList class in the com.ibm.ivj.examples.vc.swing.bookmarklist and com.ibm.ivj.examples.vc.bookmarklist packages, the ToDoList class in the com.ibm.ivj.examples.vc.todolist package, and the Amortization class in the com.ibm.ivj.examples.vc.mortgageamortizer package. These examples are shipped in the IBM Java Examples project.


Related procedures
Working with Beans Visually
Using VisualAge Beans in Visual Composition
Adding the IBM Java Examples project

Related references
List and Slider Beans
BookmarkList Sample