<doc>
	<legacy_id></legacy_id>
	<name>mobilePick</name>
	<type>command</type>

	<syntax>
		<example>mobilePick <i>optionList</i>, <i>initialIndex </i>[, <i>optionList</i>, <i>initialIndex</i>, ...] [, <i>style</i> ] [, button] [, view]</example>
	</syntax>

	<synonyms>
		<synonym>iphonePick</synonym>
	</synonyms>

	<summary>Presents the user with a native list picker dialog.</summary>

	<examples>
<example>mobilePick myOptionList, selectedIndex</example>
<example>mobilePick "A" &amp; return &amp; "B" &amp; return &amp; "C", 1, "checkmark"</example>
<example><p>mobilePick "A" &amp; return &amp; "B" &amp; return &amp; "C", 1, "cancelDone"</p></example>
<example><p>put the weekdayNames into tDays</p><p>put lineoffset("Tuesday", tDays) into tInitialIndex</p><p>mobilePick tDays, tInitialIndex</p></example>
<example><p>-- iOS only example</p><p>put "Mon" &amp; return &amp; "Tue" into tDays</p><p>put "Jan" &amp; return &amp; "Feb" &amp; return &amp; "Mar" &amp; return &amp; "Apr" into tMonths</p><p>mobilePick tDays, 2, tMonths, 3, "checkmark"</p><p>answer the result with "Okay"</p></example>
	</examples>

	<history>
		<introduced version="4.5.3">Introduced</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="5.5">Added support for Android picker</changed>
<changed version="5.0.0">Added support for Cancel and Done buttons</changed>
<changed version="4.6.4">Added support for multiple columns</changed>
	</history>

	<objects>
	</objects>

	<platforms>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
	</classification>

	<references>
		<command tag="mobilePickPhoto">mobilePickPhoto Command</command>
		<command tag="mobilePickDate">mobilePickData Command</command>
	</references>

	<description>
	<overview>Use the <b>mobilePick</b> command to display a native list picker that allows the user to select from one or multiple (iOS Only) lists of options.</overview>

		<parameters>
  <parameter>
    <name>optionList</name>
    <description>A return delimited list of options.</description>
  </parameter>
  <parameter>
    <name>initialIndex</name>
    <description>The (1-based) index of the item to be initially highlighted.</description>
  </parameter>
  <parameter>
    <name>style</name>
    <description>The type of display used. On the iPad if "checkmark" is specified a check-mark (tick) is put against the currently selected item. If not present, the currently selected item is hilited with the (standard) blue background. On Android if "checkmark" is specified then the standard checkmark(radio button) is shown next to the currently selected item.</description>
  </parameter>
  <parameter>
    <name>button</name>
    <description>Specifies if "Cancel" and/or "Done" buttons should be forced to be displayed with the picker dialog. The default behavior is device dependent, exhibiting the most native operation.</description>
    <options title="">
      <option>
        <item>cancel</item>
        <description>display the Cancel button on the Picker</description>
      </option>
      <option>
        <item>done</item>
        <description>display the Done button on the Picker</description>
      </option>
      <option>
        <item>cancelDone</item>
        <description>display the Cancel and Done buttons on the Picker</description>
      </option>
    </options>
  </parameter>
  <parameter>
    <name>view</name>
    <description>The type of view to be displayed when showing a single column of date on an iPad. By default a standard pop-over is displayed with a single column of data. If "picker" is specified, then the single column of data is replaced with a single picker wheel.</description>
  </parameter>		</parameters>

	<value>A comma delimited list giving the line indices of the selected items. If the selection was canceled, then 0 is returned.</value>
	<comments>A standard action-sheet pops up on the iPhone, containing the standard picker-wheel user interface element. On the iPad, a standard pop-over is presented to display a single column of data or a picker-wheel to display multiple columns of data. On Android, the default pop-up is presented to display a single option picker.<p></p><p><b>iOS Behavior</b></p><p>There are three modes of operation for <b>mobilePick</b>, depending on the values for <i>initialIndex</i>.</p><p></p><p>If all <i>initialIndex</i> values are non-zero, the operation acts as a way to change an existing selection. The items specified by the initial index are selected (checked or hilited on iPad if a single column is specified).</p><p></p><p>If all <i>initialIndex</i> values are zero, the operation acts as a way to select from lists of options with no items selected. The user is able to cancel the operation by clicking 'Cancel' (iPhone) or touching outside of the popover (iPad). If the operation is canceled, 0 is returned; otherwise the indexes to the selected items are returned. Any picker-wheels that remain untouched by the user, in a group of picker-wheels are set to 1, indicating that the defaults have been accepted.</p><p></p><p>If some <i>initialIndex</i> values are zero and others are non-zero, the operation acts in the same way as if all values are non-zero on the iPhone. Once the user selects the 'Done' button, all values that were set to 0 and were not updated by the users are automatically set to 1. On the iPad values that were initially set to 0 and were not altered by the  user are automatically set to 1 if at least one picker-wheel was altered. If the user does not alter the state of any picker-wheel on the iPad, then the initial settings are returned without alteration. This includes any zeros that were initially set.</p><p></p><p>If the 'Cancel' button is displayed, then any selection made by the user can be canceled, returning 0.</p><p></p><p>If the 'Done' button is displayed, then all 0's are returned if no default values were specified and the user did not make any selections on the pickers.</p><p></p><p><b>Android Behavior</b></p><p>If the 'Cancel' button is displayed, then any selection made by the user can be canceled and the result is set to 0.</p><p></p><p>If the 'Done' button is displayed, then the result contains the initial index.</p><p></p><p></p><warning>No support is provided in LiveCode for multi column pickers on Android. This currently a limitation of Android.</warning></comments>
	</description>
</doc>