macro/command/listbox.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <title>listbox</title>
  <meta http-equiv="Content-Style-Type" content="text/css">
  <link rel="stylesheet" href="../../style.css" type="text/css">
</head>

<body>


<h1>listbox</h1>

<p>
Displays a list box, and ask an item to user. <em>(version 4.78 or later)</em>
</p>

<pre class="macro-syntax">
listbox &lt;message&gt; &lt;title&gt; &lt;string array&gt; [&lt;selected&gt;]
</pre>

<h2>Parameters</h2>

<dl>
        <dt class="macro">string &lt;message&gt;</dt>
        <dd>It is displayed in the list box.</dd>
        
        <dt class="macro">string &lt;title&gt;</dt>
        <dd>It is displayed as the list box title.</dd>
        
        <dt class="macro">array &lt;string array&gt;</dt>
        <dd>It is displayed as the list box items.</dd>

        <dt class="macro">integer &lt;selected&gt; (version 4.89 or later)</dt>
        <dd>It is selected first item by specifying the zero-based index of the array. This argument is optional.</dd>
</dl>

<h2>Return Value</h2>

<dl>
        <dt class="macro">System variable &lt;result&gt;</dt>
        <dd>If the user selects one of items, it is set to from 0 to N-1.<br>
            If the user cancels, it is set to -1.</dd>
        
</dl>

<h2>Remarks</h2>

<p>
The listbox macro command shows all selected items of the &lt;string array&gt; array.<br />
If the &lt;string array&gt; is defined as bigger entries than selected numbers as follows, 
the empty string will be shown at last.
</p>

<pre>
strdim msg 4
msg[0] = 'Banana' 
msg[1] = 'Apple' 
msg[2] = 'Orange'
listbox 'Select your favorite food.' 'Confirmation' msg

; displays 4 items
Banana
Apple
Orange
[Empty string]
</pre>

<p>
<em>(version 4.89 or later)</em><br>
When the &lt;selected&gt; parameter is specified, an item of the list box can be selected at first. <br />
If the parameter is omitted, the default value is 0.
</p>


<h2>Example</h2>

<pre class="macro-example">
strdim msg 3
msg[0] = 'Banana' 
msg[1] = 'Apple' 
msg[2] = 'Orange'
listbox 'Select your favorite food.' 'Confirmation' msg
sprintf2 var "%d" result
messagebox var "result"
; result
;   -1: Cancel
;    0: Banana
;    1: Apple
;    2: Orange
</pre>

<pre class="macro-example">
strdim msg 7
msg[0] = 'Sunny' 
msg[1] = 'Cloudy' 
msg[2] = 'Rainy'
msg[3] = 'Windy'
msg[4] = 'Snowy'
msg[5] = 'Foggy'
msg[6] = 'Unknown'
; The seventh entry is selected by default.
listbox "How's today's weather?" 'Confirmation' msg 6
sprintf2 var "%d" result
messagebox var "result"
</pre>

<h2>See also</h2>
<ul>
  <li><a href="inputbox.html">inputbox</a></li>
  <li><a href="passwordbox.html">passwordbox</a></li>
  <li><a href="setdlgpos.html">setdlgpos</a></li>
  <li><a href="yesnobox.html">yesnobox</a></li>
</ul>

</body>
</html>