How to Create Graphical User Interfaces Using the GUI Module Controls in Nelson

Use Nelson's built-in msgbox, warndlg, questdlg, uigetfile, and related functions to display Qt-backed modal dialogs and file pickers, combining them with uicontrol objects from the graphics module for fully interactive applications.

The nelson-lang/nelson repository provides a dedicated gui module that enables you to create graphical user interfaces using the gui module controls through a thin, Qt-based wrapper. This module offers ready-made dialog boxes and helper functions that work seamlessly across Linux, macOS, and Windows without platform-specific modifications. When you launch a Nelson GUI session via nelson-gui, the module loads automatically via modules/gui/etc/startup.m, which registers the native built-ins with the Nelson::GuiGateway.

Architecture of the GUI Module

The gui module follows a layered architecture that bridges Nelson's interpreter with Qt's native widgets. When you call a function like msgbox, the interpreter looks up the name in the gateway (GuiGateway), dispatches to the corresponding C++ routine (e.g., Nelson::GuiGateway::msgboxBuiltin), and returns a handle to the Nelson environment.

The registration layer in modules/gui/builtin/cpp/Gateway.cpp (line 38) maps high-level MATLAB-style calls to their C++ implementations. Each dialog function is a small wrapper around Qt classes such as QMessageBox, QFileDialog, and QInputDialog. For example, msgboxBuiltin.cpp handles argument parsing, icon selection, modality, and window management before displaying the native dialog.

Thin M-language wrappers provide convenience syntax for common variants. Files like modules/gui/functions/warndlg.m, errordlg.m, and helpdlg.m are one-line scripts that forward arguments to msgbox with preset icons, reducing code duplication while maintaining consistent behavior.

Core Dialog Functions

The gui module provides several high-level functions for user interaction. Each returns a handle or value that you can capture for further processing.

• msgbox – Displays an informational dialog with optional custom title and modality. Signature: h = msgbox(message [, title] [, mode]). Implemented in modules/gui/builtin/cpp/msgboxBuiltin.cpp (lines 20-80).

• warndlg – Shows a warning dialog with the 'warn' icon. Signature: h = warndlg(message [, title] [, mode]). Defined as a wrapper in modules/gui/functions/warndlg.m.

• errordlg – Displays an error dialog with the 'error' icon. Signature: h = errordlg(message [, title] [, mode]). Source: modules/gui/functions/errordlg.m.

• helpdlg – Creates a help-style dialog with the 'help' icon. Signature: h = helpdlg(message [, title] [, mode]). Source: modules/gui/functions/helpdlg.m.

• questdlg – Presents a modal question with customizable buttons and returns the user's choice. Signature: choice = questdlg(question [, title] [, btn1, btn2, btn3]). Core implementation in modules/gui/builtin/cpp/questdlgBuiltin.cpp.

• uigetfile – Opens a native file picker for selecting files. Signature: [filename, path] = uigetfile(filter, title). Implementation: modules/gui/builtin/cpp/uigetfileBuiltin.cpp.

• uigetdir – Opens a directory selection dialog. Signature: dir = uigetdir(startPath, title). Implementation: modules/gui/builtin/cpp/uigetdirBuiltin.cpp.

Practical Code Examples

All examples assume you are running inside a Nelson GUI session (nelson-gui). Save each script with a .nls extension and execute with run('filename.nls').

Basic Message and Warning Dialogs

This script demonstrates simple informational, warning, and error notifications:

// demo_dialogs.nls
msgbox('Welcome to Nelson!', 'Nelson Demo');
warndlg('This is a warning, proceed with care.', 'Warning');
errordlg('An unexpected error occurred.', 'Error');

Interactive Question Dialogs with Push Buttons

Combine gui module dialogs with graphics module uicontrol objects to build interactive applications:

// demo_button_question.nls
function onButtonPress(~, ~)
    answer = questdlg('Do you want to close the figure?', ...
                      'Close request', 'Yes', 'No', 'No');
    if strcmp(answer, 'Yes')
        close(gcf());
    end
end

% Create a figure with a button
f = figure('Name', 'Nelson GUI demo', 'Position', [200 200 300 150]);
b = uicontrol('Parent', f, ...
              'Style',  'pushbutton', ...
              'String', 'Close?', ...
              'Position', [80 50 140 40], ...
              'Callback', @onButtonPress);

Clicking the button triggers the questdlg, and the figure closes only if the user selects Yes.

File and Directory Selection

Use uigetfile and uigetdir to request user input for file system operations:

// demo_filepicker.nls
[filename, pathname] = uigetfile('*.m', 'Select a Nelson script');
if ~isequal(filename, 0)
    msgbox(['You chose: ', fullfile(pathname, filename)], 'File selected');
else
    warndlg('No file was selected.', 'Cancelled');
end

Integration with Graphics Controls

While the gui module handles modal dialogs and file pickers, interactive controls such as push-buttons, sliders, and text boxes are provided by the graphics module via uicontrol. You create graphical user interfaces using the gui module controls alongside these uicontrol objects to build complex workflows—such as launching a msgbox from a button callback or confirming file operations before execution.

The CMake build rules in modules/gui/CMakeLists.txt link the GUI built-ins against Qt libraries, ensuring that uicontrol figures and gui dialogs share the same event loop and appear native on all supported platforms.

Summary

• The gui module in nelson-lang/nelson provides Qt-backed dialog functions including msgbox, warndlg, errordlg, helpdlg, questdlg, uigetfile, and uigetdir.
• Function registration occurs at startup via modules/gui/etc/startup.m and modules/gui/builtin/cpp/Gateway.cpp.
• C++ implementations in msgboxBuiltin.cpp, questdlgBuiltin.cpp, and related files wrap native Qt widgets for cross-platform compatibility.
• M-language wrappers in warndlg.m, errordlg.m, and helpdlg.m provide convenient icon presets.
• Combine gui dialogs with uicontrol objects from the graphics module to create complete interactive applications.

Frequently Asked Questions

What is the difference between the gui and graphics modules in Nelson?

The gui module provides high-level modal dialogs and file pickers (message boxes, question dialogs, file browsers), while the graphics module supplies low-level UI controls like push-buttons, sliders, and axes via uicontrol and figure objects. According to the nelson-lang/nelson source code, you typically use the gui module for alerts and file selection, and the graphics module for building the underlying interface layout.

How do I display a modal error dialog in Nelson?

Call errordlg('Your error message', 'Dialog Title') to display a blocking error dialog with the standard error icon. The function is implemented as a thin wrapper in modules/gui/functions/errordlg.m that forwards to msgbox with the icon preset to 'error', ensuring consistent styling across all dialog types.

Can I use Nelson GUI functions in headless or CLI mode?

No. The gui module requires a Qt event loop and is only available when running nelson-gui. If you attempt to call msgbox or uigetfile from a headless nelson CLI session, the functions will fail because the GuiGateway registrations and Qt dependencies are not initialized in non-GUI interpreter modes.

Where are the C++ implementations of GUI dialogs located?

The core C++ implementations reside in modules/gui/builtin/cpp/. For example, msgboxBuiltin.cpp contains the QMessageBox wrapper, questdlgBuiltin.cpp handles question dialogs with custom buttons, and uigetfileBuiltin.cpp implements the file picker using QFileDialog. These files link against Qt via the build rules defined in modules/gui/CMakeLists.txt.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}