PageRenderTime 50ms CodeModel.GetById 19ms 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. methods in the <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a> class that
  3. allow you to converse easily with your macros. They all encapsulate
  4. calls to methods of the Java platform's
  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. <b class="fsfunc">message</b>(</code></td><td>Component
  7.  </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
  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. <b class="fsfunc">error</b>(</code></td><td>Component
  10.  </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
  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. <b class="fsfunc">input</b>(</code></td><td>Component
  13.  </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
  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. <b class="fsfunc">input</b>(</code></td><td>Component
  16.  </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
  17.  </td><td><var class="pdparam">prompt</var>, </td></tr><tr><td> </td><td>String
  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. <b class="fsfunc">confirm</b>(</code></td><td>Component
  20.  </td><td><var class="pdparam">comp</var>, </td></tr><tr><td> </td><td>String
  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. provides a concise reference to the way in which the methods may be
  23. used. The keyword <code class="function">public</code> means that the method can
  24. be used outside the <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a> class. The
  25. alternatives are <code class="function">private</code> and
  26. <code class="function">protected</code>. For purposes of BeanShell, you just have
  27. to know that BeanShell can only use public methods of other Java
  28. classes. The keyword <code class="function">static</code> we have already
  29. discussed. It means that the method does not operate on a particular
  30. object. You call a static function using the name of the class (like
  31. <a class="ulink" href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a>) rather
  32. than the name of a particular object (like <code class="varname">view</code>). The
  33. third word is the type of the value returned by the method. The keyword
  34. <code class="function">void</code> is Java's way of saying the the method does
  35. not have a return value.</p><p>The <code class="function">error()</code> method works just like
  36. <code class="function">message()</code> but displays an error icon in the message
  37. box. The <code class="function">input()</code> method furnishes a text field for
  38. input, an <span class="guilabel"><strong>OK</strong></span> button and a
  39. <span class="guilabel"><strong>Cancel</strong></span> button. If <span class="guilabel"><strong>Cancel</strong></span> is
  40. pressed, the method returns <code class="constant">null</code>. If
  41. <span class="guilabel"><strong>OK</strong></span> is pressed, a <code class="classname">String</code>
  42. containing the contents of the text field is returned. Note that there
  43. are two forms of the <code class="function">input()</code> method; the first form
  44. with two parameters displays an empty input field, the other forms lets
  45. you specify an initial, default input value.</p><p>For those without Java experience, it is important to know that
  46. <code class="constant">null</code> is <span class="emphasis"><em>not</em></span> the same as an
  47. empty, &#8220;<span class="quote">zero-length</span>&#8221; <code class="classname">String</code>. It is
  48. Java's way of saying that there is no object associated with this
  49. variable. Whenever you seek to use a return value from
  50. <code class="function">input()</code> in your macro, you should test it to see if
  51. it is <code class="constant">null</code>. In most cases, you will want to exit
  52. gracefully from the script with a <code class="function">return</code> statement,
  53. because the presence of a null value for an input variable usually means
  54. that the user intended to cancel macro execution. BeanShell will
  55. complain if you call any methods on a <code class="constant">null</code>
  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. little more complex. The <code class="varname">buttons</code> parameter has an
  58. <code class="classname">int</code> type, and the usual way to supply a value is
  59. to use one of the predefined values taken from Java's
  60. <code class="classname">JOptionPane</code> class. You can choose among
  61. <code class="constant">JOptionPane.YES_NO_OPTION</code>,
  62. <code class="constant">JOptionPane.YES_NO_CANCEL_OPTION</code>, or
  63. <code class="constant">JOptionPane.OK_CANCEL_OPTION</code>. The return value of
  64. the method is also an <code class="classname">int</code>, and should be tested
  65. against the value of other predefined constants:
  66. <code class="constant">JOptionPane.YES_OPTION</code>,
  67. <code class="constant">JOptionPane.NO_OPTION</code>,
  68. <code class="constant">JOptionPane.OK_OPTION</code> or
  69. <code class="constant">JOptionPane.CANCEL_OPTION</code>.</p><p>We've looked at using <code class="function">Macros.message()</code>. To
  70. use the other methods, you would write something like the
  71. following:</p><div class="informalexample"><pre class="programlisting">Macros.error(view, "Goodbye, cruel world!");
  72. String result = Macros.input(view, "Type something here.");
  73. String result = Macros.input(view, "When were you born?",
  74. "I don't remember, I was very young at the time");
  75. int result = Macros.confirm(view, "Do you really want to learn"
  76. + " about BeanShell?",JOptionPane.YES_NO_OPTION);
  77. </pre></div><p>In the last three examples, placing the word
  78. <code class="classname">String</code> or <code class="classname">int</code> before the
  79. variable name <code class="varname">result</code> tells BeanShell that the
  80. variable refers to an integer or a <code class="classname">String</code> object,
  81. even before a particular value is assigned to the variable. In
  82. BeanShell, this <em class="glossterm">declaration</em> of the
  83. <em class="glossterm">type</em> of <code class="varname">result</code> is not
  84. necessary; BeanShell can figure it out when the macro runs. This can be
  85. helpful if you are not comfortable with specifying types and classes;
  86. just use your variables and let BeanShell worry about it.</p><p>Note that macros are not limited to using these methods for
  87. presenting a user interface. In fact, full-blown user interfaces using
  88. the Java Swing APIs are also possible, and will be covered later on in
  89. <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>