Xournal User's Manual
</h2>
<p style="font-size: 0.95em; text-align: center; color: rgb(0,0,0)">
- Version 0.2
+ Version 0.4.2.1
</p>
<hr />
<p>
</p>
<p>
Xournal can be downloaded at
+<a href="http://xournal.sourceforge.net/">http://xournal.sourceforge.net/</a> or
<a href="http://math.mit.edu/~auroux/software/xournal/">http://math.mit.edu/~auroux/software/xournal/</a>
</p>
<p>
<li> <a href="manual.html#tools">The drawing and selection tools</a> </li>
<li> <a href="manual.html#pages-layers">Pages, layers, and backgrounds</a> </li>
<li> <a href="manual.html#printing">Printing</a> </li>
+ <li> <a href="manual.html#configuration">Configuration</a> </li>
<li> <a href="manual.html#author">Author information, license, bug-reports</a> </li>
<li> <a href="manual.html#changelog">Version history</a> </li>
<li> <a href="manual.html#file-format">The file format</a> </li>
</p>
<h3 class="subsub"><img src="pixmaps/eraser.png"> The eraser</h3>
<p>
-The eraser lets you erase what you have drawn. If your tablet's stylus
-has an eraser tip, and if the XInput extensions are enabled, the eraser
-will be automatically selected when drawing with the eraser tip.
-Another possibility is to enable the "Emulate Eraser" option in the Options
-menu, which lets you use button 2 or 3 on the stylus (mouse middle or right button)
-as an eraser.<br />
+The eraser lets you erase what you have drawn.
+By default, stylus buttons 2 and 3 (mouse middle or right buttons) are
+mapped to the eraser tool.
+<br />
The eraser comes in three different thicknesses (selected using the
<a href="manual.html#thicknesses">thickness</a> toolbar buttons),
and can operate in three different modes (Eraser Options submenu of
is yellow) and thicknesses. Use the color and thickness toolbar buttons
to change these settings.
</p>
+<h3 class="subsub"><img src="pixmaps/text-tool.png"> The text tool</h3>
+<p>
+ To insert a new text item, click at the location where the text is to be
+ inserted on the page, then type it in or paste it using the contextual
+ menu (note: no wrapping is performed). To modify a text item, click inside
+ it. The font and point size can be modified using the "Text Font" command
+ in the Tools menu (or the toolbar button). The color is the same as that
+ currently selected for the pen (and can be modified using the toolbar
+ buttons).
+</p>
+<p>
+ Text items can contain arbitrary Unicode characters, provided that a
+ suitable font is installed on your system. However, languages written
+ in a direction other than left-to-right might not be handled properly.
+ If a journal contains some items in a font that is unavailable on your
+ system, another one will be substituted. (Also, text items will be
+ lost if the document is opened in a version of Xournal prior to 0.4).
+ Finally, note that the printing and PDF export features only accept
+ TrueType and Type 1 scalable fonts (do not use any bitmap fonts), and
+ that the typesetting of the text may be slightly different in the
+ printout.
+</p>
<h3 class="subsub"><img src="pixmaps/ruler.png"> The ruler</h3>
<p>
The ruler is not a tool by itself, but rather a special operating mode
line segments instead of curvy strokes. For simplicity, selecting the
ruler when not in pen or highlighter mode automatically selects the pen.
</p>
+<a name="recognizer"></a>
+<h3 class="subsub"><img src="pixmaps/shapes.png"> The shape recognizer</h3>
+<p>
+ The shape recognizer is also a special
+ operating mode of the pen and highlighter tools. When it is enabled,
+ Xournal attempts to recognize geometric shapes as they are drawn, and
+ if successful will replace the drawn strokes accordingly. The shapes
+ that can be recognized are: line segments, circles, rectangles, arrows,
+ triangles and quadrilaterals. Polygonal shapes can be drawn in a single
+ stroke or in a sequence of consecutive strokes.
+</p>
+<p>
+ The recognizer is set to be as unobtrusive as possible, and should not
+ interfere too much with handwriting. (It differs in this and other ways
+ from another shape recognizer written for Xournal by Lukasz Kaiser).
+ As a result, it may only recognize shapes if you draw them carefully and
+ deliberately. Specific tips for better recognition: (1) for circles,
+ a closed curve that isn't quite round works better
+ than a rounder curve that doesn't close; (2) for arrows, it is better
+ to lift the pen before drawing the tip of the arrow, and make sure
+ the tip consists of two straight line segments;
+ (3) for very elongated rectangles,
+ recognition tends to be better if you lift the pen between consecutive
+ sides.
+</p>
<h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
<p>
- Each drawing tool (pen, eraser, highlighter) has a default setting
- (color, thickness, ...) associated to it.
- The "Default Pen", "Default Eraser", and "Default Highlighter" entries of
+ Each tool (pen, eraser, highlighter, text) has a default setting
+ (color, thickness, ... for the drawing tools, font and size for the
+ text tool) associated to it.
+ The "Default Pen", "Default Eraser", "Default Highlighter", and
+ "Default Text" entries of
the Tools menu select the appropriate tool and reset its settings to
the defaults. The toolbar also includes a "Default" button which
- resets the currently selected drawing tool to its default settings,
+ resets the currently selected tool to its default settings,
and a "Default Pen" button. <br />
The "Set As Default" entry of the Tools menu takes the current settings
- of the currently selected drawing tool and makes them the new default.
+ of the currently selected tool and makes them the new default.
</p>
<a name="thicknesses"></a>
<h3 class="subsub"><img src="pixmaps/thin.png"> <img src="pixmaps/medium.png">
All the strokes which are entirely contained within the rectangular region
are selected.
The selection can be moved within its page by clicking inside the
- selection rectangle and dragging the cursor.
+ selection rectangle and dragging the cursor. If the cursor is dragged
+ to a different page, the selection will be moved to the topmost layer of
+ that page.
</p>
<p>
The selection can be cut, duplicated, etc. (including to a different page
space, or change the page height to an appropriate value (using the
"Paper Size" entry in the Journal menu).
</p>
+<p>
+ If you drag the cursor below the bottom of the page (so that the
+ entire block being moved has become invisible), the items will be moved
+ to the next page (topmost layer); however, any items that were already
+ present on the next page are left unchanged. Similarly, dragging the
+ cursor above the top of the page so that the entire block being moved
+ becomes invisible results in the items being moved to the previous page.
+</p>
+<h3 class="subsub"><img src="pixmaps/hand.png"> Hand tool</h3>
+<p>
+ This tool lets you browse the journal; dragging the cursor scrolls the
+ view.
+</p>
<h3 class="subsub">Undo and redo</h3>
<p>
All operations performed on the currently open journal (drawing, erasing,
the corresponding entries in the Edit menu.<br />
There is no limit to the depth of the undo/redo stack. It is cleared only
when you quit the application or open a new journal.
+</p>
+<a name="mappings"></a>
+<h3 class="subsub">Button mappings</h3>
+<p>
+ Stylus buttons 2 and 3 (mouse middle and right buttons) can be mapped
+ to different tools using the appropriate submenus in the Options menu
+ (whereas the Tools menu and the toolbar buttons affect the primary tool
+ assigned to button 1). The default mapping is the eraser.
+</p>
+<p><b>Advanced configuration:</b>
+ if a secondary button is mapped to a drawing tool (pen, eraser, or
+ highlighter), the default is to "dynamically link" its settings to those
+ of the primary tool, which means that each drawing tool has common
+ settings (color, thickness, etc.) for all buttons.
+ Dynamic linking of brush settings
+ can be disabled by selecting the "Copy of current brush" option in the
+ "Button mapping" submenu. The settings of the tool for button 2 or 3 are
+ copied from the button 1 settings at the time when you select the option,
+ and afterwards they are no longer updated when the button 1 settings are
+ modified, thus making it possible to assign pens of different colors or
+ thicknesses to different buttons.
+</p>
+<p>
+ Another option that affects button mappings is the "Eraser tip" option.
+ If this option is turned on and the XInput extensions are enabled, then
+ the eraser tip of your tablet's stylus will automatically be remapped to
+ the eraser tool. This behavior, which overrides all other button mappings,
+ is most useful if your X server is configured to map the eraser tip of
+ your tablet's stylus to button 1.
+</p>
<hr />
<a name="pages-layers"></a>
<h2 class="subtitle">Pages, layers, and backgrounds</h2>
<h2 class="subtitle">Printing</h2>
<p>
Xournal uses the gnome-print architecture for printing. While it is very
-powerful, some aspects of the API leave to be desired,
-and future versions of Xournal will probably also include a native
-Postscript/PDF printing feature.
+powerful, some aspects of the API leave to be desired. As of version 0.3,
+Xournal also includes a native PDF printing feature.
</p>
+<h3 class="subsub">Printing via gnome-print</h3>
<p>
The "Printer" tab of the print dialog box lets you select a printer
(either one of the printers installed on your system, or the generic
this often fails due to gnome-print API issues).
</p>
<p>
-The "Print to PDF" entry of the File menu directly generates a PDF file
-using the PDF virtual printer, without bringing up the dialog box
-(the page size is the default one for that printer, usually A4).
Note that the PDF virtual printer produces files that are very large
-and far from optimal, so in the current state of things it is better
-to generate a Postscript file and use a converter such as ps2pdf.
-</p>
-<p>
+and far from optimal, so its use is not recommended.
The gnome-print architecture also forces page backgrounds (bitmaps
and PDF) to be generated as uncompressed bitmaps, which leads to gigantic
-print job files. An alternative to gnome-print will be
-implemented in a future release of Xournal.
+print job files. A better alternative is to export a PDF file, and
+print the PDF file.
+</p>
+<h3 class="subsub">Exporting to PDF</h3>
+<p>
+Starting with version 0.3, Xournal provides its own PDF rendering
+engine. The "Export to PDF" command (in the File menu) produces a
+PDF-1.4 file from the currently loaded document. The resulting PDF
+file is much more compact than those produced via gnome-print, and
+its pages have the same size as in Xournal. Highlighter strokes
+are rendered in a partially transparent manner (note however that
+applications such as xpdf and ghostview do not always handle
+PDF transparency properly). Text items are rendered by embedding
+TrueType subsets or Type 1 fonts into the PDF document as appropriate.
+</p>
+<p>
+Xournal also includes a PDF file parser compatible with PDF format
+version 1.4; the compression features of PDF 1.5 (Acrobat 6) are
+not supported. When exporting a document that uses PDF
+backgrounds, Xournal attempts to preserve most of the structure of
+the original PDF file (however, auxiliary data such as thumbnails, hyperlinks,
+and annotations are lost). If Xournal is unable to parse the PDF
+file, the backgrounds are converted to (compressed) bitmaps and a new
+PDF file is generated from scratch.
+</p>
+<hr />
+<a name="configuration"></a>
+<h2 class="subtitle">Configuration</h2>
+<p>
+Starting with version 0.3.2, Xournal's configuration settings can be
+saved to a file (<tt>~user/.xournal/config</tt>) by using the "Save
+Preferences" command in the Options menu. The settings saved in the
+configuration file include in particular:
+<ul>
+<li>general display preferences: zoom level, window size, ...</li>
+<li>default paper settings (as set by the "Set As Default" command in
+the Journal menu)</li>
+<li>default settings for the pen, eraser, highlighter, and text tools
+(as set by the "Set As Default" command in the Tools menu)</li>
+<li>mappings for buttons 2 and 3</li>
+<li>the various preferences set in the Options menu</li>
+</ul>
+The configuration file also gives access to additional customization
+options which cannot be set from the user interface, such as: the
+display resolution in pixels per inch, the step increment in zoom factors,
+the tool selected at startup, the thickness of the various drawing tools,
+the default directory for opening and saving files, the visibility and
+position of the menu and toolbars, ...
+</p>
<hr />
<a name="author"></a>
<h2 class="subtitle">Author information, license, bug-reports</h2>
</p>
<p>Feel free to contact me with bug reports and suggestions; I apologize
in advance if I am unable to respond properly to some requests.
-List of known bugs/misfeatures (no need to report them again):
-<ul>
- <li> highlighter strokes become opaque on printouts (apparently a bug in
- libgnomeprint).</li>
- <li> print settings are not saved from one print command to the next.</li>
- <li> printing to PDF and/or printing page backgrounds generates large files.</li>
- <li> preferences are not saved on disk.</li>
- <li> selection cannot be dragged across page boundaries.</li>
-</ul>
+</p><p>
If you find a sequence of operations which crashes Xournal in a reproducible
manner, please send detailed instructions on how to reproduce the crash.
A core file may also be helpful.
</p>
+<p>
+Bug reports and suggestions can also be submitted on Xournal's
+<a href="http://www.sourceforge.net/projects/xournal/">SourceForge page.</a>
+</p>
<hr />
<a name="changelog"></a>
<h2 class="subtitle">Version history</h2>
<p>
+Version 0.4.2.1 (Mar 27, 2008):
+<ul>
+ <li>bugfix for #1926757 (crash upon pasting variable-width stroke)</li>
+ <li>bugfix: set ruler/recognizer setting to default upon switching tools</li>
+</ul>
+</p>
+<p>
+Version 0.4.2 (Mar 25, 2008):
+<ul>
+ <li>bugfixes for X.org 7.3; allow XInput and core events in reverse order</li>
+ <li>resize selection (patch contributed by Andy Neitzke)</li>
+ <li>pressure sensitive pen (variable stroke width) (patch by Andy Neitzke)</li>
+ <li>geometric shape recognizer (after an idea by Lukasz Kaiser)
+ (see <a href="manual.html#recognizer">here</a>)</li>
+ <li>clean up compiler warnings (patch contributed by Danny Kukawka)</li>
+</ul>
+</p>
+<p>
+Version 0.4.1 (Sep 15, 2007):
+<ul>
+ <li> bugfix: compatibility with new versions of pdftoppm (thanks to
+ Vincenzo Ciancia)</li>
+ <li>GTK+ 2.11 event processing bugfix</li>
+ <li>minor bugfixes: hand tool, handling of filenames containing '&'</li>
+ <li>desktop and MIME files (thanks to Mathieu Bouchard) + updated installer</li>
+ <li>config options: left-handed scrollbar (contributed by Uwe Winter),
+ hide some menu items (customizable in config file), auto-save
+ preferences</li>
+</ul>
+</p>
+<p>
+Version 0.4.0.1 (September 3, 2007):
+<ul>
+ <li>bugfixes for GTK+ 2.11 behavior (thanks to everyone who reported bugs)</li>
+</ul>
+</p>
+<p>
+Version 0.4 (August 15, 2007):
+<ul>
+ <li>text tool (handles most TrueType and Type1 fonts)</li>
+ <li>font selection dialog and button</li>
+ <li>keyboard mappings (arrow keys)</li>
+ <li>menu mnemonics and shortcuts (suggestions by Jean-Baptiste Rouquier)</li>
+ <li>more responsive hand tool</li>
+ <li>bugfix for GTK+ 2.11 XInput behavior (thanks to Robert Gerlach)</li>
+ <li>various minor bugfixes and enhancements</li>
+</ul>
+</p>
+<p>
+Version 0.3.3 (January 31, 2007):
+<ul>
+ <li>bugfix: upon loading a new file, zoom is set to default startup zoom</li>
+ <li>config option to allow input from a mouse or other core pointer device</li>
+ <li>config file entry to specify a default location for open/save
+ (patch contributed by Andy Neitzke)</li>
+ <li>config file entries to customize visibility and position of toolbars</li>
+ <li>icon (thanks to Michele Codutti)</li>
+</ul>
+</p>
+<p>
+Version 0.3.2 (November 25, 2006):
+<ul>
+ <li>preferences file and Save Preferences command</li>
+ <li>extra customization (via preferences file)</li>
+ <li>minor UI changes (patch contributed by Eduardo de Barros Lima)</li>
+ <li>hand tool (partially contributed by Vincenzo Ciancia)</li>
+ <li>a few bugfixes in rendering of bitmap backgrounds</li>
+</ul>
+<p>
+Version 0.3.1 (August 3, 2006):
+<ul>
+ <li>fixed a file format bug on systems with non-standard numeric locale
+ (bug reported by Gert Renckens)</li>
+</ul>
+</p>
+<p>
+Version 0.3 (July 23, 2006):
+<ul>
+ <li>new PDF rendering engine: export to PDF generates optimized files
+ (smaller and more accurate)</li>
+ <li>export to PDF handles PDF backgrounds (up to PDF-1.4) natively
+ (without conversion to bitmap)</li>
+ <li>default thickness of erasers and highlighters slightly increased</li>
+ <li>zoom dialog box with input box and "fit to page height" option</li>
+ <li>file format documentation added to the user's manual</li>
+</ul>
+</p>
+<p>
+Version 0.2.2 (June 5, 2006):
+<ul>
+ <li>mapping of tools to stylus buttons (the options menu has new entries
+ to allow the mapping of buttons 2 and 3 to arbitrary tools; the tools
+ menu and toolbar affect the settings for button 1)
+ (see <a href="manual.html#mappings">here</a>)</li>
+ <li>moving selection by drag-and-drop works across page boundaries</li>
+ <li>vertical space tool can move items to next page (only when the entire
+ block being moved has crossed the page boundary; items on the new page
+ are not moved)</li>
+ <li>"apply to all pages" is now a toggle button affecting the behavior of
+ paper size, color, and style commands</li>
+ <li>change in the behavior of the selection upon switching between tools</li>
+</ul>
+</p>
+<p>
+Version 0.2.1 (June 3, 2006):
+<ul>
+ <li>recently used files listed in file menu</li>
+ <li>can change color or thickness of pen strokes in selection</li>
+ <li>function to apply paper style to all pages</li>
+ <li>can specify on command line a PDF file to annotate</li>
+ <li>suggest a derived file name for PDF annotation</li>
+ <li>speed up switching between pages</li>
+ <li>fixed a bug in XInput initialization (thanks to Luca de Cicco)</li>
+ <li>fixed a bug in print ranges (thanks to Mathieu Bouchard)</li>
+ <li>fixed a refresh bug in rescaling bitmap backgrounds</li>
+</ul>
+</p>
+<p>
Version 0.2 (January 29, 2006):
<ul>
<li>PDF file annotation using xpdf's pdftoppm
<p>
Version 0.1 (January 2, 2006): initial release.
</p>
+<hr />
+<a name="file-format"></a>
+<h2 class="subtitle">The file format</h2>
+<h3 class="subsub">Overall structure</h3>
+<p>
+Xournal stores its data in gzipped XML-like files. The gzipped data consists
+of a succession of XML tags describing the document. By convention, the
+file header and trailer look like this:
+<pre>
+<?xml version="1.0" standalone="no"?>
+<xournal version="...">
+<title>Xournal document - see http://math.mit.edu/~auroux/software/xournal/</title>
+... sequence of pages ...
+</xournal>
+</pre>
+The <title> and <xournal> tags may only appear within the file
+header (not within the pages of the document). The <i>version</i> attribute of
+the <xournal> tag indicates which version of Xournal was used to
+create the document; it is currently ignored, but may be used in a later
+release if the file format changes in an incompatible manner.
+(Following a suggestion of Matteo Abrate, starting with version 0.4 the
+<xournal> tag is the document's root tag, and encloses all other tags).
+</p>
+<p>
+The rest of the file is a sequence of pages, specified by a
+<page> tag, whose attributes <i>width</i> and <i>height</i> specify the
+physical size of the page in points (1/72 in). The width and height
+parameters are floating point values. The format of a page is therefore:
+<pre>
+<page width="..." height="...">
+... page contents ...
+</page>
+</pre>
+</p>
+<h3 class="subsub">Page background</h3>
<p>
-Features yet to be implemented:
+The first entry within a page describes the page background.
+It consists of a <background> tag followed by several mandatory
+XML attributes. The first attribute is always <i>type</i>, which
+can take three possible values: "solid" for a solid background, "pixmap"
+for a bitmap background, and "pdf" if the background is a page of a PDF
+document. The rest of the attributes depends on the type of background.
<ul>
- <li>freeform selection tool</li>
- <li>preferences file; persistent printer settings; recent files list</li>
- <li>native PDF print feature</li>
- <li>various functionalities (flatten layers, drag-and-drop across pages, ...)</li>
+<li><p> Solid background: <tt><background type="solid" color="..."
+style="..." /></tt> <br />The <i>color</i> attribute takes one of
+the standard values "white", "yellow", "pink", "orange", "blue", "green",
+or can specify a hexadecimal RGBA value in the format "#rrggbbaa". The
+<i>style</i> attribute takes one of the standard values "plain", "lined",
+"ruled", or "graph".</p>
+</li>
+<li><p> Bitmap background: <tt><background type="pixmap" domain="..."
+filename="..." /></tt> <br />
+The <i>domain</i> attribute takes one of the standard values "absolute",
+"attach", or "clone". A value of "absolute" indicates that the bitmap is
+found in the file specified by <i>filename</i>. The bitmap can be in any
+format recognized by the gdk-pixbuf library; this includes most of the
+common bitmap formats (JPEG, PNG, BMP, GIF, PCX, PNM, TIFF, ...).
+<br />A value
+of "attach" indicates that the bitmap is an attachment to the Xournal file.
+The bitmap is in PNG format, and resides in a file whose name is derived
+from that of the main Xournal file by appending to it a dot and the contents
+of the <i>filename</i> attribute. For example, if the Xournal file is in
+<tt>file.xoj</tt> and the <i>filename</i> attribute is <tt>"bg_1.png"</tt>
+then the bitmap file is <tt>file.xoj.bg_1.png</tt> (Xournal saves attached
+bitmaps sequentially in files ...bg_1.png, ...bg_2.png, etc.)
+<br />A value of "clone" indicates that the bitmap is identical to the
+background of a previous page of the journal; the <i>filename</i> attribute
+then specifies the page number, starting with 0 for the first page. For
+example, if a <i>filename</i> value of <tt>"1"</tt> indicates that the
+background bitmap is identical to that of the second page.
+</p>
+</li>
+<li><p> PDF background: <tt><background type="pdf" domain="..."
+filename="..." pageno="..." /></tt> or
+<tt><background type="pdf" pageno="..." /></tt>
+<br />The <i>domain</i> and <i>filename</i> attributes must be specified
+for the first page of the journal that uses a PDF background, and must
+be omitted subsequently for every other page that uses a PDF background.
+The <i>domain</i> attribute takes one of the standard values
+"absolute" and "attach"; the PDF document is to be found in the file
+specified by <i>filename</i> (if <i>domain</i> is "absolute"), or in the
+file whose name is obtained by appending a dot and the contents of the
+<i>filename</i> attribute to the name of the main Xournal file (if
+<i>domain</i> is "attach"). The <i>pageno</i> attribute specifies which
+page of the PDF file is used as background, starting with 1 for the first
+page of the PDF file.
+</p>
+</li>
</ul>
</p>
-<hr />
-<a name="file-format"></a>
-<h2 class="subtitle">The file format</h2>
+<h3 class="subsub">Layers and strokes</h3>
<p>
-XOJ files are gzipped XML-like files. A more precise documentation of
-the file format will be added at a later date. Meanwhile, most of the
-format should be easy to figure out by trial-and-error or by looking
-at the source; if some details are unclear, feel free to ask.
+After the line specifying the background, the remainder of a <page>
+section is occupied by one or more layer sections
+<pre><layer> ... </layer></pre>
+describing the various items within a layer. Every page must
+contain at least one layer; a layer may be empty. The successive layers
+are listed in their stacking order, from bottom to top.
+</p>
+<p>
+A layer consists of a collection of items, listed in the order in which
+they should be drawn
+(from bottom-most to top-most).
+Up to version 0.3.3, the only legal contents within a layer are
+strokes. The format of a stroke is:
+<pre><stroke tool="..." color="..." width="...">
+... list of coordinates ...
+</stroke>
+</pre>
+The <i>tool</i> attribute can take the values "pen", "highlighter", or
+"eraser" depending on the tool used to create the stroke (pen, highlighter,
+or whiteout eraser); a value of "highlighter" indicates that the stroke
+should be painted in a partially transparent manner (Xournal uses an alpha
+coefficient of 0.5).
+</p>
+<p>
+The <i>color</i> attribute can take one of the standard values "black",
+"blue", "red", "green", "gray", "lightblue", "lightgreen", "magenta",
+"orange", "yellow", "white", or can specify a hexadecimal RGBA value in
+the format "#rrggbbaa".
+</p>
+<p>
+The <i>width</i> attribute is a floating-point
+number (or a sequence of floating-point numbers starting with version 0.4.2),
+and specifies the width of the stroke in points (1/72 in). (For a
+variable-width stroke, the <i>width</i> attribute contains a
+whitespace-separated succession of floating-point values: first the
+nominal brush width, and then the width of each successive segment forming
+the stroke.)
+</p>
+<p>
+The list of coordinates is simply a succession of floating-point values,
+separated by whitespace.
+The number of given values must be even; consecutive pairs of values give
+the <i>x</i> and <i>y</i> coordinates of each point along the stroke.
+These values are expressed in points (1/72 in). The coordinates (0,0)
+represent the top-left corner of the page: hence x is measured from the left
+of the page, and y is measured from the top of the page.
+</p>
+<p>
+Every stroke must contain at least two points (four floating point values).
+Moreover, two consecutive points on the stroke should be spaced no more
+than 5 units apart or so; longer line segments should be subdivided as
+appropriate (otherwise the eraser tool will not interact properly with the
+stroke). The default precision used by Xournal for the x,y coordinates is
+0.01 unit (1/7200 in).
+</p>
+<p>Starting with version 0.4, layers also contain text items.
+The format of a text item is:
+<pre><text font="..." size="..." x="..." y="..." color="...">... text ...</text>
+</pre>
+The <i>font</i> attribute contains the font name, for example "Serif Bold
+Italic"; if the font is not available, another font will be substituted.
+The <i>size</i> attribute specifies the font size in points. The <i>x</i>
+and <i>y</i> attributes specify the coordinates of the top-left corner
+of the text box in page coordinates (measured in points from the top-left
+corner of the page). Finally, the <i>color</i> attribute contains either
+the name of a standard color or a hexadecimal RGBA value (see above).
+</p>
+<p>
+The contents of the text are encoded in UTF-8, with the characters
+<tt>'&', '<', '>'</tt> replaced by <tt>&amp;, &lt;,
+&gt;</tt>. Whitespace and linefeeds are preserved (in particular,
+no extraneous whitespace should be inserted between the enclosing tags
+and the text itself).
</p>
<hr />
<a name="installation"></a>
later):
<ul>
<li> the <b>gtk+</b> libraries, version <b>2.4</b> or later
- (2.6 recommended) (package gtk2 and dependencies)</li>
+ (<b>2.6</b> strongly recommended) (package gtk2 and dependencies)</li>
<li> <b>libgnomecanvas</b> version <b>2.4</b> or later
(package libgnomecanvas and dependencies)</li>
<li> <b>libgnomeprint</b> and <b>libgnomeprintui</b> version <b>2.2</b> or later
./autogen.sh
make
(as root) make install
+(as root) make desktop-install
</pre>
</p>
<p>
./configure --prefix=$HOME
make
make install
+make home-desktop-install
</pre>
</p>
<p><b>Configure error message:</b> <br />
use USB instead; the BottomX and BottomY values correspond to the physical
resolution of the tablet and will vary from one model to another.
</p>
+<p>
+For historical reasons, most X servers do not allow the input device
+designated as the "core pointer" in the X server's configuration file
+to be used as an XInput extension device. Thus, your tablet input devices
+should <b>not</b> be designated as the core pointer device. Instead, they
+should be configured with the "SendCoreEvents" option, which enables them
+to simultaneously generate XInput extension events and move the cursor on
+the screen. Since high-resolution coordinates cannot be obtained for the
+core pointer device, it is disabled in Xournal by default.
+Starting with version 0.3.3,
+it is possible to have core events processed alongside with extension
+events (uncheck "Discard Core Events" in the Options menu); however, in
+some rare cases this may lead to a loss of resolution on all devices.
+</p>
<h3 class="subsub">The cursor doesn't appear in the right place...</h3>
<p>
If the mouse pointer does not follow accurately the position of the stylus,
properly when using xsetwacom).
</p>
<p>
-<b>Important:</b> due to issues with the linuxwacom driver, it is important
-to either upgrade your driver to a <a href="manual.html#wacompatch">patched
-version</a>, or restrict your choice of settings as follows:
+<b>Important:</b> due to issues with old versions of the linuxwacom
+driver (< 0.7.6), it is important to upgrade your driver,
+or restrict your choice of settings as follows:
<ul>
<li> your calibration settings should not be changed at runtime (i.e.,
insert your settings directly into your X server configuration file.
</p>
<h3 class="subsub">Strokes aren't drawn under the cursor...</h3>
<p>
-This is due to misfeatures in the linuxwacom driver. Typically, this
-will happen in all of the following cases:
+This is typically due to misfeatures in the linuxwacom driver in versions
+prior to 0.7.6, and will happen in all of the following cases:
<ul>
<li> the calibration settings have been changed after the X server was
started (using xsetwacom) </li>
<li> the calibration TopX or TopY values are not 0 </li>
<li> the display has been rotated </li>
</ul>
-Future versions of the driver may fix these issues. Meanwhile, you can
+Most of these issues should have been fixed in version 0.7.6 of the
+wacom driver. Otherwise, you can
either disable XInput support in Xournal (in the Options menu), at a
price of a severe loss of resolution (and the eraser tip won't be detected
-anymore), or apply this <a href="manual.html#wacompatch">patch</a>
-to the wacom driver.
+anymore), or inspect carefully your X server configuration and make
+sure the tablet devices are calibrated and configured properly.
</p>
<p>
I have also had a report that one of the workarounds used by Xournal to
bypass a calibration bug in GTK+ can actually entirely prevent strokes
from being drawn. If you are being unsuccessful at drawing in Xournal
-with XInput enabled, try recompiling after changing the first line of
-<tt>src/main.c</tt> to
-<pre>#define ENABLE_XINPUT_BUGFIX 0</pre>
+with XInput enabled, try recompiling after commenting out the line
+<pre>#define ENABLE_XINPUT_BUGFIX</pre>
+near the beginning of <tt>src/xournal.h</tt>.
If this modification does improve things for you, and if you have a bit
of spare time to help investigate the causes of this problem, please
contact me.
</p>
<h3 class="subsub">On-the-fly display rotation</h3>
<p>
-You need an X server that supports the RANDR extension, and a
-<a href="manual.html#wacompatch">patched</a> version of the linuxwacom
-driver to support on-the-fly rotation.
+You need an X server that supports the RANDR extension, and a sufficiently
+recent (0.7.6 or later)
+version of the linuxwacom driver to support on-the-fly rotation.
</p>
<p>
To set the tablet in portrait mode:
become incorrect.
Exit Xournal and restart it after the display has been rotated.
</p>
-<a name="wacompatch"></a>
-<h3 class="subsub">Linuxwacom patch for calibration and rotation</h3>
-<p>
-This patch fixes rotation and calibration issues with the linuxwacom driver
-version 0.7.0.
-<ul>
-<li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-0.7.0-rotate-patch">patch
-file</a> for the linuxwacom source code (also included with the Xournal
-distribution).</li>
-<li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-rotate-patch.tar.gz">patched
-binaries</a> for the X.org X server.</li>
-</ul>
-</p>
</body>
</html>
projects / xournal.git / blobdiff