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

> Learn to build interactive applications with Nelson's GUI module. Easily create graphical user interfaces using msgbox, warndlg, questdlg, uigetfile, and uicontrol.

- Repository: [The Nelson Programming Language/nelson](https://github.com/nelson-lang/nelson)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/nelson-lang/nelson/blob/main/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`](https://github.com/nelson-lang/nelson/blob/main/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`](https://github.com/nelson-lang/nelson/blob/main/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`](https://github.com/nelson-lang/nelson/blob/main/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`](https://github.com/nelson-lang/nelson/blob/main/modules/gui/builtin/cpp/uigetfileBuiltin.cpp).

- **`uigetdir`** – Opens a directory selection dialog. Signature: `dir = uigetdir(startPath, title)`. Implementation: [`modules/gui/builtin/cpp/uigetdirBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/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:

```nls
// 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:

```nls
// 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:

```nls
// 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`](https://github.com/nelson-lang/nelson/blob/main/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`](https://github.com/nelson-lang/nelson/blob/main/modules/gui/builtin/cpp/Gateway.cpp).
- C++ implementations in [`msgboxBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/msgboxBuiltin.cpp), [`questdlgBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/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`](https://github.com/nelson-lang/nelson/blob/main/msgboxBuiltin.cpp) contains the `QMessageBox` wrapper, [`questdlgBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/questdlgBuiltin.cpp) handles question dialogs with custom buttons, and [`uigetfileBuiltin.cpp`](https://github.com/nelson-lang/nelson/blob/main/uigetfileBuiltin.cpp) implements the file picker using `QFileDialog`. These files link against Qt via the build rules defined in [`modules/gui/CMakeLists.txt`](https://github.com/nelson-lang/nelson/blob/main/modules/gui/CMakeLists.txt).