georg Sun Dec 30 13:58:08 2001 EDT
Modified files:
/phpdoc/en/functions ncurses.xml
Log:
Documentation for soft label key functions added
Index: phpdoc/en/functions/ncurses.xml
diff -u phpdoc/en/functions/ncurses.xml:1.4 phpdoc/en/functions/ncurses.xml:1.5
--- phpdoc/en/functions/ncurses.xml:1.4 Tue Dec 25 18:25:24 2001
+++ phpdoc/en/functions/ncurses.xml Sun Dec 30 13:58:08 2001
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<reference id="ref.ncurses">
<title>Ncurses terminal screen control functions</title>
<titleabbrev>ncurses functions</titleabbrev>
@@ -160,7 +160,7 @@
<refentry id="function.ncurses-def-prog-mode">
<refnamediv>
<refname>ncurses_def_prog_mode</refname>
- <refpurpose></refpurpose>
+ <refpurpose>Saves terminals (program) mode</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -186,7 +186,7 @@
<refentry id="function.ncurses-def-shell-mode">
<refnamediv>
<refname>ncurses_def_shell_mode</refname>
- <refpurpose></refpurpose>
+ <refpurpose>Saves terminals (shell) mode</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -738,7 +738,7 @@
<refentry id="function.ncurses-resetty">
<refnamediv>
<refname>ncurses_resetty</refname>
- <refpurpose>Restore saved terminal state </refpurpose>
+ <refpurpose>Restores saved terminal state </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -750,7 +750,13 @@
</funcsynopsis>
&warn.experimental.func;
<para>
- undocumented
+ Function <function>ncurses_resetty</function> restores the
+ terminal state, which was previously saved by calling
+ <function>ncurses_savetty</function>.
+ This function always returns &false;.
+ </para>
+ <para>
+ See also: <function>ncurses_savetty</function>
</para>
</refsect1>
</refentry>
@@ -758,7 +764,7 @@
<refentry id="function.ncurses-savetty">
<refnamediv>
<refname>ncurses_savetty</refname>
- <refpurpose>Save terminal state </refpurpose>
+ <refpurpose>Saves terminal state </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -770,15 +776,51 @@
</funcsynopsis>
&warn.experimental.func;
<para>
- undocumented
+ Function <function>ncurses_savetty</function> saves the current
+ terminal state. The saved terminal state can be restored with
+ function <function>ncurses_resetty</function>.
+ <function>ncurses_savetty</function> always returns &false;.
+ </para>
+ <para>
+ See also: <function>ncurses_resetty</function>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.ncurses-slk-init">
+ <refnamediv>
+ <refname>ncurses_slk_init</refname>
+ <refpurpose>Initializes soft label key functions</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>ncurses_slk_init</function></funcdef>
+ <paramdef>int <parameter>format</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ &warn.experimental.func;
+ <para>
+ Funtion <function>ncurses_slk_init</function> must be called
+ before <function>ncurses_initscr</function> or
+ <function>ncurses_newterm</function> is called. If
+ <function>ncurses_initscr</function> eventually uses a line from
+ stdscr to emulate the soft labels, then
+ <parameter>format</parameter> determines how the labels are
+ arranged of the screen. Setting <parameter>format</parameter> to
+ 0 indicates a 3-2-3 arrangement of the labels, 1 indicates a 4-4
+ arrangement and 2 indicates the PC like 4-4-4 mode, but in
+ addition an index line will be created.
</para>
</refsect1>
</refentry>
+
<refentry id="function.ncurses-slk-attr">
<refnamediv>
<refname>ncurses_slk_attr</refname>
- <refpurpose></refpurpose>
+ <refpurpose>Returns current soft label key attribute</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -790,7 +832,8 @@
</funcsynopsis>
&warn.experimental.func;
<para>
- undocumented
+ <function>ncurses_slk_attr</function> returns the current soft
+ label key attribute. On error returns &true;, otherwise &false;.
</para>
</refsect1>
</refentry>
@@ -798,7 +841,7 @@
<refentry id="function.ncurses-slk-clear">
<refnamediv>
<refname>ncurses_slk_clear</refname>
- <refpurpose></refpurpose>
+ <refpurpose>Clears soft labels from screen</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -810,7 +853,8 @@
</funcsynopsis>
&warn.experimental.func;
<para>
- undocumented
+ The function <function>ncurses_slk_clear</function> clears soft
+ label keys from screen. Returns &true; on error, otherwise &false;.
</para>
</refsect1>
</refentry>
@@ -818,7 +862,7 @@
<refentry id="function.ncurses-slk-noutrefresh">
<refnamediv>
<refname>ncurses_slk_noutrefresh</refname>
- <refpurpose></refpurpose>
+ <refpurpose>Copies soft label keys to virtual screen</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -838,7 +882,7 @@
<refentry id="function.ncurses-slk-refresh">
<refnamediv>
<refname>ncurses_slk_refresh</refname>
- <refpurpose></refpurpose>
+ <refpurpose>Copies soft label keys to screen</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -850,7 +894,9 @@
</funcsynopsis>
&warn.experimental.func;
<para>
- undocumented
+ <function>ncurses_slk_refresh</function> copies soft label keys
+ from virtual screen to physical screen. Returns &true; on error,
+ otherwise &false;.
</para>
</refsect1>
</refentry>
@@ -858,7 +904,7 @@
<refentry id="function.ncurses-slk-restore">
<refnamediv>
<refname>ncurses_slk_restore</refname>
- <refpurpose></refpurpose>
+ <refpurpose>Restores soft label keys</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -870,7 +916,9 @@
</funcsynopsis>
&warn.experimental.func;
<para>
- undocumented
+ The function <function>ncurses_slk_restore</function> restores
+ the soft label keys after <function>ncurses_slk_clear</function>
+ has been performed.
</para>
</refsect1>
</refentry>
@@ -878,7 +926,7 @@
<refentry id="function.ncurses-slk-touch">
<refnamediv>
<refname>ncurses_slk_touch</refname>
- <refpurpose></refpurpose>
+ <refpurpose>Fources output when ncurses_slk_noutrefresh is performed</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -890,7 +938,9 @@
</funcsynopsis>
&warn.experimental.func;
<para>
- undocumented
+ The <function>ncurses_slk_touch</function> function forces all the soft
+ labels to be output the next time a
+ <function>ncurses_slk_noutrefresh</function> is performed.
</para>
</refsect1>
</refentry>
@@ -2233,26 +2283,6 @@
</refsect1>
</refentry>
- <refentry id="function.ncurses-slk-init">
- <refnamediv>
- <refname>ncurses_slk_init</refname>
- <refpurpose></refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>ncurses_slk_init</function></funcdef>
- <paramdef>int <parameter>intarg</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- &warn.experimental.func;
- <para>
- undocumented
- </para>
- </refsect1>
- </refentry>
-
<refentry id="function.ncurses-standend">
<refnamediv>
<refname>ncurses_standend</refname>
@@ -2490,6 +2520,261 @@
&warn.experimental.func;
<para>
undocumented
+ </para>
+ </refsect1>
+ </refentry>
+
+<refentry id="function.ncurses-termname">
+ <refnamediv>
+ <refname>ncurses_termname</refname>
+ <refpurpose>Returns terminals (short)-name</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>ncurses_termname</function></funcdef>
+ <void/>
+ </funcprototype>
+ </funcsynopsis>
+ &warn.experimental.func;
+ <para>
+ <function>ncurses_termname</function> returns terminals
+ shortname. The shortname is truncated to 14 characters.
+ On error <function>ncurses_termname</function> returns NULL.
+ </para>
+ <para>
+ See also: <function>ncurses_longname</function>
+ </para>
+ </refsect1>
+ </refentry>
+
+<refentry id="function.ncurses-longname">
+ <refnamediv>
+ <refname>ncurses_longname</refname>
+ <refpurpose>Returns terminals description</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>ncurses_longname</function></funcdef>
+ <void/>
+ </funcprototype>
+ </funcsynopsis>
+ &warn.experimental.func;
+ <para>
+ <function>ncurses_longname</function> returns a verbose
+ description of the terminal. The descritpion is truncated to 128
+ characters.
+ On Error <function>ncurses_longname</function> returns NULL.
+ </para>
+ <para>
+ See also: <function>ncurses_termname</function>
+ </para>
+ </refsect1>
+ </refentry>
+
+<refentry id="function.ncurses-mousemask">
+ <refnamediv>
+ <refname>ncurses_mousemask</refname>
+ <refpurpose>Sets mouse options</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>ncurses_mousemask</function></funcdef>
+ <paramdef>int <parameter>newmask</parameter>,
+ int <parameter>oldmask</parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ &warn.experimental.func;
+ <para>
+ Function <function>ncurses_mousemask</function> will set mouse events
+ to be reported. By default no mouse events will be reported. The
+ function <function>ncurses_mousemask</function> will return a
+ mask to indicated which of the in parameter
+ <parameter>newmask</parameter>
+ specified mouse events can be reported. On complete failure, it
+ returns 0. In parameter <parameter>oldmask</parameter>, which is
+ passed by reference <function>ncurses_mousemask</function>
+ returns the previous value of mouse event mask.
+
+ Mouse events are represented bei NCURSES_KEY_MOUSE in the
+ <function>ncurses_wgetch</function> input stream. To read the
+ event data and pop the event of of queue, call
+ <function>ncurses_getmouse</function>.
+ </para>
+ <para>
+ As a side effect, setting a zero mousemask in
+ <parameter>newmask</parameter> turns off the mouse
+ pointer. Setting a non zero value turns mouse pointer on.
+ </para>
+ <para>
+ mouse mask options can be set with the following predefined
+ constants:
+ <itemizedlist>
+ <listitem><para>NCURSES_BUTTON1_PRESSED</para></listitem>
+ <listitem><para>NCURSES_BUTTON1_RELEASED</para></listitem>
+ <listitem><para>NCURSES_BUTTON1_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON1_DOUBLE_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON1_TRIPLE_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON2_PRESSED</para></listitem>
+ <listitem><para>NCURSES_BUTTON2_RELEASED</para></listitem>
+ <listitem><para>NCURSES_BUTTON2_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON2_DOUBLE_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON2_TRIPLE_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON3_PRESSED</para></listitem>
+ <listitem><para>NCURSES_BUTTON3_RELEASED</para></listitem>
+ <listitem><para>NCURSES_BUTTON3_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON3_DOUBLE_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON3_TRIPLE_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON4_PRESSED</para></listitem>
+ <listitem><para>NCURSES_BUTTON4_RELEASED</para></listitem>
+ <listitem><para>NCURSES_BUTTON4_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON4_DOUBLE_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON4_TRIPLE_CLICKED</para></listitem>
+ <listitem><para>NCURSES_BUTTON_SHIFT></para></listitem>
+ <listitem><para>NCURSES_BUTTON_CTRL</para></listitem>
+ <listitem><para>NCURSES_BUTTON_ALT</para></listitem>
+ <listitem><para>NCURSES_ALL_MOUSE_EVENTS</para></listitem>
+ <listitem><para>NCURSES_REPORT_MOUSE_POSITION</para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ See also: <function>ncurses_getmouse</function>,
+ <function>ncurses_ungetmouse</function>
+ <function>ncurese_getch</function>
+ </para>
+ <para>
+ <example>
+ <title><function>ncurses_mousemask</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+
+$newmask = NCURSES_BUTTON1_CLICKED + NCURSES_BUTTON1_RELEASED;
+$mask = ncurses_mousemask($newmask, &$oldmask);
+if ($mask & $newmask){
+ printf ("All specified mouse options will be supported\n");
+}
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+
+<refentry id="function.ncurses-getmouse">
+ <refnamediv>
+ <refname>ncurses_getmouse</refname>
+ <refpurpose>Reads mouse event</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>ncurses_getmouse</function></funcdef>
+ <paramdef>array <parameter>mevent</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ &warn.experimental.func;
+ <para>
+ <function>ncurses_getmouse</function> reads mouse event a pop
+ event out of queue. Function
+ <function>ncurses_getmouse</function> will return ;&false; if a
+ mouse event is actually visible in the given window, otherwise it
+ will return &true;.
+ Event options will be delivered in parameter
+ <parameter>mevent</parameter>, which has to be an array, passed
+ by reference (see example below).
+ On success an associative array with following keys will be
+ delivered:
+ <itemizedlist>
+ <listitem><para>"id" : Id to distinguish multiple
+ devices</para></listitem>
+ <listitem><para>"x" : screen relative x-position in character
+ cells</para></listitem>
+ <listitem><para>"y" : screen relative y-position in character
+ cells</para></listitem>
+ <listitem><para>"z" : currently not supported</para></listitem>
+ <listitem><para>"mmask" : Mouse action</para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <function>ncurses_getmouse</function> returns &false; on
+ success, otherwise &true;.
+ </para>
+ <para>
+ <example>
+ <title><function>ncurses_getmouse</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+
+switch (ncurses_getch){
+ case NCURSES_KEY_MOUSE:
+ if (!ncurses_getmouse($mevent)){
+ if ($mevent["mmask"] & NCURSES_MOUSE_BUTTON1_PRESSED){
+ $mouse_x = $mevent["x"]; // Save mouse position
+ $mouse_y = $mevent["y"];
+ }
+ }
+ break;
+
+ default:
+ ....
+}
+
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ See also: <function>ncurses_ungetmouse</function>
+ </para>
+ </refsect1>
+ </refentry>
+
+<refentry id="function.ncurses-ungetmouse">
+ <refnamediv>
+ <refname>ncurses_ungetmouse</refname>
+ <refpurpose>Pushes mouse event to queue</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>ncurses_ungetmouse</function></funcdef>
+ <paramdef>array <parameter>mevent</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ &warn.experimental.func;
+ <para>
+ <function>ncurses_getmouse</function> pushes a KEY_MOUSE event
+ onto the unput queue and associates with this event the given
+ state sata and screen-relative character cell coordinates,
+ specified in <parameter>mevent</parameter>.
+
+ Event options will be specified in associative array
+ <parameter>mevent</parameter>:
+ <itemizedlist>
+ <listitem><para>"id" : Id to distinguish multiple
+ devices</para></listitem>
+ <listitem><para>"x" : screen relative x-position in character
+ cells</para></listitem>
+ <listitem><para>"y" : screen relative y-position in character
+ cells</para></listitem>
+ <listitem><para>"z" : currently not supported</para></listitem>
+ <listitem><para>"mmask" : Mouse action</para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <function>ncurses_ungetmouse</function> returns &false; on
+ success, otherwise &true;.
+ </para>
+ <para>
+ See also: <function>ncurses_getmouse</function>
</para>
</refsect1>
</refentry>
