def sheetCombo(name, initialValue=None, update=None, below=0):
""" 'prints' a combo box to the sheet.
takes four parameters:
-> a name for this UI element
-> an optional 'initial value" which is a tuple such as ( ["a", "b", "c"], 0 ), where ["a", "b", "c"] are the menu items and 0 is the index of the default selection
-> an optional 'update' function that's called when a new selection occurs
-> whether this element should be positioned 'below' the box or to the right (the default)
this will return an object that can be used to query and set the selected item.
Typical usage pattern is:
myVariable = sheetCombo("myVariable", ( ["A", "B", "C"], 0)).value()
Note that the selected item is persisted accross restarts of Field and is stored in the sheet itself.
"""
r = OutputInsertsOnSheet.printCombo(name, getSelf(), update, below)
if (OutputInsertsOnSheet.lastWasNew and initialValue):
r.setValues(initialValue[0], initialValue[1])
return r
