Documentation

dialog

Create empty modal dialog box

The dialog function creates an empty modal dialog box, which is a figure window with properties set to make the window look and behave like a dialog box.

Syntax

  • d = dialog
  • d = dialog(Name,Value) example

Description

d = dialog creates an empty dialog box and returns d, a figure object. Use the uicontrol function to add user interface controls to a dialog.

example

d = dialog(Name,Value) specifies one or more figure property names and corresponding values. Use this syntax to override the default properties.

Examples

collapse all

Dialog Containing Text and a Button

Use the uicontrol function to add user interface controls to a dialog box. For instance, create a program file called mydialog.m that displays a dialog containing text and a button.

function mydialog
    d = dialog('Position',[300 300 250 150],'Name','My Dialog');

    txt = uicontrol('Parent',d,...
               'Style','text',...
               'Position',[20 80 210 40],...
               'String','Click the close button when you''re done.');

    btn = uicontrol('Parent',d,...
               'Position',[85 20 70 25],...
               'String','Close',...
               'Callback','delete(gcf)');
end

Next, run the mydialog function from the Command Window.

mydialog

Dialog That Returns Output

Use the uiwait function to return output based on user selections in the dialog box. For instance, create a program file called choosedialog.m to perform these tasks:

  • Call the dialog function to create dialog with a specific size, location, and the title, "Select One".

  • Call the uicontrol function three times to add text, a pop-up menu, and a button, respectively.

  • Define the function, popup_callback, to serve as the callback function for the button.

  • Call the uiwait function to wait for the user to close the dialog before returning the output to the command line.

function choice = choosedialog

    d = dialog('Position',[300 300 250 150],'Name','Select One');
    txt = uicontrol('Parent',d,...
           'Style','text',...
           'Position',[20 80 210 40],...
           'String','Select a color');
       
    popup = uicontrol('Parent',d,...
           'Style','popup',...
           'Position',[75 70 100 25],...
           'String',{'Red';'Green';'Blue'},...
           'Callback',@popup_callback);
       
    btn = uicontrol('Parent',d,...
           'Position',[89 20 70 25],...
           'String','Close',...
           'Callback','delete(gcf)');
       
    choice = 'Red';
       
    % Wait for d to close before running to completion
    uiwait(d);
   
       function popup_callback(popup,callbackdata)
          idx = popup.Value;
          popup_items = popup.String;
          choice = char(popup_items(idx,:));
       end
end

Run the choosedialog function from the Command Window. Then, select a color in the dialog.

color = choosedialog

choosedialog returns the last selected color when you close the dialog.

color =

Blue

    Note:   The uiwait function blocks the MATLAB® thread. Although uiwait works well in a simple modal dialog, it not recommended for use in more sophisticated applications.

Input Arguments

collapse all

Name-Value Pair Arguments

Example: 'WindowStyle','normal' sets the WindowStyle property to 'normal'.

The properties listed here are only a subset. For a complete list, see Figure Properties.

'Position' — Location and size of window[left bottom width height]

Location and size of window, specified as the vector, [left bottom width height]. This table describes the values in the Position vector. All values are in units specified by the Units property.

ElementDescription
leftDistance from the left edge of the primary display to the inner left edge of the window. This value can be negative on systems that have more than one monitor.
bottomDistance from the bottom edge of the primary display to the inner bottom edge of the window. This value can be negative on systems that have more than one monitor.
widthDistance between the right and left inner edges of the window.
heightDistance between the top and bottom inner edges of the window.

    Note:  

    • You cannot specify the Position property when the window is docked.

    • To place the full window, including the title bar, menu bar, tool bars, and outer edges, use the OuterPosition property.

    • On Windows® systems, figure windows cannot be less than 104 pixels wide, regardless of the value of the Position property.

Example: [230 250 570 510]

Data Types: double

'ButtonDownFcn' — Button-press callback functionfunction handle | cell array | string

Button-press callback function, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

By default, MATLAB sets this command string to be the ButtonDownFcn callback for all dialogs. This command string makes the dialog box close when the user clicks the window.

'if isempty(allchild(gcbf)), close(gcbf), end'

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

'WindowStyle' — Window behavior'modal' (default) | 'normal' | 'docked'

Window behavior, specified as one of the following:

  • 'modal' — The window appears on top of all existing windows, making them inaccessible as long as the top window exists and remains modal. However, nothing prevents the display of subsequent windows after the modal window appears.

  • 'normal' — The window is independent of other windows, and the other windows are accessible while the current window exists.

  • 'docked' — The window appears in the desktop or a document window.

Output Arguments

collapse all

d — Dialog windowfigure object

Dialog window, returned as a figure object with these properties values set.

PropertyValue
ButtonDownFcn'if isempty(allchild(gcbf)), close(gcbf), end'
Colormap[]
DockControls'off'
HandleVisibility'callback'
IntegerHandle'off'
InvertHardcopy'off'
MenuBar'none'
Number[]
NumberTitle'off'
PaperPositionMode'auto'
Resize'off'
WindowStyle'modal'

Introduced before R2006a

Was this topic helpful?