View on GitHub

Flex Launcher

A customizable HTPC application launcher and front-end interface

Configuring Flex Launcher

Table of Contents

  1. Overview
  2. Settings
  3. Creating Menus
  4. Clock
  5. Screensaver
  6. Hotkeys
  7. Gamepad Controls
  8. Transparent Backgrounds

Overview

Flex Launcher uses an INI file to configure settings and menus. The INI file consists of sections enclosed in square brackets, and in each section there are entries which consist of a key and a value. Example:

[Section]
Key1=value
Key2=value
...

A line can be commented out by using the # character at the beginning of the line, which will cause the line to be ignored by the program. In-line comments are not allowable. Here are a few things to note about the configuration settings for Flex Launcher:

Settings

The following sections contain settings that control the look and behavior of the launcher:

General

The settings in this section control the general behavior of the launcher.

DefaultMenu

This is the title of the main menu that shows when Flex Launcher is started. The value must match the name of one of your menu sections, or there will be an error and Flex Launcher will refuse to start. See the Creating Menus section for more information.

VSync

Defines whether VSync will be used to synchronize the frame rate with the refresh rate of your monitor. This setting is a boolean “true” or “false”

Default: true

FPSLimit

When VSync is set to false, this setting defines the maximum number of frames per second that Flex Launcher will render. The minimum is 10, and the maximum is the same as the refresh rate of your monitor.

OnLaunch

Defines the action that Flex Launcher will take upon the launch of an application. Possible values: “None”, “Blank”, and “Quit”

Default: Blank

ResetOnBack

Defines whether Flex Launcher will remember the previous entry position when going back to a previous menu. If set to true, the highlight will be reset to the first entry in the menu when going back. This setting is a boolean “true” or “false”.

Default: false

MouseSelect

Defines whether the left mouse button can be used to select the highlighted entry. This setting is intended to support gyroscopic mouse devices where the enter/ok button functions as a mouse left click instead of the keyboard enter button. This setting is a boolean “true” or “false”.

Default: false

InhibitOSScreensaver

Defines whether Flex Launcher will prevent your default OS screensaver from activating while it is running. On Windows, this will also inhibit any power saving features as well (e.g. autosleep). This setting is a boolean “true” or “false”.

Default: true

StartupCmd

Defines a command that Flex Launcher will execute immediately upon startup. This can be used to autostart your favorite application.

QuitCmd

Defines a command that Flex Launcher will execute immediately before quitting. This can be used to do any mode switching or appplication starting to prepare your desktop, e.g. for maintenance.

Background

The settings in this section control what Flex Launcher will display in the background.

Mode

Defines what mode the background will be. Possible values: “Color”, “Image”, and “Slideshow”

Default: Color

Color

When Mode is set to “Color”, this setting defines the color of the background.

Default: #000000 (Black)

Image

When Mode is set to “Image”, this setting defines the image to be displayed in the background. The value should be a path to an image file. If the image is not the same resolution as your desktop, it will be stretched accordingly.

SlideshowDirectory

When Mode is set to “Slideshow”, this setting defines the directory (folder) which contains the images to display in the background. The value should be a path to a directory on your filesystem. The number of images that may be scanned from the directory is limited to 250.

SlideshowImageDuration

When Mode is set to “Slideshow”, this setting defines the amount of time in seconds to display each image. Must be an integer value.

Default: 30

SlideshowTransitionTime

When Mode is set to “Slideshow”, this setting defines the amount of time in seconds that the next background image will fade in. The fading transition may be disabled by setting this to 0, which will yield a “hard” transition between images. Decimal values are acceptable.

Default: 3

ChromaKeyColor

When Mode is set to “Transparent”, this setting defines the color that will be applied to the background for chroma key transparency.

Default: #010101

Overlay

Defines whether the background overlay feature is enabled. The background overlay is a solid color, typically black, that is painted over your background to improve the contrast between the background and the text/icons. This setting is a boolean “true” or “false”.

Default: false

OverlayColor

Defines the color of the background overlay.

Default: #000000 (Black)

OverlayOpacity

Defines the opacity of the background overlay. Must be a percent value.

Default: 50%

Layout

The settings in this section define the geometric layout of the launcher.

MaxButtons

The maximum number of buttons that can be displayed on the screen. If a menu has more entries than this value, it will be split into multiple pages. A value of 3-5 is sensible for a typical TV size and viewing distance.

Default: 4

IconSize

The width and height of icons on the screen in pixels. If an icon is not the same resolution, it will be stretched accordingly.

Default: 256

IconSpacing

Distance between the menu entry icons, in pixels or percent of the screen width.

Default: 5%

VCenter

Defines the vertical centering of the menu entries in percent of the screen height. A value of 50% will cause the buttons to be centered halfway in the screen. Increasing the value will lower the buttons, and lowering it will raise them.

Default: 50%

Titles

The settings in this section affect the application titles that display below the icons.

Enabled

Defines whether or not application titles are enabled. This setting is a boolean “true” or “false”.

Default: true

Font

Defines the font to use for the titles of the menu entries. The value should be the path to a TrueType (TTF) font file. Non-TTF font formats are not supported. Flex Launcher ships with a handful of libre fonts.

Default: OpenSans

FontSize

Defines the font size of each menu entry title.

Default: 36

Color

Defines the color of the menu entry titles.

Default: #FFFFFF (White)

Shadows

Defines whether shadows are enabled for the menu titles. Shadows give a 3D textured appearance to the text to improve the contrast from the background. This setting is a boolean “true” or “false”.

Default: false

ShadowColor

Defines the color of the title shadows.

Default: #000000 (Black)

Opacity

Defines the opacity of the menu entry titles. Must be a percent value.

Default: 100%

OversizeMode

Defines the behavior when the width of a menu entry title exceeds the width of its icon (which is defined in IconSize). Possible values: “Truncate”, “Shrink”, and “None”

Default: Truncate

Padding

Defines the vertical spacing between an icon and its title, in pixels.

Default: 20

Highlight

The settings in this section control the menu highlight.

Enabled

Defines whether or not the highlight is enabled. If a user disables the highlight, it is assumed that they will be using the Sected Icon Overrides feature instead. This setting is a boolean “true” or “false”.

Default: true

FillColor

Defines the fill color of the highlight cursor.

Default: #FFFFFF (White)

FillOpacity

Defines the fill opacity of the highlight cursor. Must be a percent value.

Default: 25%

OutlineSize

Defines the stroke width in pixels of the outline of the highlight cursor. Setting this to 0 will disable the outline.

Default: 0

OutlineColor

Defines the outline color of the highlight cursor.

Default: #0000FF (Blue)

OutlineOpacity

Defines the outline opacity of the highlight cursor. Must be a percent value.

Default: 100%

CornerRadius

Defines the corner radius of the highlight cursor, in pixels. A value of 0 will yield a plain rectangle. Increasing the value will yield a rounded rectangle with increasingly round corners. The value of HighlightOutlineSize must be 0, otherwise this setting will be ignored.

Default: 0

VPadding

Defines the amount of vertical distance that the highlight cursor extends beyond the top and bottom of the menu entry icon, in pixels.

Default: 30

HPadding

Defines the amount of horizontal distance that the highlight cursor extends beyond the left and right of the menu entry icon, in pixels.

Default: 30

Scroll Indicators

The settings in this section pertain to scroll indicators. Scroll indicators are arrows which appear in the bottom left and/or bottom right of the screen to inform the user that there are additional pages of applications to scroll to.

Enabled

Defines whether scroll indicators will be enabled in the event that a menu has multiple pages of entries. This setting is a boolean “true” or “false”.

Default: true

OutlineSize

Defines the stroke width in pixels of the scroll indicator outline. Setting this to 0 will disable the outline.

Default: 0

FillColor

Defines the fill color of the scroll indicators.

Default: #FFFFFF (White)

OutlineColor

Defines the color of the scroll indicator outline.

Default: #000000 (Black)

Opacity

Defines the opacity of the scroll indicators. Must be a percent value.

Default: 100%

Creating Menus

At least one menu must be defined in the configuration file, and the title must match the DefaultMenu setting value. The title of a menu is its section name. Any title may be used that is not reserved for another section, such as “Settings”, “Gamepad”, etc. The entries of the menu are implemented as key=value pairs. The name of the key will be ignored by the program, and is therefore arbtrary. However, it is recommended to pick something intutitive such as Entry1, Entry2, Entry3, etc. The entry information is contained in the value.

Each entry value contains 3 parts of information in order: the title, the icon image path, and the command to run when the button is clicked. These are delimited by semicolons:

Entry=title;icon_path;command

The command is typically one of the following:

  1. The path to the program executable that you want to launch
  2. Windows: the path to a program shortcut (.lnk file)
  3. Linux: the path to a .desktop file
  4. A special command
  5. The path to an executable script, in the case that you want to perform multiple actions upon program launch.

A simple example menu titled Media is shown below:

[Media]
Entry1=Kodi;C:\Pictures\Icons\kodi.png;"C:\Program Shortcuts\kodi.lnk"
Entry2=Netflix;C:\Pictures\Icons\netflix.png;"C:\Program Shortcuts\netflix.lnk"
Entry3=Plex;C:\Pictures\Icons\plex.png;"C:\Program Shortcuts\plex.lnk"
Entry4=Back;C:\Pictures\Icons\back.png;:back

Selected Icon Overrides

The Selected Icon Override feature allows the user to define a different icon for the launcher to display when an entry is highlighted. To use this feature, name the path of the selected icon the same as the default entry icon path, but with a suffix of _selected (not including the file extension).

For example, if the icon path for an entry is defined as C:\icons\kodi.png, then the program will check for the existence of C:\icons\kodi_selected.png and, if it exists, this icon will be shown when the entry is selected instead of the default. This feature allows the user to implement custom highlight effects such as glowing, color changes, etc.

Special Commands

Special commands are commands that are internal to Flex Launcher and begin with a colon. The following is a list of special commands:

Change to a different menu. Requires a menu title as an argument. For example, the command :submenu Games will change to the menu Games. The argument must be a valid menu title that is defined elsewhere in the config file.

:fork

Forks a new process and executes a command in it without exiting the launcher. This is typically used in combination with a hotkey. Use this special command when you want to execute a command on your system for some reason other than launching a graphical application. Example use cases:

The :fork special command requires a command as an argument. For example :fork command arguments will execute command arguments without leaving the launcher.

Windows users should invoke a command line interpreter such as Command Prompt and pass the command to run as an argument, e.g. :fork cmd.exe /c "command arguments"

:exit

Windows only. Quits the currently running application. This special command is only available as a hotkey command. See the Exit Hotkey section for more information.

:back

Go back to the previous menu.

:home

Change to the menu defined in the DefaultMenu setting.

:quit

Quit Flex Launcher.

:left

Move the highlight cursor left.

Move the highlight cursor right.

:select

Press enter on the current selection. This special command is only available as a gamepad or hotkey command, it is forbidden for menu entries.

:shutdown

Shut down the computer.1

:restart

Restart the computer.1

:sleep

Put the computer to sleep.1

1 Linux: Works in systemd-based distros only. Non-systemd distro users need to implement the command manually for their init system.

Desktop Files (Linux Only)

If the application you want to launch was installed via your distro’s package manager, a .desktop file was most likely provided. The command to launch a Linux application can simply be the path to its .desktop file, and Flex Launcher will run the Exec command that the developers have specified in the file. Desktop files are located in /usr/share/applications.

Desktop Actions

Some .desktop files contain “Actions”, which affect how the program is launched. An action may be specified by delimiting it from the path to the .desktop file with a semicolon. For example, Steam has a mode called “Big Picture Mode”, which provides an interface similar to a game console and is ideal for a living room PC. The action in the .desktop file is called “BigPicture”. A sample menu entry to launch Steam in Big Picture mode is shown below:

Entry1=Steam;/path/to/steamicon.png;/usr/share/applications/steam.desktop;BigPicture

Clock

Flex Launcher contains a clock widget, which displays the current time, and, optionally, the current date. The following settings may be used to control the behavior of the clock.

Enabled

Defines whether or not the clock is enabled. This setting is a boolean “true” or “false”.

Default: false

ShowDate

Defines whether or not the current date should be shown in addition to the current time. This setting is a boolean “true” or “false”.

Default: false

Alignment

Defines which side of the screen the clock text should align to. Possible values: “Left” and “Right”

Default: Left

Font

Defines the font to use for the clock text. The value should be the path to a TrueType (TTF) font file.

Default: SourceSansPro

FontSize

Defines the font size of the clock text

Default: 50

Margin

Defines the distance of the clock text from the top and side of the screen, in pixels or percent of the screen height.

Default: 5%

FontColor

Defines the color of the clock text.

Default: #FFFFFF (White)

Shadows

Defines whether shadows are enabled for the clock text. Shadows give a 3D textured appearance to the text to improve the contrast from the background. This setting is a boolean “true” or “false”.

Default: false

ShadowColor

Defines the color of the clock text shadows.

Default: #000000 (Black)

Opacity

Defines the opacity of the clock text. Must be a percent value.

Default: 100%

TimeFormat

Defines the format of the current time. Possible values: “24hr”, “12hr”, and “Auto”

Default: Auto

DateFormat

Defines the order of the month and day in the date. Possible values: “Little”, “Big”, “Auto”

IncludeWeekday

Defines whether the date format should include the abbreviated weekday in your system locale. This setting is a boolean “true” or “false”

Default: true

Screensaver

Flex Launcher contains a screensaver feature, which will dim the screen after the input has been idle for the specified amount of time. Here are the settings that control the behavior of the screensaver

Enabled

Defines whether or not the screensaver is enabled. This setting is a boolean “true” or “false”.

Default: false

IdleTime

Defines the amount of time in seconds that the input should be idle before activating the screensaver

Default: 300 (5 minutes)

Intensity

Defines the amount to dim the screen. Must be a percent value.

Default: 70%

PauseSlideshow

When BackgroundMode is set to “Slideshow”, this setting defines whether or not the slideshow should be paused while the screensaver is active. This setting is a boolean “true” or “false”.

Default: true

Hotkeys

Flex Launcher supports configurable hotkeys, which executes a command when a specified key is pressed. Each hotkey consists of a key=value pair, where the key is an arbitrary name, and the value contains the SDL keycode of the hotkey and the command to run when it is pressed, delimited by a semicolon:

Hotkey=keycode;command

The keycode is a HEX prefixed with the # character. There are two ways to find a keycode for a given key. The first is to use the lookup table provided by SDL. The name of each key is in the right column of the table, and the corresponding HEX keycode is in the center column. The second is to run Flex Launcher in debug mode, press the key, then check the log. For each keystroke, the name of the key will be printed and the HEX value will be in parenthesis next to it.

Any key can be set as a hotkey, except keys that are reserved for the default controls: the left and right arrow keys, enter/return, and backspace. Hotkeys may be used to “speed dial” your favorite applications, or to add controls via special commands. As an example configuration below, the first hotkey is mapped to F1 and will launch Kodi when it is pressed, and the second hotkey is mapped to F12 and will cause Flex Launcher to quit when it is pressed:

[Hotkeys]
Hotkey1=#4000003A;"C:\Program Shortcuts\kodi.lnk"
Hotkey2=#40000045;:quit

Exit Hotkey (Windows only)

The exit hotkey feature allows a user to quit the running application using a button on their remote. This is especially useful for applications that don’t have a quit button, such as a web browser operating in fullscreen mode.

Only the function keys F1-F24 may be used as an exit hotkey, with the exception of F12 which is forbidden by Windows. Pressing an exit hotkey is functionally equivalent to using the Alt+F4 keyboard shortcut on the active window; it is not a forceful method, so the application is able to close cleanly. However, the application could also choose to ignore it, display a confirmation dialog, or not respond if it’s hung.

The following example maps F10 as an exit hotkey:

Hotkey=#40000043;:exit

Linux users that desire similar functionality should check the documentation of their desktop environment and/or window manager. Most support global hotkeys that can be configured to close the active window.

Gamepad Controls

Flex Launcher has built-in support for gamepad controls through SDL. All settings for gamepads will be in a section titled Gamepad. Within the section, there are key=value pairs which define the gamepad settings and the commands to be run when a button or axis is pressed.

Settings

The following settings are available in the Gamepad section to define the behavior of gamepads

Enabled

Defines whether or not gamepad controls are enabled. This setting is a boolean “true” or “false”.

Default: false

DeviceIndex

Defines the device index of the gamepad in SDL. If this value is negative, any gamepad may be used to control the launcher.

Default: -1

ControllerMappingsFile

A path to a text file that contains 1 or more controller mappings to override the default. This is usually not necessary, but if you want to change the mapping for your controller, or there is no default mapping for your controller in SDL, it can be specified via this interface. A community database of mappings for many common controllers can be found here. Alternatively, you may create a custom mapping using a GUI tool such as the SDL2 Gamepad Tool.

Controls

The controls are defined in key=value pairs, where the key is the name of the axis or button that is pressed, and the value is the command that is to be run, which is typically a special command. An axis is an analog stick or a trigger. For analog sticks, negative (-) represents left for the x axis and up for the y axis, and postive (+) represents right for the x axis and down for the y axis.

The SDL GameController interface is an abstraction which conceptualizes a controller as having an Xbox-style layout. The mapping names in SDL are based on the location of the buttons on an Xbox controller, and may not correspond to the actual labelling of the buttons on your controller. For example, ButtonA is for the “bottom” button, ButtonB is for the “right” button of the 4 main control buttons. If you have a Playstation-style controller, those mapping names will correspond to the X button and the Circle button, respectively.

The default controls in Flex Launcher allow the user to move the highlight cursor left and right by using the left stick or the DPad, select an entry by pressing A, and go back to the previous menu by pressing B. These controls are simple and will suffice for the vast majority of use cases.

The following axis and buttons are available for control in Flex Launcher:

Transparent Backgrounds

Note for Linux users only: this feature requires compositor implementation. See the Linux Setup Guide for details.

Flex Launcher supports transparent backgrounds using the chroma key technique. This method works by setting a strategically chosen color to the background, which is removed later. In film production, this technique is often refered to as “blue screening” or “green screening”.

The chosen chroma key color should be one that is not found in your icons/text, as this would cause them to become transparent. The color is set with the ChromaKeyColor setting in the Background section. The default is #010101, a slight off-shade of black.

A limitation of this method is that your icons and text must be fully opqaue or fully transparent. Any semi-transparent pixels will blend with the chroma key background so that it does not produce a color match, and consequently will not be removed from the background.

Flex Launcher’s text rendering is anti-aliased, which gives the text a “feathered” look with semi-transparent pixels on the edges. Normally, this is desirable, but in the case of chroma keying, semi-transparent pixels will cause your chroma key background color to “bleed through” on the edges of the text. If bright blue or bright green is chosen as the chroma key, this will result in a blue or green glowing effect around the text, which is usually undesirable. This is the reason why a dark color is chosen as the default chroma key. The bleed though appears as a dark outline rather than as a bright glowing.

Some icons have shadows which are intended to provide a textured look. The shadows are usually semi-transparent, which will cause them to not render properly with the chroma key technique. You should choose icons without shadows, or manually erase the shadows from an icon if there are no other icons available for the given application. Some icons are also heavily anti-aliased, which can give a glowing or outline effect similar to the text rendering described above.

Another common issue is the highlight. The default highlight is semi-transparent, which will not render properly when blended with the chroma key background. There are a few ways to address with this:

Transparent backgrounds will require some effort to obtain a setup that looks good and works well. Be prepared to do a significant amount of tinkering if you wish to use this feature.

Windows Implenetation

The Windows implementation of transparency is not hardware accelerated. If your refresh rate is very high, this can result in a signficant load on the CPU. If you find that the trasparent background is causing a high load on your system, consider changing the VSync setting to false and setting FPSLimit to 30 or lower, which will reduce the amount of computation required.

Animated Backgrounds

Transparent backgrounds can be used to implement animated backgrounds in combination with another program. On Windows, Wallpaper Engine and Lively are popular choices. For Linux, I recommend anipaper; see the Linux Setup Guide for details.

Custom Widgets

Flex Launcher offers a simple clock widget which can show the current time and date. For more advanced functionality, you can combine a transparent background with a third party widget program. For example, you can have a widget that displays weather, news, etc. in addition to the time. Rainmeter is a popular option on Windows, and Conky for Linux.