beamerpresenter-ui(5)

💅 NAME 💅

okay bestie, this is beamerpresenter-ui(5) — yep, the File Formats Manual page for the user interface configuration of BeamerPresenter. This is part 1 of 3, and it's giving layout-tree main character energy already. 🫶

🌸 GENERAL 🌸

The GUI configuration file is JSON-formatted ✨. It contains a list of widgets, and each widget defines its own window. Every widget is a JSON dictionary. Some widgets provide their own content, and then there are layout widgets — those don't provide their own contents, but they contain a list of child widgets. That's the whole layout tree situation, iykyk. 🌳

Example configuration files can be found in /usr/share/doc/beamerpresenter/examples/. Go look, bestie. 🎀

🧩 arguments shared by all widgets

• type name — widget type defined in section WIDGETS. This is the only mandatory argument. Periodt.
• keys keyboard shortcut — key combination to set focus to this widget. Example: use "keys":"Ctrl+F" for a search widget. 🔍
• title text — title of the widget, visible only if the widget is shown in a tabbed widget or as a top level widget (own window).
• color color name / #RRGGBB / #AARRGGBB — background color, color name known to Qt. Some Qt styles may override colors set in the GUI config. 💅

🪟 arguments for all top level widgets (widgets that are shown as windows)

• always show bool — this window should always be shown on top of other windows if the window manager supports that. Default value is false except if the widget is of type "tool selector". 👑
• width/height integer — default window width or height in pixels. 📏

🎀 WIDGETS 🎀

🕰️ clock

clock is a digital clock. This widget lets you start the timer with a double click on the clock or by tapping on the clock on a touch screen. ⏰

Arguments:

• touch input true/false — start/stop the timer by touching the clock. 🫶

🕰️ analog clock

This widget lets you start the timer with a double click on the clock or by tapping on the clock on a touch screen. ⏰

Arguments:

• touch input true/false — start/stop the timer by touching the clock.
• interval integer — update interval in milliseconds.
• seconds true/false — show/hide hand indicating seconds.
• hour/minute/second color color — color for hour/minute/second hand.
• tick color color — color for ticks.
• small ticks true/false — show/hide small ticks (6° interval).
• aspect number — preferred aspect ratio (width/height) of the widget. Adjust this if the clock is too large or too small. 🦋

📝 notes

Rich text editable notes, bestie. 📝 Notes are included when saving drawings to gzipped xml file (.bpr/.xopp). Alternatively, they can be saved separately in an xml file using the keyboard actions while the notes widget has focus: save notes with Ctrl+S, save under new file name with Ctrl+Shift+S, open from file with Ctrl+O. Currently the notes are saved as HTML string, which is escaped when saving in xml format. This format might change in the future! 😭

Arguments:

• identifier "label" or "number" — notes are associated with a page (number) or a group of pages with the same page label.
• id — only required when using multiple distinct notes widgets: unique ID of this widget used when saving or loading notes.
• zoom integer — zoom step for the widget (defined by QTextEdit).
• file path — path to xml-file to read notes from. The notes file contains a root element <speakernotes> with child elements <page-notes> containing the rich text notes. Each page element has an attribute "label" or "number" to identify a page or a group of pages. Which of "label" or "number" is used must be specified by the attribute "identifier" or the root element.

Example file:

<?xml version="1.0" encoding="UTF-8"?>
<speakernotes identifier="label">
<page-notes label="1">notes on first page
</page-notes>
<page-notes label="2">notes on second page
</page-notes>
</speakernotes>

🔍 search

Search text in PDF document. It jumps to the next slide on which the searched text is found and highlights all occurrences (or up to 20 occurrences when using MuPDF) on this slide. To highlight occurrences of the text on another slide you need to start a new search. The search is case-insensitive. You can use the option "keys":"Ctrl+F" to start a search with Ctrl+F. 🔎

⚙️ settings

Change settings and get help. That's it. That's the widget. 🛠️

🎬 slide

Slide of a presentation. This is the main widget shown to the audience and on the speaker's screen. 👑

Arguments:

• file path — PDF file shown in the presentation or alias name. Aliases such as "presentation" or "notes" will be filled with command line arguments or by asking in a file open dialog.
• shift integer — shift slide number relative to the main presentation slide. E.g. shift=1 creates a preview of the next slide, which can be shown in the speaker's view.
• page part left/right — side of the page to be shown if the pages are split into a left and a right side showing presentation and notes on the same page.
• media controls = false — show/hide a slider to navigate inside a video. 🎥
• show tools = true — enable/disable pointing tools.
• media = true — enable/disable multimedia content on this widget. Caution: if multiple widgets show the same slide, the configuration of one of these widgets is used for the other widgets. Switching off multimedia for one widget may also disable multimedia for other widgets.
• mute = true — mute or unmute the slide connected to this widget. By default normal slides are muted and slides marked as "master" are unmuted. Make sure that exactly one slide widget is unmuted in the GUI configuration (typically the presentation slide widget). 🔇
• transitions = true — enable/disable slide transitions. Caution: if multiple widgets show the same slide, the configuration of one of these widgets is used for the other widgets. Switching off transitions for one widget may also disable transitions for other widgets.
• autoplay = true — automatically play videos on this slide. Caution: if multiple widgets show the same slide, the configuration of one of these widgets is used for the other widgets. Switching off autoplay for one widget may also disable it for other widgets.
• cache videos = true — cache videos before the slide with the video is reached. Caution: if multiple widgets show the same slide, the configuration of one of these widgets is used for the other widgets.
• draw = true — enable/disable drawing on this widget. Caution: if multiple widgets show the same slide, the configuration of one of these widgets is used for the other widgets. Disabling drawing for one widget may disable it also for other ones. ✏️
• cache hash integer — integer to identify slide widgets with the same geometry, which should use the same cached slides. Set the same "cache hash" for multiple slides to make them use the same cache. Note that this can also cause problems if the geometry of the widgets is not exactly the same. ⚠️
• threads integer — number of threads used to pre-render pages in cache. Disable pre-rendering by setting this to zero.
• overlays first/last/none — show only first/last page of each group of pages with the same page label.
• scroll mode aspect number — Experimental: set width / height ratio of scroll view widget. Scroll view means that the page size is not completely fit to the window size. Instead, pages will be shown with fixed width and you probably want to scroll down. See also: actions "scroll down" and similar. 🌀

🏷️ slide label

Show label of current slide and allow navigation by editing the slide label. 🏷️

🔢 slide number

Show number of current slide and allow navigation by editing this number. 🔢

🖼️ thumbnails

Thumbnail overview of all slides. 🖼️

Arguments:

• overlays skip — set this option to "skip" to show only one preview slide for each group of pages with the same page label.
• columns integer — number of columns in which the thumbnail slides are arranged.
• file path or alias — path to PDF document defining which thumbnail images are shown. By default, this is the alias "presentation" for the default file shown to the audience.

⏱️ timer

Timer for the presentation. Both the total time and the passed time are editable text fields. By double-clicking between these two text fields you can store the passed time (left field) as the target time for the currently visible page. These times per page are stored when saving drawings. The times per page are used to indicate the current progress relative to the planned progress by the background color of the passed time text field. ⏳

Arguments:

• require confirmation bool — ask for confirmation before setting the time for a slide.
• confirmation default bool — when asking for confirmation when setting the time for a slide, this will be the default (accept or cancel). The default value is false. ✅

colormap JSON object

Okay so this one is lowkey the glow-up of the whole timer vibe 💅 — it lets you customize the function that maps the current time relative to the target time of the current slide onto a color. This JSON object maps times (as integers, in seconds) to colors (e.g. in #rrggbb format). Positive times mean the speaker has that amount of time left 🫶. Between the times you define in this map, a linear interpolation is used — so it's all smooth, no cap.

Default configuration:

"colormap" : {
"-300" : "#ff0000",
"-90"  : "#ffff00",
"0"    : "#00ff00",
"90"   : "#00ffff",
"300"  : "#ffffff"
}

---

toc

Outline / table of contents ✨ — shows the document outline tree. Very "let me see the whole syllabus" of it, honestly.

Arguments:

• file path or alias — Path to the PDF document defining which outline is shown. By default, this is the alias "presentation" for the default file shown to the audience.

---

tools

Shows the current mapping of devices to tools 🖱️🧚 — and you can change the tools using a pop-up dialog. Currently this shows a block of mouse buttons (a touch pad is treated like a mouse), the touch input (if available), and a block of tablet devices (if available). For simple usage this is best combined with a tool selector widget — they're literally a match made in heaven 💖.

Arguments:

• orientation horizontal/vertical — Arrange different devices next to each other or above each other.
• mouse devices array — List of devices that are included in the group of mouse devices. Possible values: "left button", "right button", "middle button", "no button"
• tablet devices array — List of devices that are included in the group of tablet devices. Possible values: "tablet pen", "tablet eraser", "tablet hover", "tablet cursor", "tablet mod", "tablet other"

---

tool selector

A grid layout of buttons, bestie — think of it like your fave app's tool palette but make it presentation-core 🎀. It contains a mandatory argument buttons, which must be an array of arrays of buttons. That array of arrays constitutes a matrix defining the arrangement of the buttons. A button can be any of the following:

• string defining an action — Available actions are listed below in section ACTIONS. Pushing an action button is equivalent to sending a keyboard shortcut connected to that action.
• JSON array of strings defining actions — A button can have multiple actions. Slay, multitasking queen 👑.
• string defining a tool — The tool is created with default settings.
• JSON object defining a tool — The JSON object must have the property "tool" defining the tool. Available tools and their configuration options are listed below in section TOOLS.
• string defining a tool property — A drop down menu for this tool property is created. Available tool properties are: "color", "width" (in points), "shape" (for draw tools), "style" (pen style for draw tools), "brush" (fill pattern for draw tools).
• JSON object defining a tool property — The JSON object must have the items "select":"property" where "property" should be replaced. It should further have the item "list":[...] containing a list of selectable values for the drop down menu.

Examples:

{"select":"color", "list":["red", "green", "blue"]}
{"select":"width", "list":[0.5, 1, 2, 4]}

🫶 fun fact (well, actual fact): it is possible to select a different tool for a button while BeamerPresenter is running by clicking the button while pressing the ctrl key. But this changes the tool only temporarily, and this modification will not be saved. So don't come crying when it's gone, bestie 😭

---

🌈 LAYOUTS 🌈

horizontal

Horizontally arranged child widgets. The relative size of the widgets is determined by their preferred aspect ratios to ensure maximal usage of the screen by slide widgets ✨.

vertical

Vertically arranged child widgets — see horizontal. Same energy, rotated 90° 🌀.

stacked

Stacked child widgets, shown in the same place. The currently visible widget can only be selected by keyboard shortcuts defined using the "keys" argument of the subwidgets. iykyk 🔑

tabbed

Similar to stacked widget, but shows the child widgets as tabs, which can be selected using the cursor 💅.

Arguments:

• orientation north/east/south/west — position of the tab bar.

---

🔥 ACTIONS 🔥

Available actions are:

• previous — navigate to previous page
• next — navigate to next page
• first — navigate to first page
• last — navigate to last page
• update — Update view (technically navigates to current page)
• next skipping overlay — Navigate to next page which has a different page label than current page
• previous skipping overlays — Navigate to previous page which has a different page label than current page
• insert slide — Insert a new empty slide that can be used for drawing. Blank canvas era 🎨
• remove slide — Remove current slide. Restore slides by navigating to the previous slide and inserting a slide.
• restore slide — Restore a previously removed slide. If the current slide is a PDF page, try to restore PDF pages before trying to restore non-PDF pages.
• reload — Reload the presentation PDF (if it has been modified).
• undo — Undo last drawing action on current page
• undo left/right — Undo last drawing action on left/right part of current page, assuming that the page is split into a left and right half which represent presentation and notes, respectively
• redo — Redo last drawing action on current page
• redo left/right — Redo last drawing action on left/right part of current page, assuming that the page is split into a left and right half which represent presentation and notes, respectively
• clear — Clear all drawings on the current page.
• clear left/right — Clear all drawings on the left/right part of current page, assuming that the page is split into a left and right half which represent presentation and notes, respectively
• scroll up/normal/down — Scroll the slide view up / to normal position / down. This allows the presenter to add extra space for drawings. "scroll normal" also resets zoom.
• zoom in/reset/out — Zoom the slide view. Use the tool "drag view" (experimental) to drag the zoomed view and to zoom using double-click, click and scroll, or touch zoom gestures.
• save — Save drawings to file. Does not ask for file name if a file name is known.
• save as — Save drawings to file. Always asks for the file name.
• open — Load drawings from file.
• open unsafe — Load drawings from file without clearing existing paths.
• export svg — Experimental: Export all drawings as SVG images, one image per page. 🦋
• copy — Copy selected items on currently focused slide to clipboard.
• paste — Paste clipboard on currently focused slide.
• cut — Copy selected items on currently focused slide to clipboard and remove them.
• to foreground — Move selected items on currently focused slide to the foreground.
• to background — Move selected items on currently focused slide to the background.
• delete — Delete selected items on currently focused slide. 💀
• select all — Select all items on currently focused slide.
• clear selection — Clear selection on currently focused slide.
• start/stop/toggle timer — Start or stop timer in timer widget.
• reset timer — Reset the timer (passed time) in timer widget.
• play/pause/stop media — Start, pause or stop playing multimedia content.
• mute/unmute — Mute or unmute all multimedia content. Media on slides views which are muted in the GUI config are not affected.
• fullscreen — Toggle full screen view for currently active window.
• quit — Close BeamerPresenter. Ask for confirmation if there are unsaved changes. Note that the detection of unsaved changes is not reliable yet 👀 so maybe save your stuff, bestie.
• quit unsafe — Close BeamerPresenter ignoring unsaved changes. Main character energy, zero regrets 🙈

✨ TOOLS ✨

okay so tools are configured in a JSON object that looks like {"tool":"pen", ...} and then you fill in the configuration options listed below. Some config options are shared across whole groups of tools — like draw tools, for example. Also important: all lengths (stroke width, etc.) are in points (1/72 inch) in the PDF. periodt 💅

🛠️ Common Options for all tools

these ones work for every single tool, bestie:

• color — Color name known to Qt or #RRGGBB or #AARRGGBB
• device — Device name (e.g. "tablet pen", "touch"), "all", or "all+" (see also beamerpresenter.conf (5)). If this property is set, pushing this button will set the tool for the defined input devices. If this property is not set, then the tool will always be set only for the input device with which the button was pressed.

✋ General Tools

• none — No tool or hand tool. Follow hyperlinks and click on videos to start or stop them.
• drag view — Drag and zoom view. Available configuration options:
  • touch-zoom bool — Zoom using touch screen pinch gesture
  • scroll "zoom" | "move" | "none" — Effect of scroll wheel (only when the tool is active for a device that supports scrolling)
  • double-click "zoom" | "none" — Effect of double click with left mouse button (only when the tool is active for a device that supports double click)
• text — Add a text field. Configurable options:
  • font — Anything that Qt can interpret as a font name.
  • font size — Font size (positive number).

🖊️ Draw Tools

• pen — Pen of variable line width if the input device provides pressure information.
• fixed width pen — Pen of fixed line width.
• highlighter — Fixed width pen with default options adjusted for highlighting.

Common options for draw tools

• width — Stroke width in pt (positive number).
• fill — Color to fill the path. Leave empty if paths should not be filled.
• style = SolidLine — Pen style for stroking the path. Possible values are "nopen" , "solid", "dash", "dot", "dashdot", and "dashdotdot".
• brush = SolidPattern — Filling style of the path, see https://doc.qt.io/qt-6/qt.html#BrushStyle-enum for valid names. Gradients are not allowed.
• shape = freehand — Draw this shape instead of a freehand path. Allowed values are "freehand", "rectangle", "ellipse", "line", and "arrow".
• composition — Composition mode, valid values are: "source over" (default for pen), "darken" (default for highlighter), "lighten", "difference", "plus", "multiply", "screen", "overlay"

🔦 Pointing Tools

• eraser — Erase previously drawn strokes. Option:
  • linewidth = 0 — Draw a circle of given line width around the eraser. The circle is only drawn on the currently active widget.
• pointer — Laser pointer.
• magnifier — Enlargen the slide in a circular region. Option:
  • scale = 2 — Magnification factor (number between 0.1 and 5).
• torch — Highlight parts of the slide by darkening everything else.

Common options for pointing tools

• size — Radius of the tool (positive number).

🎯 Selection Tools

• click select — Click on items to select them.
• rectangle select — Select items in a rectangular region.
• freehand select — Select items in a drawn region.

---

👀 SEE ALSO

go say hi to beamerpresenter(1) and beamerpresenter.conf(5), — they’re literally right there, bestie 🫶

---

this lil page is serving version 0.2.6, dated 2024-12-25 — beamerpresenter-ui(5) forever, no cap 💖✨