The eraser- Version 0.2 + Version 0.4.2
@@ -38,14 +38,14 @@
Xournal can be downloaded at +http://xournal.sourceforge.net/ or http://math.mit.edu/~auroux/software/xournal/
Xournal aims to provide superior graphical quality (subpixel resolution) and overall functionality; however it lacks the collaborative features of Jarnal. Since Xournal is still in its early development stages, it may not - be fully stable, and some features have not been implemented yet - (in particular, freeform selection and PDF backgrounds are missing). + be fully stable, and some features have not been implemented yet.
@@ -54,6 +54,7 @@ Xournal can be downloaded at
The eraser
-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.
+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.
+
The eraser comes in three different thicknesses (selected using the
thickness toolbar buttons),
and can operate in three different modes (Eraser Options submenu of
@@ -128,6 +127,28 @@ the Tools menu):
is yellow) and thicknesses. Use the color and thickness toolbar buttons
to change these settings.
The text tool+ 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). +
++ 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. +
The rulerThe ruler is not a tool by itself, but rather a special operating mode @@ -135,17 +156,44 @@ the Tools menu): line segments instead of curvy strokes. For simplicity, selecting the ruler when not in pen or highlighter mode automatically selects the pen.
+ +
The shape recognizer+ 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. +
++ 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. +
Default tools
- 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.
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.
@@ -161,7 +209,9 @@ the Tools menu):
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.
The selection can be cut, duplicated, etc. (including to a different page @@ -183,6 +233,19 @@ the Tools menu): space, or change the page height to an appropriate value (using the "Paper Size" entry in the Journal menu).
++ 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. +
+
Hand tool+ This tool lets you browse the journal; dragging the cursor scrolls the + view. +
All operations performed on the currently open journal (drawing, erasing,
@@ -191,6 +254,36 @@ the Tools menu):
the corresponding entries in the Edit menu.
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.
+
+ 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. +
+Advanced configuration: + 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. +
++ 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. +
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.
+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 @@ -411,18 +504,59 @@ attempts to pre-fill the output file name (for the Postscript driver this often fails due to gnome-print API issues).
-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. -
-+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. +
++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. +
++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. +
++Starting with version 0.3.2, Xournal's configuration settings can be +saved to a file (~user/.xournal/config) by using the "Save +Preferences" command in the Options menu. The settings saved in the +configuration file include in particular: +
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): -
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.
++Bug reports and suggestions can also be submitted on Xournal's +SourceForge page. +
+Version 0.4.2 (Mar 25, 2008): +
+Version 0.4.1 (Sep 15, 2007): +
+Version 0.4.0.1 (September 3, 2007): +
+Version 0.4 (August 15, 2007): +
+Version 0.3.3 (January 31, 2007): +
+Version 0.3.2 (November 25, 2006): +
+Version 0.3.1 (August 3, 2006): +
+Version 0.3 (July 23, 2006): +
+Version 0.2.2 (June 5, 2006): +
+Version 0.2.1 (June 3, 2006): +
Version 0.2 (January 29, 2006):
@@ -471,23 +712,171 @@ Version 0.1.1 (January 5, 2006):
Version 0.1 (January 2, 2006): initial release.
++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: +
+<?xml version="1.0" standalone="no"?> +<xournal version="..."> +<title>Xournal document - see http://math.mit.edu/~auroux/software/xournal/</title> +... sequence of pages ... +</xournal> ++The <title> and <xournal> tags may only appear within the file +header (not within the pages of the document). The version 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). + +
+The rest of the file is a sequence of pages, specified by a +<page> tag, whose attributes width and height 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: +
+<page width="..." height="..."> +... page contents ... +</page> ++ +
-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 type, 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.
Solid background: <background type="solid" color="..."
+style="..." />
The color 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
+style attribute takes one of the standard values "plain", "lined",
+"ruled", or "graph".
Bitmap background: <background type="pixmap" domain="..."
+filename="..." />
+The domain 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 filename. 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, ...).
+
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 filename attribute. For example, if the Xournal file is in
+file.xoj and the filename attribute is "bg_1.png"
+then the bitmap file is file.xoj.bg_1.png (Xournal saves attached
+bitmaps sequentially in files ...bg_1.png, ...bg_2.png, etc.)
+
A value of "clone" indicates that the bitmap is identical to the
+background of a previous page of the journal; the filename attribute
+then specifies the page number, starting with 0 for the first page. For
+example, if a filename value of "1" indicates that the
+background bitmap is identical to that of the second page.
+
PDF background: <background type="pdf" domain="..."
+filename="..." pageno="..." /> or
+<background type="pdf" pageno="..." />
+
The domain and filename 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 domain attribute takes one of the standard values
+"absolute" and "attach"; the PDF document is to be found in the file
+specified by filename (if domain is "absolute"), or in the
+file whose name is obtained by appending a dot and the contents of the
+filename attribute to the name of the main Xournal file (if
+domain is "attach"). The pageno attribute specifies which
+page of the PDF file is used as background, starting with 1 for the first
+page of the PDF file.
+
-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 +
<layer> ... </layer>+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. + +
+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: +
<stroke tool="..." color="..." width="..."> +... list of coordinates ... +</stroke> ++The tool 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). + +
+The color 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". +
++The width 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 width 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.) +
++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 x and y 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. +
++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). +
+Starting with version 0.4, layers also contain text items. +The format of a text item is: +
<text font="..." size="..." x="..." y="..." color="...">... text ...</text> ++The font attribute contains the font name, for example "Serif Bold +Italic"; if the font is not available, another font will be substituted. +The size attribute specifies the font size in points. The x +and y 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 color attribute contains either +the name of a standard color or a hexadecimal RGBA value (see above). + +
+The contents of the text are encoded in UTF-8, with the characters +'&', '<', '>' replaced by &, <, +>. Whitespace and linefeeds are preserved (in particular, +no extraneous whitespace should be inserted between the enclosing tags +and the text itself).
@@ -550,6 +940,7 @@ make ./configure --prefix=$HOME make make install +make home-desktop-install
Configure error message:
@@ -632,6 +1023,20 @@ installation instructions specific to your model: for example, the
use USB instead; the BottomX and BottomY values correspond to the physical
resolution of the tablet and will vary from one model to another.
+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 not 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. +
If the mouse pointer does not follow accurately the position of the stylus, @@ -657,9 +1062,9 @@ linuxwacom driver, the tablet calibration information is often not updated properly when using xsetwacom).
-Important: due to issues with the linuxwacom driver, it is important -to either upgrade your driver to a patched -version, or restrict your choice of settings as follows: +Important: 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:
-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:
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 -src/main.c to -
#define ENABLE_XINPUT_BUGFIX 0+with XInput enabled, try recompiling after commenting out the line +
#define ENABLE_XINPUT_BUGFIX+near the beginning of src/xournal.h. 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.
-You need an X server that supports the RANDR extension, and a -patched 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.
To set the tablet in portrait mode: @@ -718,18 +1124,5 @@ otherwise the tablet calibration in Xournal may (and most likely will) become incorrect. Exit Xournal and restart it after the display has been rotated.
- --This patch fixes rotation and calibration issues with the linuxwacom driver -version 0.7.0. -