Merge pull request #253 from hkanou/ttpmacro_listbox_enhancement

ttpmacro listboxオプション追加 #154

doc/en/html/macro/command/listbox.html

@@ -14,42 +14,47 @@
 <h1>listbox</h1>
 
 <p>
-Displays a list box, and ask an item to user. <em>(version 4.78 or later)</em>
+Displays a dialog box with 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;] ['dclick=on'] ['minmaxbutton=on'] ['minimize=on'] ['maximize=on'] ['size=&lt;N1xN2&gt;']
+listbox &lt;message&gt; &lt;title&gt; &lt;string array&gt; [&lt;selected&gt;] [&lt;keyword parameter&gt;...]
 </pre>
 
 <h2>Parameters</h2>
 
 <dl>
 	<dt class="macro">string &lt;message&gt;</dt>
-	<dd>It is displayed in the list box.</dd>
-	
+	<dd>It is displayed in the dialog box.</dd>
+
 	<dt class="macro">string &lt;title&gt;</dt>
-	<dd>It is displayed as the list box title.</dd>
-	
+	<dd>It is displayed as the dialog 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. When this option is omitted, no item is selected.</dd>
 
-	<dt class="macro">fixed string 'dclick=on' (version 5.3 or later)</dt>
-	<dd>Enable item selection by double-clicking. This argument is optional.</dd>
+	<dt><br>keyword parameters : optional, multiple allowed, random order</dt>
+	<dd><dl>
+		<dt class="macro">string 'dblclick=on' (default=off) (version 5.3 or later)</dt>
+		<dd>Enable item selection by double-clicking.</dd>
 
-	<dt class="macro">fixed string 'minmaxbutton=on' (version 5.3 or later)</dt>
-	<dd>Enable Minimize/Maximize button. This argument is optional.</dd>
+		<dt class="macro">string 'minmaxbutton=on' (default=off) (version 5.3 or later)</dt>
+		<dd>Enable Minimize/Maximize button.</dd>
 
-	<dt class="macro">fixed string 'minimize=on' (version 5.3 or later)</dt>
-	<dd>Display in minimized state. This argument is optional.</dd>
+		<dt class="macro">string 'minimize=on' (default=off) (version 5.3 or later)</dt>
+		<dd>Display in minimized state.</dd>
 
-	<dt class="macro">fixed string 'maximize=on' (version 5.3 or later)</dt>
-	<dd>Display in maximized state. This argument is optional.</dd>
+		<dt class="macro">string 'maximize=on' (default=off) (version 5.3 or later)</dt>
+		<dd>Display in maximized state.</dd>
 
-	<dt class="macro">string 'size=&lt;N1xN2&gt;' (version 5.3 or later)</dt>
-	<dd>Specify the size of the list box. This argument is optional.</dd>
+		<dt class="macro">string 'listboxsize=WxH' (default=26x6) (version 5.3 or later)</dt>
+		<dd>Specify the size of the list box. W:width (horizontal character count), H:height (vertical character count).</br>
+		    Example 'listboxsize=60x20' (for 60 characters horizontally and 20 characters vertically)</dd>
+	</dl></dd>
 </dl>
 
 <h2>Return Value</h2>
@@ -58,21 +63,20 @@ <h2>Return Value</h2>
 	<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 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[0] = 'Banana'
+msg[1] = 'Apple'
 msg[2] = 'Orange'
 listbox 'Select your favorite food.' 'Confirmation' msg
 
@@ -85,21 +89,16 @@ <h2>Remarks</h2>
 
 <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 />
+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.
-<br><br>
-<em>(version 5.3 or later)</em><br>
-To specify the size of the list box, specify "size=N1xN2".<br>
-Specify the horizontal length for N1 and the vertical length for N2.<br>
-Example 'size=60x20' (for 60 characters horizontally and 20 characters vertically)
 </p>
 
 <h2>Example</h2>
 
 <pre class="macro-example">
 strdim msg 3
-msg[0] = 'Banana' 
-msg[1] = 'Apple' 
+msg[0] = 'Banana'
+msg[1] = 'Apple'
 msg[2] = 'Orange'
 listbox 'Select your favorite food.' 'Confirmation' msg
 sprintf2 var "%d" result
@@ -113,8 +112,8 @@ <h2>Example</h2>
 
 <pre class="macro-example">
 strdim msg 7
-msg[0] = 'Sunny' 
-msg[1] = 'Cloudy' 
+msg[0] = 'Sunny'
+msg[1] = 'Cloudy'
 msg[2] = 'Rainy'
 msg[3] = 'Windy'
 msg[4] = 'Snowy'
@@ -128,18 +127,21 @@ <h2>Example</h2>
 
 <pre class="macro-example">
 strdim msg 9
-msg[0] = "listbox msg[result] result msg 'size=70x10'"
-msg[1] = "listbox msg[result] result msg 'size=70x10' 'dclick=on'"
-msg[2] = "listbox msg[result] result msg 'size=70x10' 'minmaxbutton=on'"
-msg[3] = "listbox msg[result] result msg 'size=70x10' 'minimize=on'"
-msg[4] = "listbox msg[result] result msg 'size=70x10' 'maximize=on'"
-msg[5] = "listbox msg[result] result msg 'size=70x10' 'minmaxbutton=on' 'dclick=on'"
-msg[6] = "listbox msg[result] result msg 'size=100x10'"
-msg[7] = "listbox msg[result] result msg 'size=10x20'"
-msg[8] = "listbox msg[result] result msg"
+selected = 0
+msg[0] = "listbox msg[selected] title msg selected 'listboxsize=70x10'"
+msg[1] = "listbox msg[selected] title msg selected 'listboxsize=70x10' 'dblclick=on'"
+msg[2] = "listbox msg[selected] title msg selected 'listboxsize=70x10' 'minmaxbutton=on'"
+msg[3] = "listbox msg[selected] title msg selected 'listboxsize=70x10' 'minimize=on'"
+msg[4] = "listbox msg[selected] title msg selected 'listboxsize=70x10' 'maximize=on'"
+msg[5] = "listbox msg[selected] title msg selected 'listboxsize=70x10' 'minmaxbutton=on' 'dblclick=on'"
+msg[6] = "listbox msg[selected] title msg selected 'listboxsize=100x5'"
+msg[7] = "listbox msg[selected] title msg selected 'listboxsize=10x20'"
+msg[8] = "listbox msg[selected] title msg selected"
 :select
-execcmnd msg[result]
-if result = -1 then
+sprintf2 title 'selected = %d' selected
+execcmnd msg[selected]
+selected=result
+if selected = -1 then
   exit
 endif
 goto select

doc/en/html/macro/syntax/file.html

@@ -19,7 +19,7 @@ <h1>Encoding</h1>
 The TTL file was processed as ANSI CodePage in previous version.
 </p>
 
-<h2>Supporting encoding</h2>
+<h2>1) Supporting encoding</h2>
 
 <table>
   <tr>
@@ -60,7 +60,7 @@ <h2>Supporting encoding</h2>
   </tr>
 </table>
 
-<h2>Encoding determination</h2>
+<h2>2) Encoding determination</h2>
 
 <p>
 Tera Term determines the encoding as follows.

doc/en/html/macro/syntax/identifiers.html

@@ -11,7 +11,7 @@
 
 <h1>Identifiers and reserved words</h1>
 
-<h2>Variable identifiers</h2>
+<h2>1) Variable identifiers</h2>
 
 <p>
 The first character must be an alphabetic (A-Z, a-z) or an underscore character "_". Subsequent characters can be alphabetic, underscore or numeric (0-9). Variable identifiers are not case-sensitive. The maximum length is 31.
@@ -23,7 +23,7 @@ <h2>Variable identifiers</h2>
     _flag
 </pre>
 
-<h2>Label identifiers</h2>
+<h2>2) Label identifiers</h2>
 
 <p>
 Label identifiers consist of alphabetic, underscore or numeric characters, and are not case-sensitive. The maximum length is 31.
@@ -35,7 +35,7 @@ <h2>Label identifiers</h2>
     100
 </pre>
 
-<h2>Reserved words</h2>
+<h2>3) Reserved words</h2>
 
 <p>
 The following words are reserved:

doc/en/html/macro/syntax/index.html

@@ -23,6 +23,7 @@ <h1>Tera Term Language (TTL)</h1>
  <LI><A HREF="variables.html">Variables</A></LI>
  <LI><A HREF="expressions.html">Expressions and operators</A></LI>
  <LI><A HREF="lineformats.html">Line formats</A></LI>
+ <LI><A HREF="parameter.html">Parameter formats</A></LI>
 </UL>
 
 </BODY>

doc/en/html/macro/syntax/parameter.html

@@ -0,0 +1,68 @@
+<!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=Shift_JIS">
+<TITLE>Parameter formats</TITLE>
+<META http-equiv="Content-Style-Type" content="text/css">
+<link rel="stylesheet" href="../../style.css" type="text/css">
+</HEAD>
+<BODY>
+
+<h1>Parameter formats</h1>
+
+There are three parameter formats.<br>
+Which format can be used depends on the TTL command, So please check the <A HREF="../command/index.html">command reference</A>.
+
+<h2>1) Positional parameter</h2>
+
+<p>
+Specify the parameters in order.<br>
+Parameters not explicitly listed as "Keyword parameter" in the  <A HREF="../command/index.html">command reference</A> are "Positional parameter".
+</p>
+
+<pre>
+—á:
+  ttlcommand 10 20
+  1st : width
+  2nd : height
+</pre>
+
+<h2>2) Keyword parameter</h2>
+
+<p>
+Passing keyword/value pairs as parameter.<br>
+Parameter can be passed in any order.
+</p>
+
+<pre>
+—á:
+  ttlcommand 'width=10' 'height=20'
+  width keyword  : width
+  height keyword : height
+</pre>
+
+<h2>3) Positional parameter + Keyword parameter</h2>
+
+<p>
+The first few are "Positional parameter", the rest are "Keyword parameter".<br>
+"Positional parameter" order is fixed, "Keyword parameter" is in no particular order.
+</p>
+
+<pre>
+—á:
+  ttlcommand 'Terminal' 'green' 'width=10' 'height=20'
+  1st            : font
+  2nd            : color
+  width keyword  : width
+  height keyword : height
+</pre>
+
+<h2>Background</h2>
+
+<p>
+"Keyword parameters" was introduced in Tera Term version 5.3 when the <A HREF="../command/listbox.html">listbox</A> command enhance to pass many parameters, and besides, to minimize the number of parameters to be specified.
+</p>
+
+</BODY>
+</HTML>

doc/en/html/macro/syntax/types.html

@@ -15,26 +15,26 @@ <h1>Types</h1>
 TTL have four kinds of data types:
 </p>
 
-<h2 id="Integer">Integer</h2>
+<h2 id="Integer">1) Integer</h2>
 <p>
 Signed 32 bit, from -2147483648 to 2147483647.<br />
 Floating point operation is not supported.
 </p>
 
-<h2 id="String">Character string</h2>
+<h2 id="String">2) Character string</h2>
 <p>
 A sequence containing any character except NUL. The maximum length of a string is 511.<br />
 Since character encoding of string literals and macro commands is UTF-8, character encoding of string variables is also naturally UTF-8.
 </p>
 
-<h2 id="IntegerArray">Integer Array</h2>
+<h2 id="IntegerArray">3) Integer Array</h2>
 <p>
 The integer array can be used by using the <a href="../command/intdim.html">intdim</a> macro command.
 The maximum index is 65536.<br />
 The element of the array equals to the integer.
 </p>
 
-<h2 id="StringArray">String Array</h2>
+<h2 id="StringArray">4) String Array</h2>
 <p>
 The string array can be used by using the <a href="../command/strdim.html">strdim</a> macro command.
 The maximum index is 65536.<br />

doc/en/teraterm.hhc

@@ -865,6 +865,11 @@
 				<param name="Local" value="html\macro\syntax\lineformats.html">
 				<param name="ImageNumber" value="11">
 				</OBJECT>
+			<LI> <OBJECT type="text/sitemap">
+				<param name="Name" value="Parameter formats">
+				<param name="Local" value="html\macro\syntax\parameter.html">
+				<param name="ImageNumber" value="11">
+				</OBJECT>
 		</UL>
 		<LI> <OBJECT type="text/sitemap">
 			<param name="Name" value="TTL command reference">