Working with the Picklist Controls

The mmPicker and associated mmPickListForm control provide the ability for end users to launch and select items from pick lists. An mmPicker control contains three sub-controls; a text box, picker button, and clear button:

If you click the picker button, it launches a pick list form from which users can pick one or more items (as specified by the developer):

The text box at the top of the form provides incremental search capabilities in the DataGrid. As you enter characters in the text box, the corresponding matching record is automatically selected in the DataGrid (Incremental search is performed on the current sort column as defined by the Picker's GridDefaultSortColumn property):

By default, the mmPickListBusinessObject class is used to retrieve data in the PickList form. If you would like to use your own specialized business object, see the section below "Using a Different PickList Business Object"

Customizing the Picker Control

The following sections describe how to set up the picker control. In most cases you don't need to create a custom PickList form. You can simply drop a picker on a form and set properties on the picker that define the appearance and behavior of the PickList form.

PickList Data Retrieval Settings

The following settings are used to specify how data is retrieved by the PickList business object in the PickList form:

• DataCommand - The data retrieval command. For example, a stored procedure name or SQL SELECT command. If you are using a stored procedure, you can click the ellipses button next to the DataCommand property and it pops up a dialog from which you can select a stored procedure name from the list of stored procedures in your database. The builder uses the information in your applications configuration file to determine the database(s) used by your application.

• DataCommandType - The data retrieval command type:
  • StoredProcedure (the default)
    
  • TableDirect (name of the back end table; returns all columns and rows; can only be used with the OLE DB Provider)
    
  • Text (a SQL SELECT statement)

  
  Note: If you specify a stored procedure that accepts parameters, you need to create an event handler for the Picker's SetParameters event and place code in the handler that sets the parameter values. For details, see the section below on Hooking into Picker Events and check out the code samples for the SetParameters event.
  
  

• DatabaseKey - Specifies the database key to be used in the picker business object to retrieve data. If you only use a single database key with your application (even if you use multiple database sets) you do not need to specify this setting.

Data Binding the PickList

The following properties are used to specify data binding and retrieval for the PickList:

• PickListDisplayMember - The data column that contains the selected item's display text. If this property is not specified, it defaults to the value of the BindingSourceMember property

• PickListSearchField - Specifies the physical name of the database column used to search for PickList items. If this property is not specified, it defaults to the value of the PickListDisplayMember

• PickListValueMember - Specifies the data column that contains the item value. If this property is not specified, it defaults to the value of the BindingValueSourceMember property. At run time after the user selects an item in the picklist, the value of the PickListValueMember is automatically stored into the picker's BindingValueSourceMember.

Specifying PickList DataGrid Columns

The GridColumns property allows you to specify the columns that appear in the PickList form's DataGrid. If you do not specify DataGrid columns, all columns in the PickList data source are displayed, and you won't be able to perform incremental searches in the PickList text box.

To specify DataGrid columns, select the GridColumns property and click its associated ellipses button. This launches the Grid Columns Collection Editor:

Click the Add button to add a new grid column definition, or Remove to remove one from the list. You can specify the following information about a grid column:

• BindingSourceMember - The name of the source business object member (in the PickList form) to bind this control to

• NullText - The text that appears in the column when no records match the search criteria in the PickList form.

• Name - The name of the column definition

• Modifiers - The visibility of the column (Public, Protected, Protected Internal, Internal, Private)

• Alignment - The text alignment of the column (Left, Right, Center)

• HeaderText - Column header text

• Width - The default width of the column

• Format - Gets or sets the character(s) that specify how text is formatted.

Specifying PickList DataGrid Behavior

The following properties allow you to change the behavior of the PickList form's DataGrid:

• GridDefaultSortColumn - Specifies the default column on which the DataGrid is sorted. You must specify a default sort column in order to get incremental search functionality in the PickList form

• GridMultiSelect - Specifies if multiple values can be selected from the picklist

• GridResizeColumn - Specifies a specific column to be resized when the DataGrid is resized. If a particular column is not specified, all columns are resized proportionately

Data Binding the Picker (optional)

The following settings are used to data bind the picker control (optional)

• BindingFlag - Specifies if the control is automatically data bound

• BindingProperty - The control property to data bind (Text, by default)

• BindingSource - Binding source business object for the Picker control

• BindingSourceMember - Binding source member of the Picker business object. Specifies the display text of the current item

• BindingValueSource - Binding Value source business object. If this property is not specified and a BindingValueSourceMember is, defaults to the same value as BindingSource

• BindingValueSourceMember - Binding value source member of the Picker business object. Specifies the value of the current item

Showing/Hiding Picker Sub-Controls

You can show/hide either the Clear button or the picker text box with these settings:

• DisplayClearButton - Specifies if the Clear button is displayed

• DisplayTextBox - Specifies if the TextBox is displayed

As you show/hide these controls at design time, the picker control automatically shows/hides the specified sub-control and resizes the picker container.

Changing the Picker Button Settings

Change the following properties to alter the appearance of the picker buttons:

• ButtonMargin - Margin between the buttons

• ButtonTextMargin - Margin between the text box and the buttons

• ButtonImagePicker - Picker button image

• ButtonImageClearEntry - Clear button image

Specifying PickList Form Settings

• The PickListForm property allows you to specify a particular pick list form to be instantiated when the picklist button is clicked.

• The PickListFormCaption property specifies the caption of the picklist form. If this is not specified, the caption defaults to Picklist Form.

• The PickListFormDisplayMode - property specifes under which conditions the PickList form is displayed. Here are the options:
  • AlwaysDisplayForm - The PickList form is always displayed

  • AutoFillOnSingleResult - (Default) If the PickList search results only return a single record, the PickList form is not displayed and the return value is automatically stored in the picker textbox

  • AutoFillOnSingleResultExact - If the PickList search results only return a single record on an exact match, the PickList form is not displayed and the return value is automatically stored in the picker textbox

Accessing the Internal TextBox and Buttons

To provide the maximum control over the picker, the internal TextBox and Buttons are surfaced as the following class level properties that you can access at design time:

• TextBoxEntry
  
• ButtonPicker
  
• ButtonClearEntry

Hooking into Picker Events

The picker also has the following events you can hook into:

• ItemSelected - Raised when item(s) in the picklist are selected, and the user clicks OK.

  ItemSelected is the default event of the PickList control. This handler method is passed an mmPickerItemSelectedEventArgs object. You can examine the dsSelectedItems property of this event argument object to look at all columns of the item selected in the PickList control.

  For example, in C#:

  // Get the DataRow that contains the item selected in the PickList
  DataRow Row = e.dsSelectedItems.Tables[0].Rows[0];
  
  // Specify the column name you want to retrieve a value from
  int SelectedItemPK = (int)Row["My_PK"];

  And in VB .NET:

   ' Get the DataRow that contains the item selected in the PickList
  Dim Row As DataRow = e.dsSelectedItems.Tables(0).Rows(0)
  
  ' Specify the column name you want to retrieve a value from
  Dim SelectedItemPK As Integer = Row("My_PK")

• ItemNotFound - Raised when the specified value in the picker text box is not found when performing a search.

• ClearEntry - Raised when the Clear button is clicked

• SetParameters - Raised before executing the PickList search. You can create a handler for this event that sets parameters to be used in the PickList search.

  For example, in C#:

  private void pckCustomer_SetParameters(object sender, OakLeaf.MM.Main.Windows.Forms.mmPickerSetParametersEventArgs e)
  {
  	// Get PickList business object's data access object and create a parameter object
  	IDbDataParameter param = e.PickListParams.PickListBusinessObject.GetDataAccessObject().CreateParameter("@pecmp_id", this.ParentCmp_ID);
  	// Add the parameter object to a new parameter array
  	e.PickListParams.Parameters = new IDbDataParameter[] {param};
  }

  And in VB .NET:

  Private Sub pckCustomer_SetParameters(sender As Object, e As OakLeaf.MM.Main.Windows.Forms.mmPickerSetParametersEventArgs)
     ' Get PickList business object's data access object and create a parameter object
     Dim param As IDbDataParameter = e.PickListParams.PickListBusinessObject.GetDataAccessObject().CreateParameter("@pecmp_id", Me.ParentCmp_ID)
     ' Add the parameter object to a new parameter array
     e.PickListParams.Parameters = New IDbDataParameter() {param}
  End Sub

To create a handler for one of these PickList events, do the following:

1. Select the PickList control in design mode

2. Go to the Properties Window and click the Events button (the one with the lightning bolt)

3. Find the event you want to create a handler for and double-click it. This creates a handler method into which you can place code to be executed when the event is raised at run time.

Using a Different PickList Business Object

By default, the PickList form uses the mmPickListBusinessObject class to retrieve PickList data. If you want to use your own custom PickList business object, you can either create a subclass of mmPickListBusinessObject or create a business object that implements the ImmPickListBusinessObject interface.

If you would like to use the same custom PickList business object throughout your entire application, you can override the CreatePickListBusinessObject() factory method (the Factory class is located in Factory.cs or Factory.vb).

For example, in C#:

public override OakLeaf.MM.Main.Business.mmPickListBusinessObject CreatePickListBusinessObject()
{
	return new myPickListBusiness();
}

And in VB .NET:

Public Overrides Function CreatePickListBusinessObject() As Main.Business.mmPickListBusinessObject
    Return New myBusinessObject
End Function

If you have multiple picklist form classes you can change which picklist business object is used on a given form by overriding its CreatePickListBusinessObject() method.