PageRenderTime 29ms CodeModel.GetById 0ms RepoModel.GetById 0ms app.codeStats 0ms

/www/tags/NOV_07_2009/htdocs/users-guide/helpful-methods.html

#
HTML | 92 lines | 89 code | 3 blank | 0 comment | 0 complexity | e5aff898fdaed16a0ff1ca180443684a MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0 
    

  1. <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Helpful Methods in the Macros Class</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="jEdit 4.3 User's Guide"><link rel="up" href="macro-basics.html" title="Chapter 13. Macro Basics"><link rel="prev" href="predefined-variables.html" title="Predefined Variables in BeanShell"><link rel="next" href="dynamic-typing.html" title="BeanShell Dynamic Typing"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Helpful Methods in the Macros Class</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="predefined-variables.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Macro Basics</th><td width="20%" align="right"> <a accesskey="n" href="dynamic-typing.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="helpful-methods"></a>Helpful Methods in the Macros Class</h2></div></div></div><p>Including <code class="function">message()</code>, there are five static
    2. 

  2.         methods in the <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a> class that
    3. 

  3.         allow you to converse easily with your macros. They all encapsulate
    4. 

  4.         calls to methods of the Java platform's
    5. 

  5.         <code class="classname">JOptionPane</code> class.</p><div class="itemizedlist"><ul type="disc"><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static void
    6. 

  6.                         <b class="fsfunc">message</b>(</code></td><td>Component
    7. 

  7.                          </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
    8. 

  8.                          </td><td><var class="pdparam">message</var><code>)</code>;</td></tr></table></div></li><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static void
    9. 

  9.                         <b class="fsfunc">error</b>(</code></td><td>Component
    10. 

  10.                          </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
    11. 

  11.                          </td><td><var class="pdparam">message</var><code>)</code>;</td></tr></table></div></li><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static String
    12. 

  12.                         <b class="fsfunc">input</b>(</code></td><td>Component
    13. 

  13.                          </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
    14. 

  14.                          </td><td><var class="pdparam">prompt</var><code>)</code>;</td></tr></table></div></li><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static String
    15. 

  15.                         <b class="fsfunc">input</b>(</code></td><td>Component
    16. 

  16.                          </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
    17. 

  17.                          </td><td><var class="pdparam">prompt</var>, </td></tr><tr><td> </td><td>String
    18. 

  18.                          </td><td><var class="pdparam">defaultValue</var><code>)</code>;</td></tr></table></div></li><li><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">public static int
    19. 

  19.                         <b class="fsfunc">confirm</b>(</code></td><td>Component
    20. 

  20.                          </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
    21. 

  21.                          </td><td><var class="pdparam">prompt</var>, </td></tr><tr><td> </td><td>int  </td><td><var class="pdparam">buttons</var><code>)</code>;</td></tr></table></div></li></ul></div><p>The format of these four <em class="glossterm">declarations</em>
    22. 

  22.         provides a concise reference to the way in which the methods may be
    23. 

  23.         used. The keyword <code class="function">public</code> means that the method can
    24. 

  24.         be used outside the <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a> class. The
    25. 

  25.         alternatives are <code class="function">private</code> and
    26. 

  26.         <code class="function">protected</code>. For purposes of BeanShell, you just have
    27. 

  27.         to know that BeanShell can only use public methods of other Java
    28. 

  28.         classes. The keyword <code class="function">static</code> we have already
    29. 

  29.         discussed. It means that the method does not operate on a particular
    30. 

  30.         object. You call a static function using the name of the class (like
    31. 

  31.         <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a>) rather
    32. 

  32.         than the name of a particular object (like <code class="varname">view</code>). The
    33. 

  33.         third word is the type of the value returned by the method. The keyword
    34. 

  34.         <code class="function">void</code> is Java's way of saying the the method does
    35. 

  35.         not have a return value.</p><p>The <code class="function">error()</code> method works just like
    36. 

  36.         <code class="function">message()</code> but displays an error icon in the message
    37. 

  37.         box. The <code class="function">input()</code> method furnishes a text field for
    38. 

  38.         input, an <span class="guilabel"><strong>OK</strong></span> button and a
    39. 

  39.         <span class="guilabel"><strong>Cancel</strong></span> button. If <span class="guilabel"><strong>Cancel</strong></span> is
    40. 

  40.         pressed, the method returns <code class="constant">null</code>. If
    41. 

  41.         <span class="guilabel"><strong>OK</strong></span> is pressed, a <code class="classname">String</code>
    42. 

  42.         containing the contents of the text field is returned. Note that there
    43. 

  43.         are two forms of the <code class="function">input()</code> method; the first form
    44. 

  44.         with two parameters displays an empty input field, the other forms lets
    45. 

  45.         you specify an initial, default input value.</p><p>For those without Java experience, it is important to know that
    46. 

  46.         <code class="constant">null</code> is <span class="emphasis"><em>not</em></span> the same as an
    47. 

  47.         empty, &#8220;<span class="quote">zero-length</span>&#8221; <code class="classname">String</code>. It is
    48. 

  48.         Java's way of saying that there is no object associated with this
    49. 

  49.         variable. Whenever you seek to use a return value from
    50. 

  50.         <code class="function">input()</code> in your macro, you should test it to see if
    51. 

  51.         it is <code class="constant">null</code>. In most cases, you will want to exit
    52. 

  52.         gracefully from the script with a <code class="function">return</code> statement,
    53. 

  53.         because the presence of a null value for an input variable usually means
    54. 

  54.         that the user intended to cancel macro execution. BeanShell will
    55. 

  55.         complain if you call any methods on a <code class="constant">null</code>
    56. 

  56.         object.</p><p>The <code class="function">confirm()</code> method in the <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a> class is a
    57. 

  57.         little more complex. The <code class="varname">buttons</code> parameter has an
    58. 

  58.         <code class="classname">int</code> type, and the usual way to supply a value is
    59. 

  59.         to use one of the predefined values taken from Java's
    60. 

  60.         <code class="classname">JOptionPane</code> class. You can choose among
    61. 

  61.         <code class="constant">JOptionPane.YES_NO_OPTION</code>,
    62. 

  62.         <code class="constant">JOptionPane.YES_NO_CANCEL_OPTION</code>, or
    63. 

  63.         <code class="constant">JOptionPane.OK_CANCEL_OPTION</code>. The return value of
    64. 

  64.         the method is also an <code class="classname">int</code>, and should be tested
    65. 

  65.         against the value of other predefined constants:
    66. 

  66.         <code class="constant">JOptionPane.YES_OPTION</code>,
    67. 

  67.         <code class="constant">JOptionPane.NO_OPTION</code>,
    68. 

  68.         <code class="constant">JOptionPane.OK_OPTION</code> or
    69. 

  69.         <code class="constant">JOptionPane.CANCEL_OPTION</code>.</p><p>We've looked at using <code class="function">Macros.message()</code>. To
    70. 

  70.         use the other methods, you would write something like the
    71. 

  71.         following:</p><div class="informalexample"><pre class="programlisting">Macros.error(view, "Goodbye, cruel world!");
    72. 

  72. 

  73. String result = Macros.input(view, "Type something here.");
    74. 

  74. 

  75. String result = Macros.input(view, "When were you born?",
    76. 

  76.     "I don't remember, I was very young at the time");
    77. 

  77. 

  78. int result = Macros.confirm(view, "Do you really want to learn"
    79. 

  79.     + " about BeanShell?",JOptionPane.YES_NO_OPTION);
    80. 

  80.     </pre></div><p>In the last three examples, placing the word
    81. 

  81.         <code class="classname">String</code> or <code class="classname">int</code> before the
    82. 

  82.         variable name <code class="varname">result</code> tells BeanShell that the
    83. 

  83.         variable refers to an integer or a <code class="classname">String</code> object,
    84. 

  84.         even before a particular value is assigned to the variable. In
    85. 

  85.         BeanShell, this <em class="glossterm">declaration</em> of the
    86. 

  86.         <em class="glossterm">type</em> of <code class="varname">result</code> is not
    87. 

  87.         necessary; BeanShell can figure it out when the macro runs. This can be
    88. 

  88.         helpful if you are not comfortable with specifying types and classes;
    89. 

  89.         just use your variables and let BeanShell worry about it.</p><p>Note that macros are not limited to using these methods for
    90. 

  90.         presenting a user interface. In fact, full-blown user interfaces using
    91. 

  91.         the Java Swing APIs are also possible, and will be covered later on in
    92. 

  92.         <a class="xref" href="dialog-macro.html" title="Chapter 14. A Dialog-Based Macro">Chapter 14, <i>A Dialog-Based Macro</i></a>.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="predefined-variables.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="macro-basics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dynamic-typing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Predefined Variables in BeanShell </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> BeanShell Dynamic Typing</td></tr></table></div></body></html>
    93. 

  93.