Picking items from a list is typically used for filling document tabular sections with data selected by user from some object list.

We will illustrate this feature with a task of picking catalog items for filling a document tabular section, which is the most widely used scenario.

Since picking list items is implemented at the form level, it is easy to adapt it to other scenarios. These scenarios can involve other applied object types, but the algorithm is still the same. 

For picking items, you have to open a catalog form as subordinate to a document form (or to some document form item). You can use any catalog form and any method of getting that form. What is important is that the form must be opened as a subordinate one. 

The result of picking is available in the ChoiceProcessing event handler of the document form (or the form item, if the catalog item form is subordinate to that form item).

The ChoiceProcessing event occurs when any of the following conditions are met:

• Interactive selection is performed in the catalog form
• The NotifyChoice() method is called in the catalog form

We will illustrate various item picking options using the following example: picking items of the MaterialsAndServices catalog to fill GoodsReceipt documents.

Picking a single item works as follows: once you select an item, the catalog form is closed. In order to select another item one must perform a new pick operation.

Use the NotifyChoice() form method when the algorithm that generates selection data is complex and you need the user to enter or select some data in addition to selecting the catalog item. In this scenario you have to call the NotifyChoice() method when all the data required for picking is generated.

The NotifyChoice() method alerts the form owner that picking or selection is finished, passes the selected value to the owner, and closes the form unless it is opened in multiple selection mode.

You can also use the NotifyChoice() method when you need to pass a custom data structure in addition to the selected catalog item (or array of items) to the document form.

Let us implement picking a single item.

1. In Designer, open the GoodsReceipt document form.
2. On the Commands tab, create the Pick command.
3. In the command property palette, in the Action field, click the Open  button and specify that the command is executed on the client.
4. Click the Form tab and drag the command to the form controls pane, to the command bar of the Materials table (fig. 26.1).
   
   
   Fig. 26.1. Creating the Pick button
5. Click the Module tab and add the script shown in listing 26.1 to the Pick command handler.
   
   Listing 26.1. Pick command handler
   
   

   &AtClient
   Procedure Pick(Command)
       OpenForm("Catalog.MaterialsAndServices.ChoiceForm", , Items.Materials);
   EndProcedure

   The procedure opens the MaterialsAndServices catalog selection form, which is subordinate to the Materials table of the GoodsReceipt document (Items.Materials).
   
   Once a user selects a value from the catalog selection form, the value is passed to the ChoiceProcessing event handler of the Materials table because the table is the owner of the selection form.
6. Open the property palette of the Materials table and create a ChoiceProcessing event handler (fig. 26.2) that is executed on the client (listing 26.2).
   
    
   Fig. 26.2. Creating the ChoiceProcessing event handler for the Materials table
   
   Listing 26.2. ChoiceProcessing event handler for the Materials table
   
   

   &AtClient
   Procedure MaterialsChoiceProcessing(Item, SelectedValue, StandardProcessing)
    
       Items.Materials.AddRow();
       Items.Materials.CurrentData.Material = SelectedValue;
    
   EndProcedure

   The procedure adds a row to the Materials table and assigns the value selected in the catalog selection form to the Material column of that row. This value is passed to the handler as the SelectedValue parameter.

Let us test the changes.

1. Start 1C:Enterprise in the debug mode.
2. In the Inventory section, open the list of goods receipts and start creating a new one.
3. In the command bar, click the Pick button and then double-click an item to select it.

Picking multiple items works as follows: the catalog form is open until the user closes it interactively or until the Close() form method is executed. 

• In the GoodsReceipt document form, update the Pick command handler as shown in listing 26.3.
  
  Listing 26.3. Pick button click handler
  
  

  &AtClient
  ProcedurePick(Command)
   
      FormParameters = New Structure("CloseOnChoice", False);
      OpenForm("Catalog.MaterialsAndServices.ChoiceForm", FormParameters, Items.Materials);
   
  EndProcedure

  In this procedure the form is opened with parameters.
  
  Form parameters are used for opening the form in a specific state. The parameters are stored in a structure. Each structure item describes a single form parameter. The parameter name serves as a structure item key.
  
  The structure is passed to the OpenForm() method as its second parameter (the FormParameters variable).
  
  The structure is generated right before it is passed to the method. It contains a single item with the CloseOnChoice key.
  
  By passing the structure to the OpenForm method, you set the CloseOnChoice form parameter to False.
  
  It means that the form is not closed when a user selects a single item by double-clicking it.

Let us test the changes.

1. Start 1C:Enterprise in the debug mode.
2. In the Inventory section, open the list of goods receipts and start creating a new one.
3. In the command bar, click the Pick button.
4. Double-click a material to select it, then double-click another material.
5. Open the Services group and pick several services.
6. Close the selection form window.

There is another picking method available: you can pick multiple items at once.

The option to select multiple items is enabled by default in all list forms. But the option to pick the selected items is usually disabled.

To enable the option, let us use the MultipleChoice parameter of the dynamic list form extension. 

1. In the GoodsReceipt document form, update the Pick command handler as shown in listing 26.4.
   
   Listing 26.4. Pick button click handler
   
   

   &AtClient
   Procedure Pick(Command)
    
       FormParameters = New Structure ("MultipleChoice", True);
       OpenForm("Catalog.MaterialsAndServices.ChoiceForm", FormParameters, Items.Materials); 
    
   EndProcedure

   In the multiple selection mode the form returns an array of items instead of a single item. So you have to iterate through the array in the ChoiceProcessing handler.
2. Update the ChoiceProcessing event handler as shown in listing 26.5.
   
   Listing 26.5. ChoiceProcessing event handler for the Materials table
   
   

   &AtClient
   Procedure MaterialsChoiceProcessing(Item, SelectedValue, StandardProcessing)
    
       For Each SelectedItem In SelectedValue Do
           NewRow = Object.Materials.Add();
           NewRow.Material = SelectedItem;
       EndDo;
    
   EndProcedure

Let us test the changes.

1. Start 1C:Enterprise in the debug mode.
2. In the Inventory section, open the list of goods receipts and start creating a new one.
3. In the command bar, click the Pick button.
   
   Let us switch to the flat list view to simplify the picking.
4. On the More menu, point to View mode and click List.
5. Select multiple items by clicking them while holding Ctrl.
6. Click Select.
   
   This adds the selected items to the document tabular section.

The last example combines both methods that you learned. It includes selecting multiple items and picking them without closing the selection form, then selecting some more and picking them, and so on.

This requires passing both form parameters to a form being opened: CloseOnChoice and MiltipleChoice. 

• Update the Pick button click handler as shown in listing 26.6.
  
  Listing 26.6. Pick button click handler
  
  

  &AtClient
  Procedure Pick(Command)
   
      FormParameters = New Structure ("CloseOnChoice, MultipleChoice", False, True);
      OpenForm("Catalog.MaterialsAndServices.ChoiceForm", FormParameters, Items.Materials);
   
  EndProcedure

Let us test the changes.

1. Start 1C:Enterprise in the debug mode.
2. In the Inventory section, open the list of goods receipts and start creating a new one.
3. In the command bar, click the Pick button.
4. Expand the Services group, expand the TV sets group, select all services in that group, and pick them.
5. Expand the Materials group, expand the Miscellaneous group, select all materials in that group, and pick them.
6. Close the Materials and services selection form window.