PageRenderTime 67ms CodeModel.GetById 54ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 0ms

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

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