2. Configuration

The Lumina® Configuration utility, shown in Figure 2.1, can be used to configure every aspect of the desktop and is the recommended way to make changes. To launch this utility, click the start menu then Preferences Configure Desktop, right-click the desktop and hover over Preferences and click All desktop settings, or type lumina-config in a CLI. If all those options are unavailable, the “Desktop Configuration” application (under the Utilities category) will also open the configuration utility. For convenience, the Preferences section of the right-click menu also lists the commonly used sub-elements of Screensaver, Wallpaper, and Display from within the Configuration utility.


Fig. 2.1 : Lumina® Desktop Configuration

Under the top search bar are four options to configure different areas of the system. By default, each category is expanded to provide an efficient view of all available configutation options. Click an option to view the specific configuration options.


If you make changes to any of the options, remember to click Save before exiting this utility in order to save them. Lumina® will prompt for a decision if any unsaved changes are present when attempting to navigate away from the current settings area.

The rest of this section describes the configurations that are available in each category.

2.1. Appearance

This category is used to change the visual appearance and functionality of the desktop on a per-screen basis.

2.1.1. Theme Settings

The Theme option, shown in Figure 2.1.1, can be used to change the default font, font size, theme template, color scheme, icon pack, and mouse cursors.


Fig. 2.1.1 : Theme settings, Desktop Tab

It is possible to create your own theme template or color scheme by clicking Edit next to those options and changing the settings as necessary. Figure 2.1.2 shows an example of clicking Edit with the Glass (System) theme template selected. This action opened the Theme Editor and the user has clicked the color selector (dropper icon) in the upper right corner. Select an item in this menu to edit the template controlling the selection by changing the values in the theme editor box. Note the theme templates are written as Qt stylesheets, so some scripting experience will be helpful when configuring a theme. After making your changes, click Save to save the theme without closing the editor, or click Apply, which saves the theme and closes the editor.


Fig. 2.1.2 : Using the Theme Editor

The Application Themes tab, seen in Figure 2.1.3, allows the user to easily apply any installed Qt5 theme engines to any Qt based applications.


Fig. 2.1.3 : Application Themes tab, with Qt5 Theme Engine pressed.

Select the Qt5 Theme Engine drop down menu to choose between the defaults of None or Manual Setting. Any user installed theme engines will also appear in this drop down menu.

2.1.2. Wallpaper

The Wallpaper option, shown in Figure 2.1.4, can be used to add or remove a wallpaper with the + or - buttons, respectively. When + is pressed, the drop-down menu can be used to select the file(s), a single directory, a directory and all of its subdirectories, or a solid color to use as the wallpaper. If multiple images are selected, Rotate Background can be selected as well as a specified time interval in minutes to move to the next image.


Fig. 2.1.4 : Lumina® Wallpaper Settings

Click the Layout drop-down menu to change the default layout of Automatic to one of several options: Fullscreen, Fit screen, Tile, Center, Top Left, Top Right, Bottom Left, or Bottom Right.

Click + Solid Color to view all the wallpaper options shown in Figure 2.1.5. Select a color and click OK to add that color as a solid background to the wallpaper selection drop-down menu.


Fig. 2.1.5 : Modifying the Wallpaper

2.1.3. Window Effects

Window Effects, shown in Figure 2.1.6, is used to add or alter graphical effects or animations applied to your windows. By default, no additional effects are added. Any desired changes need to be adjusted manually.


Fig. 2.1.6 : Window Effects

Check Disable Compositing Manager to enable this option. Restarting the current session is required for any changes to take effect. By default, Only use compositing with GPU acceleration is selected, which aids with overall system performance.

2.1.4. Window Manager

Window Manager, shown in Figure 2.1.7, contains various configuration options for the window manager.


Fig. 2.1.7 : Session Window Manager

Drop-down menus are provided for configuring all options:

  • Number of Workspaces: A maximum of 10 workspaces can be defined, with a default of 2.
  • New Window Placement: Indicates where new windows are placed on the screen. Choices are Align in a Row, Align in a Column, Cascade”, or *Underneath Mouse.
  • Focus Policy: Indicates when windows receive focus. Choices are Click to Focus, Active Mouse Focus, or Strict Mouse Focus.
  • Window Theme: Controls the appearance of the frame around application windows. The Window Theme Preview screen can be used to preview the selected theme.

The Advanced Editor, seen in Figure 2.1.8, provides options to manually adjust every setting related to the display of windows on the system.


Fig. 2.1.8 : Window Manager - Advanced

2.2. Desktop Defaults

The Desktop Defaults category, seen in Figure 2.1, is used to configure which applications automatically start upon logging in to Lumina®, the default applications and file types, and keyboard shortcuts.

2.2.1. Applications

Click Applications to view the default applications Basic Settings tab, shown in Figure 2.2.1. This tab can be used to configure default applications.


Fig. 2.2.1 : Lumina® Default Applications - Basic

The default web browser, email client, file manager,and virtual terminal are all configurable. Click the desired application, and a new window will appear, allowing a new default application to be chosen. To return to the default application, click the current application’s name, then Restore Defaults.


Some applications, such as web browsers, keep their own internal lists of default applications for opening particular types of files. These applications, when configured to use the lumina-open or xdg-open utilities, will refer back to the default applications set in Applications.

The Advanced tab allows for configuring the default application used for particular file types, as seen in Figure 2.2.2.


Fig. 2.2.2 : Lumina® Default Applications - Advanced

To add an application, select the file type and specific group and either click Set App, which will open a drop-down menu of common applications, or Set Binary, which will open a file browser for navigating the application path. Alternately, selecting only a file type and clicking Set App or Set Binary will register the application for all the groups within the selected type. Selecting Clear will remove the default application from the associated file type or group.

2.2.2. Keyboard Shortcuts

Keyboard Shortcuts, shown in Figure 2.2.3, is used to configure various keyboard shortcuts for system or window tasks. Most of these options relate to window and workspace management, such as moving windows between workspaces, but there are also options for changing the system audio volume or screen brightness.


Fig. 2.2.3 : Lumina® Keyboard Shortcuts - Basic

To create a shortcut, click the desired entry, then Change Shortcut, and define the desired key combination. Any entry with an already defined shortcut showing in the Keyboard Shortcut column can not be assigned to another action. To free a shortcut for reuse, highlight the shortcut, click Clear Shortcut, then Save Changes. A new shortcut can now be created.

Click Advanced Editor, seen in Figure 2.2.4, to manually adjust or create all keyboard shortcuts. By default, syntax codes are shown in their own display area, but this can be hidden by unchecking View Syntax Codes.


Fig. 2.2.4 : Lumina® Keyboard Shortcuts - Advanced

2.2.3. Autostart

Autostart, displayed in Figure 2.2.5, provides adjustment options for what is automatically started when logging into Lumina®.


Fig. 2.2.5 : Lumina® Startup Services Configuration

To prevent an application from starting automatically, uncheck its box. To add an application to the auto-start configuration , click Application to select the application’s name from a drop-down menu. Alternately, click Binary or File to browse to the location of the application or file to open. If a file is chosen, Lumina® will automatically open it in an application that is capable of reading the file type.

2.3. Interface Configuration

Interface Configuration, as seen in Figure 2.3.1, is used to configure the desktop, (right-click) menu, and any panels.


Fig. 2.3.1 : Lumina® Interface Configuration


The options of Menu, Desktop, and Panels involve modifying and interacting with plugins, which are described at length in the Plugins chapter of this handbook.

2.3.1. Desktop

Select Desktop to modify what appears on the current primary desktop. By default, the RSS Reader plugin will appear in the lower right corner.

Many customization options are available after right-clicking an icon on the desktop:

  • Launch Item: Starts the item.
  • Start Moving Item: Click the icon to lock it in place once it is in the desired location.
  • Start Resizing Item: Use the mouse to increase or decrease size. Click when finished adjusting the icon to save the changes.
  • Increase Desktop Icon Sizes: Increases the size of all desktop icons, repeat as necessary.
  • Decrease Desktop Icon Sizes: Decreases the size of all desktop icons, repeat as necessary.
  • Remove Item: Removes the item from the desktop.

2.3.3. Panels

The Panels option offers the ability to create and/or customize panels which are attached to the edges of the screen, as seen in Figure 2.3.3.


Fig. 2.3.3 : Lumina® Panel Configuration

This screen can be used to customize the location, alignment, size, theme, and plugins for an existing panel. The + and - icons towards the top, next to Panel 1 can be used to add or remove additional panels. Panels must be aligned along a screen edge, opposite screen edges in the case of two panels, and may have any width, color, or transparency.


When adding panels, a frame similar to Panel 1 will be created for each panel, labeled Panel 2, Panel 3, and so on. This allows each panel to be configured separately. The configuration tabs available for a panel are described below. Be sure to select the tab in the desired panel.

The Location tab (4 arrow icon) contains a number of items:

  • Edge: This drop-down menu can be used to set the location of the panel which can be Top, Bottom, Left, or Right.
  • Alignment: This drop-down menu can be used to center the panel on the edge or pin it to one of the corners.
  • Size: Can be used to specify the panel width in pixels and the panel length.

The Appearance tab (monitor icon) is shown in Figure 2.3.4.


Fig. 2.3.4 : Panels Appearance Tab

To hide the panel unless the mouse is hovered over it, check Auto-hide Panel. The Custom Color option can be used to fine-tune the panel color. Click its box, then the paint icon to select a panel color.

The Plugins tab (puzzle icon) is shown in Figure 2.3.5.


Fig. 2.3.5 : Panels Plugins Tab

To add a plugin as an icon to the panel, click + below the listed plugins and select a plugin from the list that appears. To remove a plugin, highlight it and click -, which is below the listed plugins. The arrow buttons can be used to move the location of the plugin on the panel. The top of an ordered list corresponds to either the top of a vertical panel or the left side of a horizontal panel.

By default, Lumina® will have one panel which stretches across the bottom of the primary screen and another auto-hiding panel centered at the top of the screen. The bottom panel incorporates the Start Menu, Task Manager Plugin (No Groups), a Spacer, System Tray, Time/Date, and Battery Monitor plugins. The top panel includes the Desktop Bar between two Spacer plugins.

2.4. User Settings

The User Settings option governs the general settings for the desktop session. These settings are typically left unchanged.

2.4.1. General Options

General Options, seen in Figure 2.4.1, is used to govern numerous settings for the desktop experience.


Fig. 2.4.1 : Lumina® General Options

The user can choose to automatically enable numlock, play chimes when Lumina® starts or exits, and change the icon that appears in the login menu and the start menu button. There are also options to set the time and date format, as well as the time display format (using a drop menu). Additionally, a user can reset all their desktop settings via Return to system defaults, which returns Lumina® to the defaults created by the OS, while Return to Lumina defaults returns to the Lumina® created settings.

2.4.2. Localization

The Localization is shown in Figure 2.4.2.


Fig. 2.4.2 : Session Locale Tab

The lumina-i18n package provides localization files. Once installed, this allows customization of the locale used for the various items listed in Figure 2.4.2. To install this package on a TrueOS® or FreeBSD system, type sudo pkg install lumina-i18n. On other operating systems, use the default software management tool. Since each setting has its own drop-down menu, there is flexibility to select different locales for each item shown in this screen. If any changes are made in the Locale tab, click Save Changes and restart Lumina® to load the configured locales.

Installing the lumina-i18n package will also add a drop-down menu to the Preferences area of the start menu, though Lumina® will need to be restarted after the package installation to add the locale menu to Preferences. This drop-down menu is used to change the locale for the current session only. This will immediately change the localization of any translated menu items without requiring a restart of Lumina®.


If using Lumina® with a language other than English, any menu items that continue to be displayed in English have not yet been translated to the selected language. To assist the Lumina® Project in translating menu items, see Interface Translation.

2.4.3. Input Device Settings

Input Device Settings provides a full array of configuration options for each detected input device. Figure 2.4.3 shows options to configure a keyboard, while Figure 2.4.4 shows the available mouse options.


Fig. 2.4.3 : Input device configuration, Keyboard settings

Keyboard settings are generally confined to enable/disable, and are spread from the master device and any extension devices.


Fig. 2.4.4 : Mouse configuration settings

There are a number of different elements available to configure for a basic mouse, seen in Table 2.4.1. For more in-depth descriptions of these options, refer to x.org’s article on PointerAcceleration:

Table 2.4.1 : Mouse configuration options
Option Name Default Value Description
Button Labels Button Names Displays all button names on the device
Device Accel Adaptive Deceleration 1.00 Improves mouse control at the pixel level without reducing overall speed
Device Accel Constant Deceleration 1.00 Decelerates the mouse by a factor equal to the chosen number value
Device Accel Profile 0 Different acceleration configurations. “1” is not a valid option at this time
Device Accel Velocity Scaling 10.00 Controls the sensitivity of acceleration. The effect is dependent on the chosen profile
Device Enabled Checked Used to activate/deactivate the device
Device Node Path to Node Displays the pathway to the mouse node file
Mouse Middle Button Emulation Checked (if a middle button is detected) Activate/deactivates the middle mouse button
Mouse Middle Button Timeout 50 A millisecond value for the driver to wait before deciding two buttons were “simultaneously” pressed

When an incompatible value is set, the entire option line will be highlighted in red.