Where's documented combo box usage with zenity?

I found by chance it was possible to display a combo box with zenity (version tested: 2.32.1). See the following code:

#!/bin/bash
array=(a b c d e)
value=$(zenity --entry --title "Window title" --text "${array[@]}" --text "Insert your choice.")

The result is illustrated with the following 3 images:

I have two questions about that:

1. Is there a documentation about this functionality? I didn't find anything in the zenity documentation.

2. Why the first value of my array doesn't appear in the combo box? In the example above, my array is (a b c d e), and the combo box only displays b c d e.

   As a workaround, I add a value in my array, for example (0 a b c d e).

Solution 1:

The first element of the array gets eaten up by --text. After expansion, your zenitiy line looks like:

zenity --entry --title "Window title" --text a b c d e --text "Insert your choice."
# Which zenity treats equivalent to
zenity --entry --title "Window title" --text a --text "Insert your choice." b c d e

So you first set the text to a, then you override that with "Insert your choice." And the remaining arguments become the choices.

What you want is:

zenity --entry --title "Window title" --text "Insert your choice." a b c d e
# Hence:
zenity --entry --title "Window title" --text "Insert your choice." "${array[@]}"

Solution 2:

This is actually documented (maybe not at the time the question was posted, didn't check), not in the manual but in zenity --help-forms :

$ LANG=en_US zenity --help-forms
Usage:
  zenity [OPTION...]

Forms dialog options
  --forms                                           Display forms dialog
  --add-entry=Field name                            Add a new Entry in forms dialog
  --add-password=Field name                         Add a new Password Entry in forms dialog
  --add-calendar=Calendar field name                Add a new Calendar in forms dialog
  --add-list=List field and header name             Add a new List in forms dialog
  --list-values=List of values separated by |       List of values for List
  --column-values=List of values separated by |     List of values for columns
  --add-combo=Combo box field name                  Add a new combo box in forms dialog
  --combo-values=List of values separated by |      List of values for combo box
  --show-header                                     Show the columns header
  --text=TEXT                                       Set the dialog text
  --separator=SEPARATOR                             Set output separator character
  --forms-date-format=PATTERN                       Set the format for the returned date

Therefore:

zenity --forms --title "Window title" --text "Combo name" --add-combo "Insert your choice." --combo-values "a|b|c|d|e"

Solution 3:

I think you want to use --text-entry for the array of values, not --text (reference). Using:

#!/bin/bash
array=(a b c d e)
value=$(zenity --entry --title "Window title" --entry-text "${array[@]}" --text "Insert your choice.")

I see the default value of the dropdown box pre-filled with the first value of array, and all values available.