Door 22 - ListDialog

Sometimes you want to be able to display a dialog from which the user can select one or more options. The ListDialog component allows you to do this. I will introduce this component to you in this door.

The ListDialog is again another dialog that is accessible across the entire solution. This means that I can set settings for this dialog in various scripts and these are then applied to the dialog. So we have to reset the settings of the dialog first if we want to create a new and fresh dialog. For this we have the function ListDialog.Reset.

Set Variable [ $r ; Value: MBS( "ListDialog.Reset" ) ] 

Now we can make settings for the dialog: First, we want a text to be displayed in the dialog. We set this with the ListDialog.SetPrompt function. We set the title for the dialog with ListDialog.SetWindowTitle.

The dialog can have up to 3 buttons. One button indicates a cancel button. Then we have a Select button, which confirms the entries in the dialog. The third button, which is not displayed by default, can be passed an expression with ListDialog.SetOtherButtonEvaluate, which is executed when the button is used. This button appears when we set the text of the button with ListDialog.SetOtherButtonLabel. In our case, we do not need this. We can also change the other two buttons with the functions ListDialog.SetCancelButtonLabel and ListDialog.SetSelectButtonLabel.

Set Variable [ $r ; Value: MBS( "ListDialog.SetPrompt"; "Please make your selection") ] 
Set Variable [ $r ; Value: MBS( "ListDialog.SetWindowTitle"; "Door 22" ) ] 
Set Variable [ $r ; Value: MBS("ListDialog.SetSelectButtonLabel"; "My Presents") ]

If we now create a very long list in this dialog, then it can happen that this list quickly becomes confusing. How good it is that you can display a filter above the list with which you can limit the list. To show or hide the filter, use the ListDialog.SetShowsFilter function and pass a 1 in the parameters to show or a 0 to hide. If you already want to display a filter in the field in the beginning, you can specify this with ListDialog.SetFilter.

Set Variable [ $r ; Value: MBS("ListDialog.SetShowsFilter" ; 1) ] 

As of this year, you can also use checkboxes for multiple selections in the list dialog. To display the checkboxes, we use the ListDialog.SetShowCheckboxes function. We can then use these in the dialog. If we have checked several checkboxes and then use a filter, the already selected checkboxes remain active even though they are no longer displayed by the filter.

Set Variable [ $r ; Value: MBS("ListDialog.SetShowCheckboxes"; 1) ] 

Now, of course, we have to fill the list dialog with entries. The entry can consist of up to 5 columns in total. How many columns we see depends on the value set in the ListDialog.SetColumnCount function. By default this value is 1. With the function ListDialog.AddItemToList we can add a single item to the list. If we have an entry with more than one column, we must separate the individual columns with a Char(9) character. In addition to the visible entries in the columns, we can also specify a tag for each column. This is not displayed, but can be queried later.

Set Variable [ $r ; Value: MBS("ListDialog.SetColumnCount"; 5) ] 
Set Variable [ $r ; Value: MBS("ListDialog.AddItemToList"; "1st Column" & Char(9) & "2nd Column" 
   & Char(9) & "3rd Column" & Char(9) & "4th Column" & Char(9) & "5th Column"; "Tag123") ] 

We can also specify in the Optional whether the entry is a header. A header delimits an area and looks a little different. Here, for example, you can see the header: Fruit. A header can also not be selected.

With the ListDialog.AddItemToList function, we can only add single entries to the list. If we want to add several items to the list at the same time, we can use the ListDialog.AddItemsToList function. The entries are then transferred as a list. So we can first pass a list of titles to the function and also a list with the corresponding tags.

Set Variable [ $r ; Value: MBS( "ListDialog.AddItemToList"; "Hello" ; "Greetings" ) ] 
Set Variable [ $r ; Value: MBS( "ListDialog.AddItemToList"; "Good Morning" ; "Greetings" ) ] 
Set Variable [ $r ; Value: MBS( "ListDialog.AddItemToList"; "Banana" ; "Fruit" ) ] 
Set Variable [ $r ; Value: MBS( "ListDialog.AddItemToList"; "Orange" ; "Fruit" ) ] 
Set Variable [ $r ; Value: MBS( "ListDialog.AddItemsToList"; "Broccoli¶Apple¶GoodEvening"; "Vegetable¶Fruit¶Greetings") ] 

To display the dialog, we need to call the ListDialog.ShowDialog function. The dialog is hidden again by pressing one of the buttons on the dialog.

Set Variable [ $r ; Value: MBS("ListDialog.ShowDialog") ] 

Now, of course, we also want to know what has been selected in the dialog. We can query this with various functions. With the functions ListDialog.GetCheckedTitles and ListDialog.GetCheckedTags we get information about the lines that have been checked in the dialog. The two functions provide us with a list of either the titles that were selected with the checkbox or the tags.

Set Variable [ $CheckedTitles ; Value: MBS("ListDialog.GetCheckedTitles") ] 
Set Variable [ $CheckedTags ; Value: MBS("ListDialog.GetCheckedTags") ] 

With the functions ListDialog.GetSelectedTitle and ListDialog.GetSelectedTag we get two lists with the titles and tags of the rows that have been selected at the time of confirmation.

Set Variable [ $SelectedTitle ; Value: MBS("ListDialog.GetSelectedTitle") ] 
Set Variable [ $SelectedTag ; Value: MBS("ListDialog.GetSelectedTag") ] 

I hope you enjoyed this excursion into the world of list dialogs and that we'll see us again tomorrow in door 23.