User Manual
Note: this manual will eventually be replaced by the guide on the new website.
This manual is a draft and a work in progress. If you have the time you can help write some paragraphs ;-)
Xournal++ is a notetaking and PDF annotation tool that is based on Xournal but written from scratch in C++, using GTK3 instead of GTK2. It supports pressure sensitive pens (e.g. Wacom), text input, image input, LaTeX formula entry as well as a number of other useful features such as shape recognition and layers.
Feel free to report any bugs you encounter or make feature requests on our Issue Tracker. You're also welcome to submit pull requests.
Although Xournal++ is designed to be intuitive and simple to use, we realize that setting it up and getting used to all of the options is non-trivial. Here, we'll briefly outline how Xournal++ is used and how it should be set up. If you're a first time user, we strongly recommend that you read this section in its entirely before using Xournal++.
A typical Xournal++ workflow looks like the following:
- Use the
Filemenu to load an existing Xournal++ project, create a new document, or load a PDF file. - Annotate or markup the document using one of the tools in the toolbar, such as the Stroke tool, the Text tool, or the Image tool.
- Save periodically.
- If needed, export the document as a PDF file by selecting
File > Export as PDFin the menu. You can also export in more formats or export custom page ranges usingFile > Save As....
Once you are ready to begin editing a document, you can draw strokes and add objects using some of the tools described below.
If you need more space, you can add more pages using one of the Journal > ... options or by right clicking a page in the Page Panel (in the default layout, it is on the left side of the program).
If you edit and annotate a PDF document you may want to combine the keyboard and a Wacom tablet. In this case
- (Cursor) use the cursor keys (up, down) for moving up and down in the document and
- (Stylus/Wacom) use the Wacom tablet with the stylus to annotate the PDF document. Of course you can scroll with the stylus but sometimes you forget to return the focus from the scrollbar back to the document and then the movement of the stylus move the document instead of annotating the document at the Wacom tablet (helpful e.g. on Operating System MacOSX with Xounral++ - Version 1.0.18).
Xournal++ is highly customizable and has many configurable settings, as it is designed to work on a variety of devices. You can edit the settings by selecting Edit > Preferences from the menu.
For example:
- You can try enabling the optional "Experimental Input System" (in the
Input Systemtab), which fixes many input-related issues and is a better experience overall. - You can customize mouse/stylus/touchscreen controls.
- You can edit how Xournal++'s interface is organized in the
Viewtab. - You can adjust zoom and layout settings.
One of the most important settings that you should tweak are the input settings. The options you choose are going to depend on the exact devices that you are using as well as your habits and workflow.
In the Input System tab, you should check that your devices are properly detected by Xournal++. If you have the new input system enabled (we strongly recommend that you enable this setting), you will have the capability to assign different devices classes to your detected input devices. For example, if you have a graphical tablet, ensure that your stylus is set to a Pen device, not Disabled or Mouses. Otherwise, your stylus may not work or its pressure sensitivity may be disabled.
If the button settings for your stylus are not working, you may want to enabled Merge button events with stylus tip events.
In the Mouse and Stylus tabs, you can set which tools should be assigned to your button presses. For example, you may want to set the middle mouse button for the mouse to activate the hand tool, or you may want to set one of the stylus buttons to activate the eraser. When a secondary button is pressed, the activate tool will temporarily change to the selected tool until the secondary button is released.
If you have a computer with a touchscreen, you will want to check out the options in the Touchscreen tab so that Xournal++ behaves in a way that you expect.
There is a "Touch Workaround" option in the Touchscreen tab. By default, Xournal++ will treat touches as scrolling. If you would instead like to use the touchscreen for drawing, you should enable the "Touch Workaround". (Note: in a future version of Xournal++, the "Touch Workaround" will be renamed to "Touch Drawing", as the current "Touch Workaround" has some serious bugs).
By default, the cursor for the stylus is a 1-pixel wide dot. If you would like to see a bigger cursor, you can enable the Big cursor for pen option in the View tab.
If you would like to highlight the cursor positions at all times (useful for e.g. giving presentations), you can enable the Highlight cursor position option in the View tab.
Additionally, you can also edit how Xournal++'s interface is organized (e.g. where buttons are, where the panels should be located) by selecting one of the options in View > Toolbars.
The configuration files are generally located at $HOME/.xournalpp or $HOME/.config/com.github.xournalpp.xournalpp/ on Linux:
-
toolbar.ini- it's possible to create new toolbars layouts manually and precisely. -
colornames.ini- in case you've added custom colors in your toolbar, you can add a label to them following this format:[custom] ff00ff=4bit Magenta ff00bb=Hot pink ff0000=4bit Red ...Note that this six-hex-digits format does not include the
0xprefix, which is actually mandatory fortoolbar.ini.Example:
COLOR(0xff00bb)
The handwriting tools allow you to write on the document using a mouse or a pressure-sensitive stylus. There are three such tools: Pen, Highlighter, and Eraser.
The Pen tool allows you to draw lines on the document. It supports mouse input, as well as pressure-sensitive styluses (e.g. with a graphics tablet).
The Eraser tool can remove strokes or parts of strokes. It has three modes:
- Standard: remove parts of strokes that the cursor moves over.
- Whiteout: paint a white stroke.
- Delete Stroke: remove the entirety of any stroke that the cursor touches.
The Pen and Highlighter tools can be used to draw strokes of different colors and thicknesses.
To change the color of any selected stroke or any future strokes you draw, click on one of the color buttons (in the default layout, the color buttons are at the right side of the toolbar second from the top). Besides the preset color buttons, you can also set a custom color by clicking on the Select color button.
To change the thickness, press one of the thickness buttons (in the default layout, they are to the left of the color buttons).
It is also possible to automatically fill in the area enclosed by a stroke; this Fill Mode can be toggled by selecting the paint bucket icon (in the default layout, it is to the left of the color buttons).
The Pen and Highlighter tool can also draw shapes instead of strokes. In the default layout, you can find the Shapes Toggle Menu to the right of the Text Tool (the big "T"). The Shapes Toggle Menu will have a dropdown arrow on its right. After selecting one of the shape modes in the menu, the Pen and Highlighter will place down the selected shape instead of strokes.
The selectable shapes are:
-
Draw Rectangle: Draws a rectangle. Start point is the top-left corner.
- Hold
Ctrlto draw starting from the rectangle's center. - Hold
Shiftto draw a square.
- Hold
-
Draw Ellipse: Draws a ellipse. Start point is the top-left "corner".
- Hold
Ctrlto draw starting from the ellipse's center. - Hold
Shiftto draw a circle.
- Hold
- Draw Arrow: Draws an arrow from the initial point of contact to wherever you finish the stroke.
- Draw Line: Draws a line.
-
Draw Coordinate System: Draws an "L" shape.
- Hold
Ctrlto draw starting from the coordinate system's center (the corner). - Hold
Shiftto draw a coordinate system with the same width and height.
- Hold
- Draw Spline: Draws a spline through the knots you set by clicking or click-dragging. In the latter case the spline will be smooth at the corresponding knot and tangent to the direction you set.
- Stroke Recognizer: After you finish the stroke, it will attempt to convert the stroke into one of the shape types above (it will leave the stroke as-is if it cannot).
The Text tool inserts text (objects) onto the document. To do so, click anywhere on the document to begin editing. Any existing text objects can be altered by clicking on them with the text tool.
A text object's color and font can be customized by clicking the corresponding buttons in the toolbar.
The Image button inserts an image onto the document. Clicking on the Image button will bring up a file dialog, which will allow you to choose which image you want to insert.
An image can be repositioned or resized with one of the selection tools.
The LaTeX button inserts a LaTeX formula onto the document. Note that the LaTeX feature requires a working version of LaTeX to be installed on your computer (specifically, the feature needs to be able to call pdflatex). In addition, LaTeX standalone package needs to be installed, which typically requires installation of texlive-latex-extra or texlive-standalone. On Ubuntu or similar Linux systems this means
sudo apt-get install texlive-latex-extra
For other operating systems you will need to consult your LaTeX installation manual on how to add the standalone LaTeX package.
Clicking on the LaTeX button will bring up a dialog which will allow you to type in a formula. A preview will be displayed in the center of the dialog, which will updating as you type and indicate whether your formula is valid. Once you are done, you can click the OK button to insert the LaTeX onto the document; the rendered formula will appear at the center of the current page. The formula can be selected, moved scaled and edited as desired.
The Selection tool allows you to select areas or objects, as well as playing objects for which it is possible. The dropdown menu in the selection tool allows you to choose between different behaviors:
- Select rectangle: the selection tool will select rectangles.
- Select area: the selection tool will select areas drawn freely.
- Select object: objects (strokes, text, LaTeX objects) that have been created by Xournal++ will be selected when this option is used.
- Play object: if an object is playable and this option is active, it will be played when selected.
The Hand tool allows you to move the page or pages around when they does not fit your screen (for example, when you have zoomed in or when you have shrunk the Xournal++ window so you can't see the full contents of the page you are editing; or when you are not in presentation mode and not all pages fit the screen). As long as not all pages are in view, the hand tool will work, and it will be disabled when not needed.
Xournal++ supports both grid snapping and rotation snapping. Both are available from the menu, in Edit > Rotation Snapping and Edit > Grid Snapping.
- When rotation snapping is enabled, rotations will snap to each angle which is a multiple of 15° (0°, 15°, 30°, 45° and so on).
- When grid snapping is enabled, movements will snap to the grid, whose size can be configured in
Edit > Preferences > Drawing Area.
Snapping tolerance is a value between zero and one which determines how close to a grid point or fixed angle you need to be for snapping to be triggered: when tolerance is zero, the effect is the same as if snapping were not enabled; when tolerance is one, you cannot put the object between grid points or fixed angles (the object will jump from one point or angle directly to the other). Tolerance to both grid snapping and rotation snapping can also be configured in the drawing area preferences.
- Go to
Edit > Preferences > Audio Recordingand set theAudio Folderas well as the appropriateInput DeviceandOutput Device. - If you need to edit the recording audio gain, take a look at the preferences tab mentioned above.
Please test this new feature in advance before relying on it to work. It could contain undiscovered bugs specific to some hardware or software that we have not tested.
To record audio, first press the Start/Stop Recording button (icon: a solid red circle). Recording will begin when you create the next stroke or object and will stop when the button is pressed again. The audio playback will be attached to that object.
To playback audio, use the Play Object tool and click on the object for which you recorded audio. You can pause and stop the playback of the audio with the buttons next to the recording button in the toolbar.
The File menu has the usual entries along with an Annotate PDF option which allows you to open a PDF and draw on top, and an Export PDF option that allows you to save your document as a PDF.
The Edit menu is also pretty standard, with a Find function that allows you to search in any text, as well as a Preferences dialog.
The Journal menu allows you to configure settings for the document that is currently being edited.
The Help menu has two entries:
- Help opens the manual on your default browser.
- About pops up a window with information about Xournal++, including its authors, license, and information about the specific build that you are running.
