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

/www/tags/NOV_07_2009/htdocs/42docs/users-guide/first-example.html

#
HTML | 138 lines | 138 code | 0 blank | 0 comment | 0 complexity | 1c6d4c2b2d08f0cf0cf776b8c0dc2e8f 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>The Mandatory First Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="jEdit 4.2 User's Guide"><link rel="up" href="macro-basics.html" title="Chapter 13. Macro Basics"><link rel="previous" href="single-macros.html" title="Single Execution Macros"><link rel="next" href="predefined-variables.html" title="Predefined Variables in BeanShell"></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">The Mandatory First Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="single-macros.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Macro Basics</th><td width="20%" align="right"> <a accesskey="n" href="predefined-variables.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="first-example"></a>The Mandatory First Example</h2></div></div><div></div></div><div class="informalexample"><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting">Macros.message(view, "Hello world!");</pre></td></tr></table></div><p>
  2. Running this one line script causes jEdit to display a message
  3. box (more precisely, a <tt class="classname">JOptionPane</tt> object) with
  4. the traditional beginner's message and an <span><b class="guilabel">OK</b></span> button.
  5. Let's see what is happening here.
  6. </p><p>
  7. This statement calls a static method (or function) named
  8. <tt class="function">message</tt> in jEdit's <a href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a>
  9. class. If you don't know anything about classes or static methods or
  10. Java (or C++, which employs the same concept), you will need to gain
  11. some understanding of a few terms. Obviously this is not the place for
  12. academic precision, but if you are entirely new to object-oriented
  13. programming, here are a few skeleton ideas to help you with BeanShell.
  14. </p><div class="itemizedlist"><ul type="disc"><li><p>
  15. An <i class="glossterm">object</i> is a collection of data that can be
  16. initialized, accessed and manipulated in certain defined ways.
  17. </p></li><li><p>
  18. A <i class="glossterm">class</i> is a specification of what data an object
  19. contains and what methods can be used to work with the data. A Java
  20. application consists of one or more classes (in the case of jEdit ,over
  21. 600 classes) written by the programmer that defines the application's
  22. behavior. A BeanShell macro uses these classes, along with built-in
  23. classes that are supplied with the Java platform, to define its own
  24. behavior.
  25. </p></li><li><p>
  26. A <i class="glossterm">subclass</i> (or child class) is a class which
  27. uses (or &#8220;<span class="quote">inherits</span>&#8221;) the data and methods of its parent
  28. class along with additions or modifications that alter the subclass's
  29. behavior. Classes are typically organized in hierarchies of parent
  30. and child classes to organize program code, to define common
  31. behavior in shared parent class code, and to specify the types of
  32. similar behavior that child classes will perform in their own specific ways.
  33. </p></li><li><p>
  34. A <i class="glossterm">method</i> (or function) is a procedure that works
  35. with data in a particular object, other data (including other objects)
  36. supplied as <i class="glossterm">parameters</i>, or both. Methods
  37. typically are applied to a particular object which is an
  38. <i class="glossterm">instance</i> of the class to which the method
  39. belongs.
  40. </p></li><li><p>
  41. A <i class="glossterm">static method</i> differs from other methods
  42. in that it does not deal with the data in a particular object but is
  43. included within a class for the sake of convenience.
  44. </p></li></ul></div><p>
  45. Java has a rich set of classes defined as part of the Java platform.
  46. Like all Java applications, jEdit is organized as a set of classes that
  47. are themselves derived from the Java platform's classes. We will refer
  48. to <i class="firstterm">Java classes</i> and <i class="firstterm">jEdit
  49. classes</i> to make this distinction. Some of jEdit's classes
  50. (such as those dealing with regular expressions and XML) are derived
  51. from or make use of classes in other open-source Java packages. Except
  52. for BeanShell itself, we won't be discussing them in this guide.
  53. </p><p>
  54. In our one line script, the static method
  55. <tt class="function">Macros.message()</tt> has two parameters because that is
  56. the way the method is defined in the <a href="../api/org/gjt/sp/jedit/Macros.html" target="_top">Macros</a>
  57. class. You must specify both parameters when you call the function. The
  58. first parameter, <i class="parameter"><tt>view</tt></i>, is a variable naming
  59. the current, active <a href="../api/org/gjt/sp/jedit/View.html" target="_top">View</a> object. Information
  60. about pre-defined variables can be found in <a href="predefined-variables.html" title="Predefined Variables in BeanShell">the section called &#8220;Predefined Variables in BeanShell&#8221;</a>.
  61. </p><p>
  62. The second parameter, which appears to be quoted text, is a
  63. <i class="glossterm">string literal</i> - a sequence of characters of
  64. fixed length and content. Behind the scenes, BeanShell and Java take
  65. this string literal and use it to create a <tt class="classname">String</tt>
  66. object. Normally, if you want to create an object in Java or BeanShell,
  67. you must construct the object using the <tt class="function">new</tt> keyword
  68. and a <i class="firstterm">constructor</i> method that is part of the
  69. object's class. We'll show an example of that later. However, both Java
  70. and BeanShell let you use a string literal anytime a method's parameter
  71. calls for a <tt class="classname">String</tt>.
  72. </p><p>
  73. If you are a Java programmer, you might wonder about a few things
  74. missing from this one line program. There is no class definition, for
  75. example. You can think of a BeanShell script as an implicit definition
  76. of a <tt class="function">main()</tt> method in an anonymous class. That is
  77. in fact how BeanShell is implemented; the class is derived from
  78. a BeanShell class called <a href="../api/bsh/XThis.html" target="_top">XThis</a>. If you
  79. don't find that helpful, just think of a script as one or more blocks of
  80. procedural statements conforming to Java syntax rules. You will also get
  81. along fine (for the most part) with C or C++ syntax if you leave out
  82. anything to do with pointers or memory management - Java and BeanShell
  83. do not have pointers and deal with memory management automatically.
  84. </p><p>
  85. Another missing item from a Java perspective is a
  86. <tt class="function">package</tt> statement. In Java, such a statement is
  87. used to bundle together a number of files so that their classes become
  88. visible to one another. Packages are not part of BeanShell,
  89. and you don't need to know anything about them to write
  90. BeanShell macros.
  91. </p><p>
  92. Finally, there are no <tt class="function">import</tt> statements in this
  93. script. In Java, an <tt class="function">import</tt> statement makes public
  94. classes from other packages visible within the file in which the
  95. statement occurs without having to specify a fully
  96. qualified class name. Without an import statement or a fully qualified
  97. name, Java cannot identify most classes using a single name as an identifier.
  98. </p><p>
  99. jEdit automatically imports a number of commonly-used packages into the
  100. namespace of every BeanShell script. Because of this, the script output
  101. of a recorded macro does not contain <tt class="function">import</tt>
  102. statements. For the same reason, most BeanShell scripts you write will
  103. not require <tt class="function">import</tt> statements.
  104. </p><p>
  105. Java requires <tt class="literal">import</tt> statement to be located
  106. at the beginning of a source file. BeanShell allows you to place
  107. <tt class="literal">import</tt>
  108. statements anywhere in a script, including inside a block of
  109. statements. The <tt class="literal">import</tt> statement will cover all names
  110. used following the statement in the enclosing block.
  111. </p><p>
  112. If you try to use a class that is not imported without its
  113. fully-qualified name, the BeanShell interpreter will complain with an
  114. error message relating to the offending line of code.
  115. </p><div class="sidebar"><p>
  116. Here is the full list of packages automatically imported by jEdit:
  117. </p><table border="0" bgcolor="#E0E0E0"><tr><td><pre class="programlisting">java.awt
  118. java.awt.event
  119. java.net
  120. java.util
  121. java.io
  122. java.lang
  123. javax.swing
  124. javax.swing.event
  125. org.gjt.sp.jedit
  126. org.gjt.sp.jedit.browser
  127. org.gjt.sp.jedit.buffer
  128. org.gjt.sp.jedit.gui
  129. org.gjt.sp.jedit.help
  130. org.gjt.sp.jedit.io
  131. org.gjt.sp.jedit.msg
  132. org.gjt.sp.jedit.options
  133. org.gjt.sp.jedit.pluginmgr
  134. org.gjt.sp.jedit.print
  135. org.gjt.sp.jedit.search
  136. org.gjt.sp.jedit.syntax
  137. org.gjt.sp.jedit.textarea
  138. org.gjt.sp.util</pre></td></tr></table></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="single-macros.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="predefined-variables.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Single Execution Macros </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Predefined Variables in BeanShell</td></tr></table></div></body></html>