inputUniversalDlg¶

utils.dlgs.inputUniversalDlg(ParentFigure, header, prompts, defAns, dlgTitle, options)¶

INPUTUNIVERSALDLG - Multi-widget input dialog built on uifigure + uigridlayout.

Supports text fields, numeric fields, spinners, dropdowns, checkboxes, placeholders, and HTML display widgets. Replaces mibInputMultiDlg.

Syntax:

[answer, selectedIndices, dontShowAgain] = ...
    inputUniversalDlg(ParentFigure, header, prompts, defAns, dlgTitle)
[answer, selectedIndices, dontShowAgain] = ...
    inputUniversalDlg(ParentFigure, header, prompts, defAns, dlgTitle, options)

Input Arguments:

ParentFigure - handle to the parent window (AppContainer, uifigure, or []); used to centre the dialog. Pass [] to use the cached handle from a prior call. In MIB controllers / model methods pass obj.mibModel.getProgressBarParent() (or obj.getProgressBarParent() inside MibModel) so the dialog follows the active dataset window when it is undocked.
header (optional) - [char] bold label shown above all widgets. Supersedes options.Header when non-empty.
prompts - {n x 1} cell array of prompt strings, one per widget row.
defAns - {n x 1} cell array of default values; supported types per element:
- '', 'text', or string scalar → text edit (uieditfield); when the text contains newline characters → multi-line text area (uitextarea) sized to one row per line
- numeric scalar or [] → numeric edit field (uieditfield)
- struct('Spinner',true,'Value',v,'Limits',[lo hi],'Step',s,'Round',tf) → spinner (uispinner)
- cell array of strings with a numeric last element (default index) → dropdown (uidropdown)
- true / false → checkbox (uicheckbox)
- NaN → placeholder row (prompt only, no widget)
- string starting with '<html>' → rich-text display (uihtml)
dlgTitle - [char|string] dialog window title.
options (optional) - struct with configuration fields:
- .Columns - [integer] number of widget columns (default: 1)
- .DefaultKey - [char] button triggered by Enter: 'OK' (default) or 'Cancel'
- .DoNotShowAgain - [logical] show “Do not show again” checkbox (default: false)
- .DoNotShowAgainText - [char] checkbox label (default: 'Do not show again')
- .Focus - [integer] 1-based index of widget to focus on open; 0 = focus the OK button (default: 0)
- .Header - [char] text above widgets; superseded by the header parameter
- .HeaderLines - [integer] number of lines reserved for the header
- .HelpBtnText - [char] Help button label (default: 'Help')
- .HelpUrl - URL, base-workspace command, or function handle taking no arguments; when provided, the Help button is shown. Use a handle such as @() utils.openHelpPage(localPage, onlineUrl) for a page that is also shipped with MIB - the web call used for a plain address opens file:/// links unreliably on Windows
- .Icon - [char] icon identifier (default: 'puffin_question'): 'puffin_question', 'puffin_warning', 'puffin_info', 'puffin_error', 'puffin_measure', 'puffin_waiting', 'question', 'celebrate', 'call4help', 'warning'
- .IconWidth - [numeric] icon column width in pixels (default: [], i.e. use the image’s natural width)
- .LabelPosition - [char] 'left' (default, label beside widget) or 'top' (label above widget)
- .LastItemColumns - [integer] 1 to force the last widget to span all columns, 0 otherwise (default: 0)
- .MainColumnWidths - cell array of main-grid column widths, e.g. {'1x', '2x'} for 2 columns (default: '1x' for all)
- .mibPath - [char] path to MIB installation
- .MsgBoxOnly - [logical] show as a message-box with a single OK button and one HTML content widget (default: false)
- .OkBtnText - [char] OK button label (default: 'OK')
- .ParentFigure - [handle] parent figure for centering (default: [])
- .SectionsColumnWidths - cell array of label/widget column proportions for each main column when LabelPosition='left'; e.g. {'1x','2x','1x','2x'} gives label:widget = 1x:2x for both columns (default: 'fit' for labels and '1x' for widgets)
- .WindowHeight - [numeric] dialog height in pixels (default: auto-calculated, min 200, max 800)
- .WindowStyle - [char] 'normal' (default) or 'modal'
- .WindowWidth - [numeric] dialog width in pixels (default: 450)

Output Arguments:

answer - {n x 1} cell array of entered values; [] when cancelled. Dropdowns return the selected string; numeric edits return double; spinners return double; checkboxes return logical.
selectedIndices - vector of selected indices for dropdowns; 1 for non-dropdown items; [] when cancelled.
dontShowAgain - [logical] state of the “Do not show again” checkbox (false when cancelled).

Example 1 - Horizontal layout (label on the left, 2 columns, all widget types)

prompts = {'Enter a text:'; 'Select an option'; 'Are you sure?'; ...
           'placeholder row'; 'Long prompt wrapping over two lines'; ...
           'Multi-line text (3 lines):'; 'Numeric value'; 'Iterations (spinner)'};
defAns  = {'my test string'; ...
           {'Option 1','Option 2','Option 3', 2}; ...  % dropdown, default index 2
           true; NaN; ''; ...                          % checkbox, placeholder, editfield
           sprintf('Line 1\nLine 2\nLine 3'); ...      % multi-line text
           3.14; ...                                    % numeric edit field
           struct('Spinner',true,'Value',5,'Limits',[1 100],'Step',1, ...
                  'Round',true,'ValueDisplayFormat','%d units')};
options.WindowStyle  = 'normal';
options.HeaderLines  = 2;
options.WindowWidth  = 672;
options.WindowHeight = 350;
options.Columns      = 2;
options.MainColumnWidths = {'1x', '2x'};
options.LabelPosition = 'left';
options.SectionsColumnWidths = {'1x', '2x', '1x', '3x'};
options.Focus        = 1;
options.HelpUrl      = 'http://mib.helsinki.fi';
options.LastItemColumns = 1;
options.Icon         = 'question_48px';
options.OkBtnText    = 'Proceed';
options.HelpBtnText  = 'Help';
options.DoNotShowAgain = true;
options.DefaultKey   = 'OK';
options.ParentFigure = obj.view.gui;
[answer, selIndex, dontShow] = utils.dlgs.inputUniversalDlg(obj.view.gui, ...
    'My test Input dialog', prompts, defAns, 'Test Dialog', options);
if isempty(answer); return; end

Example 2 - Vertical layout (label on top, 1 column)

prompts = {'Enter a text:'; 'Select an option'; 'Are you sure?'; 'Numeric value'};
defAns  = {'my test string'; {'Option 1','Option 2','Option 3', 2}; true; 3.14};
options.WindowStyle  = 'normal';
options.Header       = 'Vertical Layout Example';
options.WindowWidth  = 400;
options.LabelPosition = 'top';
options.Icon         = 'question_48px';
[answer, selIndex, dontShow] = utils.dlgs.inputUniversalDlg(obj.view.gui, ...
    '', prompts, defAns, 'Vertical layout dialog', options);
if isempty(answer); return; end

Example 3 - Warning message box (plain-text body, auto-wrapped to HTML)

dlgOpt.MsgBoxOnly  = true;
dlgOpt.Icon        = 'puffin_warning';
dlgOpt.HeaderLines = 1;
utils.dlgs.inputUniversalDlg(obj.mibModel.getProgressBarParent(), 'The models are switched off!', {''}, ...
    {'Please enable "Enable selection" in Preferences and try again.'}, ...
    'Models are disabled', dlgOpt);

Example 4 - Message box with rich HTML body

options.MsgBoxOnly         = true;
options.Icon               = 'puffin_info';
options.HeaderLines        = 1;
options.DoNotShowAgain     = true;
options.DoNotShowAgainText = 'Do not show this again';
htmlBody = ['<html><p style="font-size:10pt">This message has ' ...
            '<b>rich text</b> and a list:<ul><li>Item 1</li>' ...
            '<li>Item 2</li></ul></p></html>'];
[answer, selIndex, dontShow] = utils.dlgs.inputUniversalDlg(obj.mibModel.getProgressBarParent(), ...
    'Please Read', {''}, {htmlBody}, 'Information', options);

Example 5 - Minimalist warning with everything in the header

dlgOpt.MsgBoxOnly  = true;
dlgOpt.Icon        = 'puffin_warning';
dlgOpt.HeaderLines = 3;
utils.dlgs.inputUniversalDlg(obj.mibModel.getProgressBarParent(), ...
    sprintf('!!! Warning !!!\n\nThe output format was not selected!'), ...
    {}, {}, 'Warning', dlgOpt);