/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * JavaWorld Library, Copyright 2011 Bryan Chadwick * * * * FILE: ./imagetutor/package-info.java * * * * This file is part of JavaWorld. * * * * JavaWorld is free software: you can redistribute it and/or * * modify it under the terms of the GNU General Public License * * as published by the Free Software Foundation, either version * * 3 of the License, or (at your option) any later version. * * * * JavaWorld is distributed in the hope that it will be useful, * * but WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * * GNU General Public License for more details. * * * * You should have received a copy of the GNU General Public License * * along with JavaWorld. If not, see <http://www.gnu.org/licenses/>. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /** <style> .func{ color: #BB7733; } .com{ font-style: italic; color: #880000; } .keyw{ font-weight: bold; color: #000088; } .num{ color: #00AA00; } .str{ color: #CC00AB; } img.example{ padding-left: 50px; padding-top: 20px;padding-bottom: 30px; } </style> <center><h3>JavaWorld and Image Tutorial</h3></center> <br /> <p> We've been developing a new Java library, coined <code>JavaWorld</code>, that supports the development of visual and interactive programs in the style of <a href="http://docs.racket-lang.org/">DrRacket</a>'s <a href="http://docs.racket-lang.org/teachpack/2htdpuniverse.html">2htdp/universe</a> module/teachpack, with an object-oriented twist. </p> <p> This tutorial will walk you through the setup and some of the features of the <code>JavaWorld</code>. </p> <h3>Setup, Jars, and Documentation</h3> <blockquote> <h4>Jars</h4> <p> First, you need the <a href="http://bryanchadwick.com/javaworld/JavaWorld.jar"><tt>JavaWorld.jar</tt></a>, which contains the Image and World packages/libraries. Make sure the Jar is part of your <i>build-path</i> in the <i>Project</i> you want to work from. </p> <p> The important parts of the documentation for <tt>JavaWorld</tt> are <a href="http://bryanchadwick.com/javaworld/doc/image/package-summary.html">Images</a> and <a href="http://bryanchadwick.com/javaworld/doc/world/World.html">Worlds</a>. Though the entire documentation <a href="http://bryanchadwick.com/javaworld/doc/">can be found here</a>. </p> <p> When necessary we will reference specific pages. As you become a more accomplished programmer, more and more of the library will make sense, and you'll be able to write more complex programs. Feel free to poke around, but don't get lost in all the details too quickly. We'll guide you through the basics, then you can explore more on your own as you get more experience. </p> </blockquote> <h3>Images, Scenes, and Colors</h3> <blockquote> The <tt>JavaWorld</tt> library contains lots of Java classes to help with the creation of graphical programs. Here's a review of the important ones. <h4>Images</h4> All of the <code>Image</code> classes can be used (assuming the libraries are setup appropriately) simply by importing them: <blockquote> <pre><span class='keyw'>import</span> image.*;</pre> </blockquote> The classes are similar in design to the <tt>Racket</tt> <tt>2htdp/image</tt> module that you may already be familiar with. <h4>Classes and Methods</h4> Creating images is as easy as creating instances of classes. There is a full list with <a href="http://bryanchadwick.com/javaworld/doc/image/package-summary.html">examples here</a>. But a few of the important ones are discussed below. <blockquote> <h5>Class Constructors</h5> <table style="padding-left:40px"> <tr> <td style="text-align:right"><code class='func'>EmptyScene</code></td> <td><tt>(<span class='keyw'>int</span> width, <span class='keyw'>int</span> height)</tt></td> </tr> <tr> <td style="text-align:right"><code class='func'>Circle</code></td> <td><tt>(<span class='keyw'>int</span> radius, <span>String</span> mode, <span>String</span> color)</tt></td> </tr> <tr> <td style="text-align:right"><code class='func'>Rectangle</code></td> <td><tt>(<span class='keyw'>int</span> width, <span class='keyw'>int</span> height, <span>String</span> mode, <span>String</span> color)</tt></td> </tr> <tr> <td style="text-align:right"><code class='func'>Text</code></td> <td><tt>(<span>String</span> text, <span class='keyw'>int</span> size, <span>String</span> color)</tt></td> </tr> <tr> <td style="text-align:right"><code class='func'>Star</code></td> <td><tt>(<span class='keyw'>int</span> radius, <span class='keyw'>int</span> points, <span>String</span> mode, <span>String</span> color)</tt></td> </tr> <tr> <td style="text-align:right"><code class='func'>Overlay</code></td> <td><tt>(<span>Image</span> top, <span>Image</span> bot)</tt></td> </tr> <tr> <td style="text-align:right"><code class='func'>OverlayXY</code></td> <td><tt>(<span>Image</span> top, <span class='keyw'>int</span> x, <span class='keyw'>int</span> y, <span>Image</span> bot)</tt></td> </tr> </table> </blockquote> <blockquote> <h5>Methods</h5> <blockquote> <b><tt>Scenes</tt></b> <table style="padding-left:20px"> <tr> <td><code>Scene <span class='func'>placeImage</span>(<span>Image</span> image, <span class='keyw'>int</span> x, <span class='keyw'>int</span> y)</code></td> </tr> <tr> <td><code>Scene <span class='func'>addLine</span>(<span class='keyw'>int</span> fromX, <span class='keyw'>int</span> fromY, <span class='keyw'>int</span> toX, <span class='keyw'>int</span> toY, <span>String</span> color)</code></td> </tr> </table><br /> <b><tt>Images</tt></b> <table style="padding-left:20px"> <tr> <td><code>Image <span class='func'>overlay</span>(<span>Image</span> top)</code></td> </tr> <tr> <td><code>Image <span class='func'>overlayxy</span>(<span>Image</span> top, <span class='keyw'>int</span> x, <span class='keyw'>int</span> y)</code></td> </tr> </table> </blockquote> </blockquote> See the next section or the <a href="http://bryanchadwick.com/javaworld/doc/image/package-summary.html">image documentation</a> for more descriptions and examples. </blockquote><br/> <h3>Using <code>World.display()</code></h3> <blockquote> <p> Images are pretty easy to create and compose, but in order to display them we need something a bit more complicated. To see the image(s) you create, we provide a method that pops up a window to display an <tt>Image</tt> (or a <tt>Scene</tt>). </p> <p> <h4>Simple Images/Scenes</h4> To display our images, we create a simple class that creates a <tt>Scene</tt> and displays it from within a <tt>main</tt> method, though this could also be done from within a testing framework (I.e., the <a href="http://www.ccs.neu.edu/javalib/Tester/index.html">NU Tester</a>, or <a href="http://www.junit.org/">JUnit</a>). Here's an initial example, <tt>Example1</tt>, that uses <tt>Circle</tt>, <tt>Square</tt>, and <tt>OverlayXY</tt> to create a <tt>Scene</tt>. The <tt>Scene</tt> is then <tt>display</tt>ed when the <tt>main</tt> method is run. <pre> <span class='keyw'>import</span> image.*; <span class='keyw'>import</span> world.*; <span class='keyw'>public class</span> Example1{ <span class='func'>Example1</span>(){} Scene mt = <span class='keyw'>new</span> <span class='func'>EmptyScene</span>(<span class='num'>100</span>, <span class='num'>100</span>); Image circ = <span class='keyw'>new</span> <span class='func'>Circle</span>(<span class='num'>20</span>, <span class='str'>"outline"</span>, <span class='str'>"blue"</span>); Image sqr = <span class='keyw'>new</span> <span class='func'>Square</span>(<span class='num'>40</span>, <span class='str'>"solid"</span>, <span class='str'>"palegreen"</span>); Scene scn = mt.<span class='func'>placeImage</span>(<span class='keyw'>new</span> <span class='func'>OverlayXY</span>(circ, -<span class='num'>20</span>, <span class='num'>20</span>, sqr), <span class='num'>50</span>, <span class='num'>50</span>); <span class='keyw'>public static void</span> <span class='func'>main</span>(String[] args){ World.<span class='func'>display</span>(<span class='keyw'>new</span> <span class='func'>Example1</span>().scn); } } </pre> Running this example results in a window similar to the following:<br/> <img class='example' src="images/WorldExample-1.png" /><br /> The <tt>World.display</tt> to show the constructed image/scene after we've created an instance of <tt>Example1</tt>. <tt>World.display</tt> returns a value of <tt class='keyw'>true</tt> once the popup window is closed. </p><br /> <p> <h4>Natural-Number Recursion</h4> Of course, we're not limited to hand constructed <tt>Scene</tt>s since we know how to use recursion over the <i>natural numbers</i>. <tt>Example2</tt> implements a recursive method, <tt>stars</tt>, that builds a <tt>Scene</tt>. Our base-case returns the <tt>EmptyScene</tt>, and our recursive case places (<tt>placeImage</tt>) a <tt>Star</tt> of the given <tt>size</tt> in the <tt>Scene</tt> returned by the recursive call. <pre> <span class="keyw">public class</span> Example2{ <span class="func">Example2</span>(){} <span class="com">// Create a Scene with nested stars of decreasing size</span> Scene <span class="func">stars</span>(<span class="keyw">int</span> size){ <span class="keyw">if</span>(size <= <span class="num">4</span>){ <span class="keyw">return</span> <span class="keyw">new</span> <span class="func">EmptyScene</span>(<span class="num">200</span>, <span class="num">200</span>); }<span class="keyw">else</span>{ <span class="keyw">return</span> <span class="keyw">this</span>.<span class="func">stars</span>(size-<span class="num">15</span>) .<span class="func">placeImage</span>(<span class="keyw">new</span> <span class="func">Star</span>(size, <span class="str">"outline"</span>, <span class="str">"red"</span>), <span class="num">100</span>, <span class="num">100</span>); } } Scene scn = <span class="keyw">this</span>.<span class="func">stars</span>(<span class="num">100</span>); <span class="keyw">public static void</span> <span class="func">main</span>(String[] args){ World.<span class="func">display</span>(<span class='keyw'>new</span> <span class='func'>Example2</span>().scn); } } </pre> We start with a <tt>size</tt> of <tt class='num'>100</tt>, and <tt>display</tt> the result. Running this example results in a window similar to the following:<br /> <img class='example' src="images/WorldExample-2.png" /><br /> </p> <p> <h4>Structural Recursion</h4> As you remember (hopefully), natural-number recursion is just a special case of <i>structural recursion</i> (which, in turn, is just a special case of what <a href="http://www.htdp.org/">HtDP</a> calls <i>generative recursion</i>). </p> <p> As an example of a recursive structure, below we define an interface and classes that together represent a <i>chain</i> of arbitrary length. <tt>Link</tt> and <tt>End</tt> implement <tt>IChain</tt>, which contains a single method header. What's important for this example is that we can <tt>place</tt> an image of an <tt>IChain</tt> into a given <tt>Scene</tt>. <pre> <span class="com">// Represents a Chain</span> <span class="keyw">interface</span> IChain{ <span class="com">// Place this IChain into the given Scene</span> <span class='keyw'>public</span> Scene <span class="func">place</span>(<span class="keyw">int</span> x, Scene scn); } <span class="com">// Represents a Link in a Chain</span> <span class="keyw">class</span> Link <span class="keyw">implements</span> IChain{ IChain next; <span class="func">Link</span>(IChain next){ <span class="keyw">this</span>.next = next; } <span class="com">// Place this Link into the given Scene</span> <span class='keyw'>public</span> Scene <span class="func">place</span>(<span class="keyw">int</span> x, Scene scn){ <span class="keyw">return</span> <span class="keyw">this</span>.next.<span class="func">place</span>(x+<span class="num">25</span>, scn) .<span class="func">placeImage</span>(<span class="keyw">new</span> <span class="func">Overlay</span>(<span class="keyw">new</span> <span class="func">Ellipse</span>(<span class="num">28</span>, <span class="num">13</span>, <span class="str">"outline"</span>, <span class="str">"gray"</span>), <span class="keyw">new</span> <span class="func">Ellipse</span>(<span class="num">30</span>, <span class="num">15</span>, <span class="str">"outline"</span>, <span class="str">"black"</span>)), x, <span class="num">50</span>); } } <span class="com">// Represents the end of a Chain</span> <span class="keyw">class</span> End <span class="keyw">implements</span> IChain{ <span class="func">End</span>(){} <span class="com">// The end of the chain, return the Scene</span> <span class='keyw'>public</span> Scene <span class="func">place</span>(<span class="keyw">int</span> x, Scene scn){ <span class="keyw">return</span> scn; } } </pre> </p> <p> Each of the classes implements the method, <tt>Scene place(<span class="keyw">int</span>, Scene)</tt>, which returns the appropriate scene. For the <tt>End</tt> of the <tt>IChain</tt> we simply return the given <tt>Scene</tt>. For a <tt>Link</tt> we place an <tt>Ellipse</tt> in the <tt>Scene</tt> returned by the recursive call on the <tt>next</tt> <tt>IChain</tt>. </p> <p> Now all we need to do is create an examples class that creates an <tt>IChain</tt> instance and has a test method that displays the <tt>IChain</tt> after placing it into the <tt>EmptyScene</tt>. <pre> <span class="keyw">public class</span> Example3{ <span class="func">Example3</span>(){} IChain ch = <span class="keyw">new</span> <span class="func">Link</span>(<span class="keyw">new</span> <span class="func">Link</span>(<span class="keyw">new</span> <span class="func">Link</span>( <span class="keyw">new</span> <span class="func">Link</span>(<span class="keyw">new</span> <span class="func">Link</span>(<span class="keyw">new</span> <span class="func">Link</span>(<span class="keyw">new</span> <span class="func">End</span>())))))); Scene scn = <span class="keyw">this</span>.ch.<span class="func">place</span>(<span class="num">40</span>, <span class="keyw">new</span> <span class="func">EmptyScene</span>(<span class="num">200</span>, <span class="num">100</span>)); <span class="keyw">public static void</span> <span class="func">main</span>(String[] args){ World.<span class="func">display</span>(<span class='keyw'>new</span> <span class='func'>Example3</span>().scn); } } </pre> Running this example results in a window similar to the following:<br /> <img class='example' src="images/WorldExample-3.png" /><br /> </p> </blockquote> <p> <h3>More Information</h3> <blockquote> If this leaves you craving more, have a look through the <a href="http://bryanchadwick.com/javaworld/doc/image/package-summary.html">Image</a> and <a href="http://bryanchadwick.com/javaworld/doc/world/package-summary.html">World</a> documentation. </blockquote> </p> </body> </html> */ package imagetutor;