This document attempts to be a best practices reference for general use screen development.
While it is possible to program just about anything to work with LinuxCNC, using a common frame work, language and configuration requirements allows easier transition between screens and more developers to maintain them.
That said, nothing in this document is written in stone.

1. Sprache

Python is currently the preferred language of LinuxCNC’s screen code.
Python has a low entry bar for new users to modify the screens to suit them.
Python has a rich array of documentation, tutorials and libraries to pull from.
It is already used and integrated into LinuxCNC’s system requirements.
While C or C++ could be used, it severely limits who can maintain and develop them.
It would be better to extend Python with C/C++ modules for whatever function that requires it.

2. Localization of float numbers in GUIs

Different locales use different decimal separators and thousands separators. Locale-specific string-to-float functions should be avoided as they may give unexpected results. (For example the text string "1.58" in de_DE will be converted to 158 by atof()). The following guidelines (based on avoiding ambiguity rather than on "correctness" in any specific locale) are suggested if parsing float to string and vice-versa:

  • In the case of input allow either comma (,) or point(.) as a decimal separator, but reject any input that has more than one of either. Space should be accepted but not required as a thousands separator.

  • In the case of display either use point (.) consistently or use the current localisation format consistently. The emphasis here being on "consistently".

3. Grundeinstellungen

Currently, most screens use a combination of INI file and preference file entries to configure their functions.
INI text files are usually used for the common machine controller settings, while text based preference files are used for more GUI related properties (such as sounds, size, colors).
There can be other files used for translations, stylizing and function customization. These are highly dependent on the underlying widget toolkit.

3.1. INI [DISPLAY]

Der Abschnitt [DISPLAY] der INI dient der Angabe von Bildschirmeinstellungen.

3.1.1. Anzeige (engl. display)

The most important of is specifying the name of the screen that the LinuxCNC script will use to load.
The screen program usually recognizes switches such as to set full screen.
Title is for the window title and icon is used for iconizing the window.

[DISPLAY]
DISPLAY = axis
TITLE = XYZA rotierende Achse
ICON = silver_dragon.png

3.1.2. Zykluszeit

Wenn einstellbar, so wird die Zykluszeit der Anzeige GUI eingestellt.
Dies ist oft die Updaterate eher als die sleep time (Dauer des Prozessor-Ruhe) zwischen Updates.
Ein Wert von 100 ms (0,1 s) ist eine übliche Einstellung, obwohl ein Bereich von 50 - 200 ms nicht aus dem Rahmen fiele.

[DISPLAY]
CYCLE_TIME = 100

3.1.3. Dateipfad

Wenn diese Funktionen im Bildschirm verfügbar sind, wird hier beschrieben, wie der zu verwendende Pfad angegeben wird.
Dabei sollte entweder von der aktuellen INI-Datei aus referenziert werden, oder das Zeichen „~“ (Tilde) für das Home-Verzeichnis bzw. absolute Pfade erlaubt sein.

MDI_HISTORY_FILE = mdi_history.txt
PREFERENCE_FILE_PATH = gui.pref
LOG_FILE = gui-log.txt

3.1.4. Jogging-Inkremente

Radiobuttons oder eine Kombibox werden in der Regel zur Inkrementauswahl verwendet.
Die linearen Inkremente können eine Mischung aus Zoll oder Millimetern sein.
Winkel werden in Grad angegeben.
Das Wort "kontinuierlich" wird verwendet, um ein kontinuierliches Joggen anzugeben und sollte wahrscheinlich hinzugefügt werden, auch wenn es aus der INI-Linie nicht angegeben wird.

INCREMENTS = continuous, 10 mm, 1.0 mm, 0.10 mm, 0.01 mm, 1.0 inch, 0.1 inch, 0.01 inch
ANGULAR_INCREMENTS = continuous, .5, 1, 45, 90, 360

3.1.5. Maschinen-Typ Hinweis (engl. hint)

The screen often needs to be adjusted based on machine type. Lathes have different controls and display DROs differently. Foam machine display the plot differently.
The old way to do this was adding switches LATHE = 1, FOAM = 1 etc

MACHINE_TYPE_HINT = LATHE

3.1.6. Neufestlegungen (engl. overrides)

Override (Übersteuerung) ermöglicht es dem Benutzer, Vorschub oder Spindeldrehzahl während des Betriebs anzupassen. In der Regel wird dafür ein Schieberegler oder Drehknopf verwendet.
Diese Einstellungen werden in Prozent angegeben.

MAX_FEED_OVERRIDE       = 120
MIN_SPINDLE_0_OVERRIDE    = 50
MAX_SPINDLE_0_OVERRIDE    = 120

3.1.7. Jogging-Rate

Die meisten Bildschirme verfügen über Schieberegler, um die lineare und die winkelbezogene Manuelles Verfahren (Jog)-Geschwindigkeit einzustellen.
Diese Einstellungen sollten in Maschineneinheiten pro Minute für lineare Bewegungen und in Grad pro Minute für Winkelbewegungen angegeben werden.
„Voreinstellung“ bezeichnet die Anfangsgeschwindigkeit, wenn der Bildschirm erstmals geladen wird.

DEFAULT_LINEAR_VELOCITY =
MIN_LINEAR_VELOCITY =
MAX_LINEAR_VELOCITY =

DEFAULT_ANGULAR_VELOCITY =
MIN_ANGULAR_VELOCITY =
MAX_ANGULAR_VELOCITY =

3.1.8. Spindel Handsteuerung

Manual controls for spindle control could be, (or a combinations of) buttons, sliders or dials
You can set limits that are less then the what the machine controller can utilize by setting these entries.
If your screen is capable of running multiple spindles, then should accept entries higher then the shown 0.

SPINDLE_INCREMENT = 100
DEFAULT_SPINDLE_0_SPEED = 500
MIN_SPINDLE_0_SPEED = 50
MAX_SPINDLE_0_SPEED = 1000

3.2. INI [MDI_COMMAND]

Einige Bildschirme verwenden Tasten, um Makro NGC-Befehle auszuführen.
Sie können wie in diesen kompakten Beispielen angegeben werden.
NGC-Befehle, die durch Doppelpunkte getrennt sind, werden vollständig ausgeführt, bevor der nächste startet.
Ein optionales Komma trennt den Text der Taste vom NGC-Code.

[MDI_COMMAND_LIST]
MDI_COMMAND_MACRO0 = G0 Z25;X0 Y0;Z0, Goto\nUser\nZero
MDI_COMMAND_MACRO1 = G53 G0 Z0;G53 G0 X0 Y0,Goto\nMachn\nZero

3.3. INI [FILTER]

This section allows setting of what files are shown in the file chooser and what filter programs will preprocess its output before sending it to LinuxCNC.
The extensions follow this pattern:
PROGRAM_EXTENSION = .extension,.extension2[space]Description of extensions
The filter program definitions are such:
filter extension = program to run

[FILTER]
# Controls what programs are shown in the file manager:
PROGRAM_EXTENSION = .ngc,.nc,.tap G-Code File (*.ngc,*.nc,*.tap)
PROGRAM_EXTENSION = .png,.gif,.jpg Greyscale Depth Image
PROGRAM_EXTENSION = .py Python Script

# Maps data/source code file extensions to a special 'filter' program for the display/execution:
png = image-to-gcode
gif = image-to-gcode
jpg = image-to-gcode
py = python3

3.4. INI [HAL]

Most screens will need some HAL pins. They need to be connected after the screen creates them.

3.4.1. Postgui Hal-Datei

Diese Dateien sollten eine nach der anderen in dieser Reihenfolge ausgeführt werden, nachdem alle GUI HAL Pins angelegt wurden.

[HAL]
POSTGUI_HALFILE = keypad_postgui.hal
POSTGUI_HALFILE = vfd_postgui.hal

3.4.2. Postgui Halcmd

Diese Dateien sollte nacheinander unter Bewahrung der Reienfolge ausgeführt werden, nachdem alle POSTGUI Dateien ausgeführt wurden.

[HAL]
POSTGUI_HALCMD = show pin qt
POSTGUI_HALCMD = loadusr halmeter

4. Erweiterte Konfiguration

4.1. GUI Elemente einbetten

Allowing users to build small panels independently, that can be embedded into the main screen is a common and very useful customization. Some screens allow embedding of 3rd party foreign programs, others only the native widget toolkit based panels.
Usually these are embedded in tabs or side panel widgets.
This is how to describe the optional title, loading command and location widget name:

EMBED_TAB_NAME=Vismach demo
EMBED_TAB_COMMAND=qtvcp vismach_mill_xyz
EMBED_TAB_LOCATION=tabWidget_utilities

4.2. Dialoge für Benutzermeldungen

Benutzerdialogs werden verwendet, um wichtige Informationen (in der Regel Fehler) anzuzeigen, die der Benutzer als relevant einstuft.
Einige bleiben sichtbar, bis das Problem behoben ist, andere erfordern eine Bestätigung, wieder andere eine Ja-/Nein-Auswahl.
Ein HAL-I/O-Pin kann den Dialog aufrufen; der Dialog setzt den I/O-Pin zurück und legt ggf. Ausgangspins für die Antwort fest.

[DISPLAY]
MESSAGE_BOLDTEXT = Dies ist eine rein informative Nachricht
MESSAGE_TEXT = Dies ist von geringer Priorität
MESSAGE_DETAILS = Drücke OK zum Löschen
MESSAGE_TYPE = okdialog status
MESSAGE_PINNAME = bothtest
MESSAGE_ICON = INFO

This style gives multiple messages defined by a number.
This example shows 3 possible messages based around a VFD error number.

[DISPLAY]
MULTIMESSAGE_ID = VFD

MULTIMESSAGE_VFD_NUMBER = 1
MULTIMESSAGE_VFD_TYPE = okdialog status
MULTIMESSAGE_VFD_TITLE = VFD Fehler: 1
MULTIMESSAGE_VFD_TEXT = Die ist der längere Text FÜR MESSAGE NUMMER 1
MULTIMESSAGE_VFD_DETAILS = DETAILS für VFD Fehler 1
MULTIMESSAGE_VFD_ICON = WARNING

MULTIMESSAGE_VFD_NUMBER = 2
MULTIMESSAGE_VFD_TYPE = nonedialog status
MULTIMESSAGE_VFD_TITLE = VFD Fehler: 2
MULTIMESSAGE_VFD_TEXT = Die sist der längere Text FÜR MESSAGE NUMMER 2
MULTIMESSAGE_VFD_DETAILS = DETAILS für VFD Fehler 2
MULTIMESSAGE_VFD_ICON = INFO

MULTIMESSAGE_VFD_NUMBER = 3
MULTIMESSAGE_VFD_TYPE = status
MULTIMESSAGE_VFD_TITLE = VFD Fehler: 3
MULTIMESSAGE_VFD_TEXT = Dies ist der längere Text FÜR Error MESSAGE NUMMER 3.
MULTIMESSAGE_VFD_DETAILS = Bei Erscheinen dieser Nachricht besteht Handlungsbedarf.
MULTIMESSAGE_VFD_ICON = WARNING