The Picklist Reusable Component

This Component enables you to easily add a Picklist or Chooser style interface to an application, to provide functionality that mimics the picklists of wizards and other dialogs. The component contains the following Form Builder objects:

Usage Notes

The Picklist control is populated and manipulated using two objects called Lists, named 'List_In' and 'List_Out'. You create an instance of the Picklist with the Create_Picklist built-in in the Pick_List package. Only one Picklist can be created in a form at any given time.
Each List contains an array of Elements; these can be populated either from a query or added and removed explicitly, one by one. Each Element has two properties: a Label and a Value. The Label is displayed in the list, for example an Employee Name. The Value is used as necessary in your application; for example, an Employee Number might be used to fetch other details of an employee. An Element is referenced by the list, such as 'List_In' or 'List_Out', together with an Index number, representing its sequential position in the List.

After making changes to the state of the picklist, you must always call Pick_List.Display_Picklist to display the changes. This allows you to make a number of changes to the list without the overhead or nuisance of screen redraw.

Creating a Picklist

To create a picklist:

  1. From the Components page of the reusable_components.olb object library, copy or subclass the Picklist object group.
  2. Attach the PL/SQL library picklist90.pll, which contains the Pick_List package, to your module.
  3. Using the Pick_List package create a Picklist, populate the Picklist with elements, and display the Picklist.
  4. Add code as necessary to manipulate the Picklist control. Remember to call Pick_List.Display_Picklist to display any changes to the picklists.

Picklist Class Routines

Pick_List.Create_Picklist  

Description 

Creates the structures needed for the picklist reusable component. Call this function to create the picklist before attempting to insert elements..

Syntax

PROCEDURE Pick_List.Create_Picklist;

Pick_List.Delete_Picklist  

Description 

Destroys the structures needed for the picklist reusable component. Call this function to release resources associated with the picklist.

Syntax

PROCEDURE Pick_List.Delete_Picklist;

Pick_List.Populate_Picklist_With_Query 

Description 

Populates a picklist with the results of the specified query and returns the Oracle error if any associated with the query.

Syntax

FUNCTION Pick_List.Populate_Picklist_With_Query(picklist    VARCHAR2, 
query VARCHAR2);

Returns

NUMBER

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
query Specify the query used to populate the picklist. The query must select exactly two columns of type VARCHAR2. The first column will be the label that will appear in the picklist and the second column will be the value.

Pick_List.Set_Picklist_Selection 

Description 

Marks the specified element as selected. If keystate is Shift, then a range is marked as selected. If keystate is Control, then the individual element is added to the list of selected elements.

Syntax

PROCEDURE Pick_List.Set_Picklist_Selection( picklist        VARCHAR2,
picklist_index NUMBER,
keystate VARCHAR2)

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
picklist_index The index of the element to select. The first element number is 1.
keystate The key modifier, in the same form as :system.mouse_button_shift_state.

Pick_List.Get_Picklist_Selection_Count 

Description 

Returns the number of items in the specified picklist that are currently marked as selected.

Syntax

FUNCTION Pick_List.Get_Picklist_Selection_Count( picklist   VARCHAR2);

Returns

NUMBER

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.

Pick_List.Get_Picklist_Element_Label

Description 

Returns the label of the specified element.

Syntax

FUNCTION Pick_List.Get_Picklist_Element_Label(picklist          VARCHAR2,
picklist_index NUMBER);


Returns

VARCHAR2

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
picklist_index The index of the element. The first element number is 1.

Pick_List.Get_Picklist_Element_Value

Description 

Returns the valueof the specified element.

Syntax

FUNCTION Pick_List.Get_Picklist_Element_Value(picklist          VARCHAR2,
picklist_index NUMBER);


Returns

VARCHAR2

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
picklist_index The index of the element. The first element number is 1.

Pick_List.Set_Picklist_Element_Label

Description 

Sets the label for the specified element.

Syntax

PROCEDURE Pick_List.Set_Picklist_Element_Label(picklist         VARCHAR2,
picklist_index NUMBER
label VARCHAR2)

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
picklist_index The index of the element. The first element number is 1.
label The label for this element

Pick_List.Set_Picklist_Element_Value

Description 

Sets the value for the specified element.

Syntax

PROCEDURE Pick_List.Set_Picklist_Element_Value(picklist         VARCHAR2,
picklist_index NUMBER
value VARCHAR2)

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
picklist_index The index of the element. The first element number is 1.
value The value for this element

Pick_List.Clear_Picklist

Description 

Clears the contents of the picklist.

Syntax

PROCEDURE Pick_List.Clear_Picklist( picklist      VARCHAR2)

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.

Pick_List.Add_Picklist_Element

Description 

Adds an element to the specified picklist.

Syntax

PROCEDURE Pick_List.Add_Picklist_Element( picklist          VARCHAR2,
picklist_index NUMBER
label VARCHAR2
value VARCHAR2)

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
picklist_index The index of the element. The first element number is 1.
label The label for this element
value The value for this element

Pick_List.Delete_Picklist_Element

Description 

Deletes the specified element from the picklist

Syntax

PROCEDURE Pick_List.Delete_Picklist_Element( picklist           VARCHAR2,
picklist_index NUMBER);

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
picklist_index The index of the element. The first element number is 1.

Pick_List.Display_Picklist

Description 

Displays the specified picklist. Note that the displayed state of the picklist does not change until you call this procedure. This allows you to make numerous changes to the picklists without causing screen flicker.

Syntax

PROCEDURE Pick_List.Display_Picklist( picklist          VARCHAR2)

Parameters

picklist Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.

Pick_List.Picklist_Element_Move

Description 

Moves elements from one list to the other.

Syntax

PROCEDURE Pick_List.Picklist_Element_Move( from_picklist           VARCHAR2
to_picklist VARCHAR2
picklist_option VARCHAR2);

Parameters

from_picklist The picklist to move from. Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
to_picklist The picklist to move to. Specify the constants PICK_LIST.LIST_IN or PICK_LIST.LIST_OUT.
picklist_option Specify whether you wish to move only the selected elements or all elements. Use the constants PICK_LIST.PICKLIST_SELECTED or PICK_LIST.PICKLIST_ALL to specify which elements to move.