* Bug 15359 fixed: twinkle(h) could not blink several objects together
[scilab.git] / scilab / modules / graphics / help / en_US / interaction / twinkle.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2015, 2016, 2018 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19         xml:lang="en" xml:id="twinkle">
20     <refnamediv>
21         <refname>twinkle</refname>
22         <refpurpose>highlights one or more graphical objects by flashing them</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             twinkle
28             twinkle(n)
29             twinkle(h)
30             twinkle(h,n)
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection role="arguments">
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>h</term>
38                 <listitem>
39                     <para>
40                         handle or vector of handles of one or several graphical entities to blink.
41                         By default, the current graphic entity pointed by <literal>gce()</literal>
42                         is considered.
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>n</term>
48                 <listitem>
49                     <para>positive integer number: the number of blinks. Default n = 5.</para>
50                 </listitem>
51             </varlistentry>
52         </variablelist>
53     </refsection>
54     <refsection role="description">
55         <title>Description</title>
56         <para>
57             <function>twinkle</function> blinks <varname>n</varname> times graphical entities
58             handled with <varname>h</varname>. If some of the objects are initially invisible,
59             they are blinked with other ones and are finally left invisible before returning.
60         </para>
61         <para>
62             If <function>twinkle()</function> is run while no graphical figure exists,
63             it does nothing and returns. If the handle <varname>h</varname> has some invalid
64             components (the entity has been deleted in the meantime),
65             <function>twinkle(h..)</function> yields an error.
66         </para>
67     </refsection>
68     <refsection role="examples">
69         <title>Examples</title>
70         <programlisting role="example"><![CDATA[
71 clf
72 plot()
73 twinkle     // twinkles the last group of curves plotted in the plot() example
74 twinkle(3)  // twinkles it only three times
75
76 clf
77 x = linspace(-2*%pi,2*%pi,100)';
78 plot2d(x,[sin(x),cos(x)]);
79 e = gce();
80 p1 = e.children(1);
81 p2 = e.children(2);
82 twinkle(p1)       // cos plot twinkle
83 twinkle(p2,10)    // sin plot twinkle 10 times
84 twinkle(gca())    // axes twinkle
85  ]]></programlisting>
86     <para/>
87         <programlisting role="example"><![CDATA[
88 // Blinking a subset of many curves, with some initially invisible ones
89 clf
90 plot()
91 c = gca().children.children(1:10);
92 c(1:5).visible = "off";
93 sleep(5,'s')
94 twinkle(c)
95  ]]></programlisting>
96     </refsection>
97     <refsection role="see also">
98         <title>See also</title>
99         <simplelist type="inline">
100             <member>
101                 <link linkend="graphics_entities">graphics entities</link>
102             </member>
103         </simplelist>
104     </refsection>
105     <refsection role="history">
106         <title>History</title>
107         <revhistory>
108             <revision>
109                 <revnumber>6.0</revnumber>
110                 <revdescription>
111                     <para>twinkle() and twinkle(n) added.</para>
112                 </revdescription>
113             </revision>
114             <revision>
115                 <revnumber>6.1</revnumber>
116                 <revdescription>
117                     <para>Several independent objects can now be blinked together.</para>
118                 </revdescription>
119             </revision>
120         </revhistory>
121     </refsection>
122 </refentry>