| <?xml version="1.0"?> |
| |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| |
| --> |
| |
| <!-- ========================================================================= --> |
| <!-- author vincent.hardy@eng.sun.com --> |
| <!-- version $Id: svgviewer.xml 201374 2004-08-18 07:17:26Z vhardy $ --> |
| <!-- ========================================================================= --> |
| |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd"> |
| <document> |
| <header> |
| <title>Squiggle, the SVG Browser</title> |
| </header> |
| |
| <body> |
| <p> |
| This page describes the main features of Squiggle, the SVG browser that |
| comes with Batik. |
| </p> |
| |
| <section id="downloading"> |
| <title>Downloading the browser</title> |
| |
| <p> |
| Refer to the <a href="site:download">download page</a> to find out |
| how to download Batik. Refer to the |
| <a href="site:install">installation page</a> for |
| instructions on how to install the Batik download on your system. |
| </p> |
| </section> |
| |
| <section id="starting"> |
| <title>Starting the browser</title> |
| <p> |
| The method for starting the browser depends on the distribution of Batik |
| that you chose to download. The following describes how to start the |
| browser for each distribution (binary and source). |
| </p> |
| |
| <section id="starting-binary"> |
| <title>Starting the browser for the binary distribution</title> |
| |
| <p> |
| If you downloaded the <a href="../install.html#distributions">binary |
| distribution</a> of Batik, you should have a file called |
| <code>batik-1.6.zip</code> (or similar), which, when expanded, |
| created a <code>batik-squiggle.jar</code> file. To start the browser, |
| type the following on the command line: |
| </p> |
| <source>cd <em>installation-directory</em> |
| java -jar batik-squiggle.jar</source> |
| <p>You can pass options on the command line:</p> |
| <source>java -jar batik-squiggle.jar <em>[</em><strong>-font-size</strong> <em>font-size] [URIs]</em></source> |
| <p>where:</p> |
| <dl class="options"> |
| <dt><strong>-font-size</strong> <em>font-size</em></dt> |
| <dd> |
| <p>specifies the font size to use in windows and menus, and</p> |
| </dd> |
| <dt><em>[URIs]</em></dt> |
| <dd> |
| <p>specifies the URIs for the SVG documents the browser should open |
| when it starts.</p> |
| </dd> |
| </dl> |
| <p>For example:</p> |
| <source>java -jar batik-squiggle.jar -font-size 10</source> |
| <p>starts the browser with a small widget text font size, and:</p> |
| <source>java -jar batik-squiggle.jar -font-size 10 samples/batikLogo.svg</source> |
| <p>starts the browser with the <code>batikLogo.svg</code> file open and |
| uses a small widget text font size.</p> |
| <p> |
| If you are using Mac OS X, and you have generated the Squiggle |
| application bundle, you can use its icon to start the browser. |
| This is the preferred way to start the browser under Mac OS X, |
| as it ensures better integration with the operating system |
| (a nicer looking menu and dock icon). |
| </p> |
| </section> |
| |
| <section id="starting-source"> |
| <title>Starting the browser for the source distribution</title> |
| |
| <p> |
| If you downloaded the <a href="../install.html#distributions">source |
| distribution</a> of Batik, you should have a zip file |
| called <code>batik-src-1.6.zip</code> (or similar) that expanded into |
| a directory called <code>xml-batik</code> or |
| <code>batik-<em>version</em></code>. In that directory, you can find |
| build scripts for the platform you are running on. For example, there |
| is a <code>build.bat</code> script for users of the Windows platform |
| and there is a <code>build.sh</code> script for UNIX users. |
| </p> |
| <p> |
| To start the browser you should: |
| </p> |
| <ul> |
| <li> |
| Make sure that your <code>JAVA_HOME</code> environment variable is |
| set to your JDK installation directory |
| </li> |
| <li> |
| Open a command line window and change to the <code>xml-batik</code> |
| or <code>batik-<em>version</em></code> directory where the Batik |
| distribution was expanded |
| </li> |
| <li> |
| <p> |
| For Windows, type the following at the command prompt: |
| </p> |
| <source>build squiggle</source> |
| <p> |
| and for Unix and Mac OS X: |
| </p> |
| <source>./build.sh squiggle</source> |
| <p>This will start the browser.</p> |
| </li> |
| </ul> |
| <p>You can pass options to the browser as follows, for Windows:</p> |
| <source>build squiggle <em>[</em><strong>-font-size</strong> <em>font-size] [URIs]</em></source> |
| <p>and for Unix:</p> |
| <source>./build.sh squiggle <em>[</em><strong>-font-size</strong> <em>font-size] [URIs]</em></source> |
| <p> |
| Refer to <a href="#starting-binary">“Starting the browser for the |
| binary distribution”</a> for an explanation of these options. |
| </p> |
| <p> |
| Note that the number of files that can be opened on Windows from the |
| command line is limited because batch files take at most 9 |
| parameters. |
| </p> |
| </section> |
| |
| <section id="screenshot"> |
| <title>Squiggle screenshot</title> |
| <p> |
| The following image shows the result of starting the browser, from the |
| binary or source distribution, with the <code>-font-size 10 |
| samples/batikFX.svg</code> options. |
| </p> |
| |
| <div class="figure"><img src="images/svgviewerDefaultRegular.png" |
| alt="Screenshot of Squiggle showing the batikFX.svg sample"/> |
| </div> |
| |
| </section> |
| </section> |
| |
| <section id="viewing"> |
| <title>Viewing SVG documents</title> |
| <p> |
| The browser has several features to view and browse SVG documents: |
| </p> |
| <ul> |
| <li><a href="#localFile">Opening a local SVG file</a></li> |
| <li><a href="#urlFile">Opening an SVG file from the web</a></li> |
| <li><a href="#locationBar">Using the location text field to view an SVG file</a></li> |
| <li><a href="#browsing">Browsing SVG files</a></li> |
| <li><a href="#viewingMultiple">Viewing multiple SVG files</a></li> |
| </ul> |
| |
| <section id="localFile"> |
| <title>Opening a local SVG file</title> |
| <p> |
| In situations where you want to open SVG files locally on the machine |
| where you are running Squiggle, you can use <strong>File→Open |
| File</strong> menu item to open that file, or use the |
| <strong>Ctrl-F</strong> key accelerator. Doing so brings up a file |
| chooser that lets you select the file you want to view. |
| </p> |
| |
| <div class="figure"><img src="images/svgviewerFileOpen.png" |
| alt="Screenshot of Squiggle showing the 'File→Open' menu and file chooser"/> |
| </div> |
| </section> |
| |
| <section id="urlFile"> |
| <title>Opening an SVG file from the web</title> |
| <p> |
| There are many situations where the SVG content you want to view is |
| not local to the machine where Squiggle is running. In that case, you |
| can use the <strong>File→Open Location</strong> menu item, or |
| use the <strong>Ctrl-A</strong> key accelerator to open that page. |
| Doing so brings up a dialog box where you can type in the URL for the |
| file you want to view. |
| </p> |
| |
| <div class="figure"><img src="images/svgviewerOpenPage.png" |
| alt="Screenshot of Squiggle showing the 'File→Open Location' menu and window"/> |
| </div> |
| </section> |
| |
| <section id="locationBar"> |
| <title>Using the location bar text field to view an SVG file</title> |
| <p> |
| When you know the URL of the document you want to view, |
| you can enter it directly in the location bar text field |
| at the top of Squiggle, the same way you can enter a URL |
| in an HTML browser. |
| </p> |
| |
| <div class="figure"><img src="images/svgviewerLocationBar.png" |
| alt="Screenshot of Squiggle showing the location bar"/> |
| </div> |
| </section> |
| |
| <section id="browsing"> |
| <title>Browsing SVG files</title> |
| <p> |
| As with HTML content, it is common to navigate back and forth between |
| SVG files (remember that SVG files contain hyperlinks, just like HTML |
| does) and, as described later in this document, it is possible to |
| <a href="#zoomInOut">zoom</a> into SVG documents, |
| <a href="#panning">pan</a> and <a href="#rotating">rotate</a>. |
| </p> |
| |
| <div class="figure"><img src="images/svgviewerBrowsing.png" |
| alt="Screnshot of Squiggle showing the 'Go' menu"/> |
| </div> |
| |
| <p> |
| Squiggle offers multiple features to help you browse SVG files: |
| </p> |
| <dl> |
| <dt>Navigating between files</dt> |
| <dd> |
| <p> |
| The <strong>Go→Back</strong> menu item (or the |
| <strong>Ctrl-left arrow</strong> keyboard accelerator) and the |
| <strong>Go→Forward</strong> menu item (or the |
| <strong>Ctrl-right arrow</strong> keyboard accelerator) let you |
| move to the previous and next visited SVG documents. |
| </p> |
| </dd> |
| <dt>History</dt> |
| <dd> |
| <p> |
| The <strong>Go</strong> menu also contains a list of previously |
| viewed SVG documents, which gives you a way to randomly access any |
| document you have already visited. |
| </p> |
| </dd> |
| <dt>Navigating between views</dt> |
| <dd> |
| <p> |
| The <strong>View→Previous Transform</strong> menu item |
| (<strong>Ctrl-K</strong>) and the <strong>View→Next |
| Transform</strong> menu item (<strong>Ctrl-L</strong>) let you go |
| to the previous or next view of the document. This is useful when, |
| for example, you <a href="#panning">pan</a> or |
| <a href="#rotating">rotate</a> the document and want to go back to |
| the previous view you had of the document (i.e., before you panned |
| or rotated it). |
| </p> |
| </dd> |
| </dl> |
| </section> |
| |
| <section id="viewingMultiple"> |
| <title>Viewing multiple SVG files</title> |
| |
| <div class="figure"><img src="images/svgviewerMultipleFiles.png" |
| alt="Screenshot of Squiggle with two windows open"/> |
| </div> |
| |
| <p> |
| Squiggle can display multiple files simultaneously in different |
| windows. To view a new file in a separate window, simply select the |
| <strong>File→New Window</strong> menu item or use the |
| <strong>Ctrl-N</strong> keyboard accelerator. |
| </p> |
| </section> |
| |
| <section id="reloading"> |
| <title>Reloading an SVG document</title> |
| |
| <p> |
| When working on an SVG document, you may want the browser to reprocess |
| a document that you have modified. The <strong>File→Reload |
| Document</strong> menu item or the <strong>Ctrl-R</strong> keyboard |
| accelerator will cause the document to be reprocessed by the browser. |
| </p> |
| </section> |
| </section> |
| |
| <section id="exportAndPrint"> |
| <title>Exporting and printing SVG documents</title> |
| <p> |
| The <strong>File→Print</strong> menu item or |
| <strong>Ctrl-P</strong> will print the currently displayed SVG document. |
| </p> |
| <p> |
| The <strong>File→Export As</strong> menu item offers the option |
| to export the currently displayed SVG document to various raster |
| formats. Currently, the browser supports the |
| <abbr title="Portable Network Graphics">PNG</abbr>, |
| <abbr title="Joint Photographic Expert Group">JPEG</abbr> and |
| <abbr title="Tagged Image File Format">TIFF</abbr> formats. |
| </p> |
| </section> |
| |
| <section id="inspecting"> |
| <title>Inspecting the SVG source</title> |
| |
| <p> |
| The browser offers two ways to inspect the source of an SVG document: |
| <a href="#viewingSource">viewing the plain source</a> or |
| <a href="#viewingTree">viewing the document tree</a>. Both are explained |
| below. |
| </p> |
| |
| <section id="viewingSource"> |
| <title>Viewing the source</title> |
| <div class="figure"><img src="images/svgviewerViewSource.png" |
| alt="Screenshot of Squiggle showing the 'View→View Source' menu item and the source window"/> |
| </div> |
| |
| <p> |
| When the browser displays an SVG file, you can select the |
| <strong>View→View Source...</strong> menu item or use the |
| <strong>Ctrl-U</strong> keyboard accelerator to view the source code. |
| </p> |
| </section> |
| |
| <section id="viewingTree"> |
| <title>Viewing the document tree</title> |
| <div class="figure"><img src="images/svgviewerViewTree.png" |
| alt="Screenshot of Squiggle showing the 'View→DOM Viewer...' menu item and the DOM viewer window"/> |
| </div> |
| |
| <p> |
| When the browser displays an SVG file, you can select the |
| <strong>View→DOM Viewer...</strong> menu item or use the |
| <strong>Ctrl-D</strong> keyboard accelerator to open a window that |
| shows the SVG document in the form of a tree. The window lets you |
| navigate the tree, select individual elements, such as a path |
| elements, and view the attributes and CSS values that apply to these |
| elements. While the View Source window shows the SVG source as it |
| was when it was loaded, the DOM Viewer window reflects the current |
| state of the document, including any modifications that have occurred |
| due to script. |
| </p> |
| </section> |
| </section> |
| |
| <section id="configuring"> |
| <title>Configuring Squiggle</title> |
| |
| <p> |
| The <strong>Edit→Preferences</strong> menu item or |
| <strong>Ctrl-G</strong> brings up the dialog box shown in the following |
| figure. |
| </p> |
| |
| <div class="figure"><img src="images/svgviewerPreferences.png" |
| alt="Screenshot of Squiggle with the Preferences window open"/> |
| </div> |
| |
| <p> |
| This dialog contains several types of options, which can be selected |
| with the left-hand side list. For each type of option, a panel lets you |
| configure various browser parameters: |
| </p> |
| <dl> |
| <dt>General panel</dt> |
| <dd> |
| <p> |
| This panel lets you choose some optional behavior: |
| </p> |
| <dl> |
| <dt>Enable double buffering</dt> |
| <dd> |
| When on, the browser uses additional memory resources |
| which improves the quality of effects such as zooming and panning. |
| </dd> |
| <dt>Show Rendering</dt> |
| <dd> |
| When on, the browser will update the canvas while processing an |
| SVG document. This turns on progressive rendering. |
| </dd> |
| <dt>Automatically resize window to document size</dt> |
| <dd> |
| When on, the browser window is resized to fit any newly loaded |
| document. |
| </dd> |
| <dt>Animation rate limiting</dt> |
| <dd> |
| This set of radio buttons determines how often animation |
| updates are performed. This can be set as a maximum percentage |
| of CPU time to use, a maximum number of frames per second, or |
| to perform as many updates as possible (unlimited). |
| </dd> |
| <dt>Print debugging information to console</dt> |
| <dd> |
| When on, some debug messages will be printed to the standard |
| output. This is will likely interest only developers. |
| </dd> |
| <dt>Use a validating XML parser</dt> |
| <dd> |
| When on, the XML parser used to load documents will be in |
| validating mode. This means that the document will be validated |
| against the DTD when it is loaded, and external DTD subsets |
| will be fetched. |
| </dd> |
| </dl> |
| </dd> |
| |
| <dt>Security panel</dt> |
| <dd> |
| <p> |
| This panel has options relating to the script and resource |
| access in documents. |
| </p> |
| </dd> |
| |
| <dt>Language panel</dt> |
| <dd> |
| <p> |
| This is the panel shown in the above figure. That panel lets you |
| select your languages. The user language can be used in SVG documents |
| to choose between alternate contents. For example, open the |
| <code>samples/moonPhases.svg</code> example. Then, change the user |
| language to French and <a href="#reloading">reload</a> the document |
| (<strong>Ctrl-R</strong>). You will see that the text is now |
| displayed in French. You can do the same with Japanese and the text |
| will be shown in Japanese. |
| </p> |
| </dd> |
| |
| <dt>Stylesheet panel</dt> |
| <dd> |
| This panel lets you specify a user stylesheet which can override some |
| of the default settings in viewed SVG documents. This might be useful |
| if you want, for example, to override the font size used in text |
| elements. |
| </dd> |
| |
| <dt>Network panel</dt> |
| <dd> |
| <p> |
| This panel lets you configure the proxy server to use if you are |
| working from behind a firewall. |
| </p> |
| </dd> |
| </dl> |
| </section> |
| |
| <section id="zooming"> |
| <title>Navigating SVG documents: zooming, panning, rotating, transform and thumbnail</title> |
| |
| <p> |
| The Batik browser offers multiple way to navigate SVG documents: |
| </p> |
| <ul> |
| <li><a href="#zoomInOut">Zooming in and out</a></li> |
| <li><a href="#panning">Panning</a></li> |
| <li><a href="#rotating">Rotating</a></li> |
| <li><a href="#transform">Arbitrary transforms</a></li> |
| <li><a href="#thumbnail">Thumbnail</a></li> |
| </ul> |
| |
| <section id="zoomInOut"> |
| <title>Zooming in and out</title> |
| <p> |
| There are several methods to zoom in or out an SVG document: |
| </p> |
| <ul> |
| <li> |
| You can select the <strong>View→Zoom In</strong> or |
| <strong>View→Zoom Out</strong> menu item. |
| </li> |
| <li> |
| You can <strong>click</strong> on the <strong>Zoom In/Out</strong> |
| tool bar buttons (the ones that show a magnifying glass with |
| <strong>+/-</strong> signs). |
| </li> |
| <li> |
| You can use the <strong>Ctrl+I</strong> and <strong>Ctrl+O</strong> |
| keyboard accelerators. |
| </li> |
| <li> |
| If the mouse is over the document in the display area, you can press |
| the <strong>Ctrl key</strong> then <strong>click the left mouse |
| button and drag</strong> to select the area of interest in the |
| document. This can only be used to zoom into a document. |
| </li> |
| <li> |
| If the mouse is over the document in the display area, you can press |
| the <strong>Shift key</strong> then <strong>click the right mouse |
| button and drag</strong> it. This is called the <em>real time</em> |
| zoom and can be used both for zooming in and out. |
| </li> |
| </ul> |
| |
| <div class="figure"><img src="images/svgviewerZoomin.png" |
| alt="Screenshot of Squiggle showing the Zoom In and Zoom Out menu items and tool bar buttons"/> |
| </div> |
| <div class="figure"><img src="images/svgviewerAOI.png" |
| alt="Screenshot of Squiggle zooming to an area of interest"/> |
| </div> |
| </section> |
| |
| <anchor id="panning" /> |
| <section id="panning"> |
| <title>Panning a document</title> |
| <p> |
| Some documents are too big to fit into the browser, especially when |
| you <a href="#zoomInOut">zoom</a> in with a large zoom factor. In |
| these circumstances, it is useful to be able to move around the |
| document and pan to view different parts of the documents. Again, |
| there are multiple ways to do this: |
| </p> |
| |
| <ul> |
| <li> |
| With the mouse cursor over the SVG document, <strong>press the Shift |
| key</strong> and then <strong>click and drag the left mouse |
| button</strong> to a new location. When you release the mouse, the |
| document will be translated to the new mouse location. |
| </li> |
| <li> |
| If you have the <a href="#thumbnail">thumbnail</a> open, you can |
| select the marker showing the current area of interest and move it |
| to the desired location. |
| </li> |
| </ul> |
| <div class="figure"><img src="images/svgviewerPan.png" |
| alt="Screenshot of Squiggle illustrating the panning gesture"/> |
| </div> |
| </section> |
| |
| <section id="rotating"> |
| <title>Rotating a document</title> |
| <p> |
| It is sometimes useful to be able to rotate a document (maps for |
| example). You can do this in the Batik browser by first pressing the |
| <strong>Ctrl key</strong> and then <strong>clicking and dragging |
| the right mouse button</strong> to a new location. The browser will |
| dynamically rotate the image as you move your cursor. When you are |
| satisfied with that angle, you can release the mouse button and the |
| document will be displayed with that new angle. |
| </p> |
| </section> |
| |
| <section id="transform"> |
| <title>Using the Transform dialog</title> |
| <p> |
| While the mouse and keyboard interactions give interactive way to |
| navigate an SVG document, it is sometimes desirable to be able to |
| define precisely the amount of <a href="#zoomInOut">zoom</a>, |
| <a href="#panning">pan</a> or <a href="#rotating">rotation</a> |
| desired. The Transform dialog, available through the |
| <strong>View→Transform</strong> menu (<strong>Ctrl-E</strong>) |
| offers that feature. |
| </p> |
| </section> |
| |
| <section id="thumbnail"> |
| <title>Thumbnail</title> |
| <p> |
| Panning in the document window can be difficult after you have zoomed |
| into a document because you cannot see the whole document. Panning on |
| large documents (or with a large zoom factor) is made easy by the |
| thumbnail that you can bring up through the |
| <strong>View→Thumbnail</strong> menu item or |
| the <strong>Ctrl-Y</strong> keyboard accelerator. The thumbnail shows |
| a rectangular marker that represents the “Area of Interest”, i.e., |
| the region currently displayed in the window (the visible portion of |
| the document). You can <strong>drag out a rectangular marker with the |
| left mouse button pushed down</strong> to select a new area of |
| interest which will then be shown in the main window. |
| </p> |
| |
| <div class="figure"><img src="images/svgviewerThumbnail.png" |
| alt="Screenshot of Squiggle showing the Thumbnail window"/> |
| </div> |
| </section> |
| </section> |
| |
| </body> |
| </document> |