inputSingleDlg

utils.dlgs.inputSingleDlg(ParentFigure, prompt, defAns, dlgTitle, options)

INPUTSINGLEDLG - Single-input dialog for one text (uieditfield) or numeric (uispinner) value.

Uses direct focus() for immediate keyboard focus - no java.awt.Robot dependency. The dialog blocks the caller via uiwait() until accepted or cancelled.

Keyboard shortcuts:

  • Enter - accept (equivalent to clicking OK)

  • Escape - cancel (equivalent to clicking Cancel)

Syntax:
answer = inputSingleDlg(ParentFigure, prompt, defAns, dlgTitle)
answer = inputSingleDlg(ParentFigure, prompt, defAns, dlgTitle, options)
Input Arguments:

  • ParentFigure - handle to the parent window (AppContainer, uifigure, or []); used to centre the dialog. Pass [] to reuse the cached handle from a prior call. In MIB pass obj.mibModel.getProgressBarParent() so the dialog follows the active dataset window when it is undocked.

  • prompt - [char|string] prompt text displayed above the input field. Supports newlines, e.g. sprintf('Line 1\nLine 2').

  • defAns - default value for the input widget:

    • For editfield (default): [char|string] default text.

    • For spinner: struct with the following fields:

      • .Value - [numeric] initial value (default: 0)

      • .Limits - [min max] spinner range (default: [-Inf Inf])

      • .Step - [numeric] increment/decrement step (default: 1)

      • .Round - [logical] round fractional values (default: true)

      • .ValueDisplayFormat - [char] format string, e.g. '%.0f' (default: '%.d')

  • dlgTitle - [char|string] dialog window title.

  • options (optional) - struct with configuration fields:

    • .mibPath - [char] path to MIB installation for icon resolution (default: auto-detected via which('mib3'))

    • .Type - [char] input widget type (default: 'editfield'):

      • 'editfield' - text input

      • 'spinner' - numeric spinner (auto-set when defAns is a struct)

    • .WindowWidth - [numeric] dialog width in pixels (default: 400)

    • .WindowHeight - [numeric] dialog height in pixels (default: 112)

    • .WindowStyle - [char] 'normal' (default) or 'modal'

    • .Icon - [char] icon identifier (default: 'puffin_question'):

      • 'puffin_question', 'puffin_warning', 'puffin_error', 'puffin_measure', 'puffin_info', 'puffin_waiting' - puffin icons (96 px)

      • 'question_48px', 'warning_48px' - standard icons (48 px)

      • 'celebrate', 'call4help' - special icons

    • .IconWidth - [numeric] icon column width in pixels (default: 96 for puffin icons, 48 for standard icons)

    • .ParentFigure - [handle] alternative parent for centering (overrides the ParentFigure parameter)

Output Arguments:

  • answer - entered value; [] when cancelled: - [char] for editfield mode - [double] for spinner mode

Usage:

Example 1 - Basic editfield: add new material name

answer = utils.dlgs.inputSingleDlg(obj.view.gui, ...
    'Please enter a name for the new material:', ...
    sprintf('m%.3d', 5), 'Add material');
if isempty(answer); return; end

Example 2 - Editfield with all options specified

options.Type = 'editfield';
options.WindowWidth = 400;
options.WindowHeight = 100;
options.WindowStyle = 'modal';
options.Icon = 'question_48px';
options.IconWidth = 48;
options.mibPath = obj.mibModel.mibPath;
answer = utils.dlgs.inputSingleDlg(obj.view.gui, ...
    'Enter file name:', 'myfile.txt', 'File Name', options);
if isempty(answer); return; end

Example 3 - Spinner with full struct configuration

options.Type = 'spinner';
options.WindowWidth = 400;
options.WindowHeight = 100;
options.WindowStyle = 'modal';
options.Icon = 'question_48px';
options.IconWidth = 48;
options.mibPath = obj.mibModel.mibPath;
defAns = struct('Value', 10, 'Limits', [1 100], 'Step', 1, ...
    'Round', false, 'ValueDisplayFormat', '%.3f units');
answer = utils.dlgs.inputSingleDlg(obj.view.gui, ...
    'Enter iteration count:', defAns, 'Iterations', options);
if isempty(answer); return; end

Example 4 - Minimalistic spinner with multiline prompt

options.Type = 'spinner';
options.WindowWidth = 320;
defAns = struct('Value', 5, 'Limits', [1 Inf], 'Step', 1, ...
    'Round', true, 'ValueDisplayFormat', '%d units');
answer = utils.dlgs.inputSingleDlg(obj.view.gui, ...
    sprintf('Please enter number of colors\n(max. value is %d)', 255), ...
    defAns, 'Define number of colors', options);
if isempty(answer); return; end

Example 5 - No parent figure (standalone call)

answer = utils.dlgs.inputSingleDlg([], 'Enter value:', 'hello', 'Test');
if isempty(answer); return; end

Example 6 - Editfield with puffin warning icon

options.Icon = 'puffin_warning';
options.WindowWidth = 450;
options.WindowHeight = 130;
options.mibPath = obj.mibModel.mibPath;
answer = utils.dlgs.inputSingleDlg(obj.view.gui, ...
    'Enter new filename:', 'myfile.tif', 'Rename File', options);
if isempty(answer); return; end