This is machine translation

Translated by Microsoft
Mouse over text to see original. Click the button below to return to the English verison of the page.


Conditionally open dialog box according to user preference


pref_value = uigetpref(group,pref,title,question,pref_choices)
[pref_value,dlgshown] = uigetpref(...)
[...] = uigetpref(... 'Name',value)


pref_value = uigetpref(group,pref,title,question,pref_choices) returns one of the items in pref_choices in either of two ways:

  • Displays a multiple-choice dialog box that prompts you to answer a question. The dialog box includes a check box with the label Do not show this dialog again.

  • Retrieves a previous answer from the preferences data base and returns it without displaying a dialog. No dialog is displayed if you previously selected the check box Do not show this dialog again.

[pref_value,dlgshown] = uigetpref(...) also returns in dlgshown whether or not the dialog displayed.

[...] = uigetpref(... 'Name',value) specify optional name-value pairs to control how dialogs display.

Input Arguments


Character vector specifying the name of the preference group that preference pref belongs to. If the group does not already exist, uigetpref creates it.

Default: None


Character vector specifying the name of the preference that controls whether the dialog displays. If the preference does not already exist, uigetpref creates it.

Default: None


Title to display in the dialog box title bar


Character vector, character array, or cell array of character vectors specifying a descriptive paragraph for the dialog to display. Use question to define what you are asking the user to decide. Clearly state the alternatives and the consequences of choosing among them. The dialog box contains line breaks between rows of the character array, between elements of the cell array of character vectors, and between '|' or newline characters within a character vector.

Default: None


Character vector, cell array of character vectors, or '|'-separated character vectors specifying the labels for the dialog box push buttons. The label on the selected push button is returned.

If the internal preference values are different from the labels displayed on the push buttons, provide a 2-by-n cell array of character vectors. The first row contains the preference names, and the second row contains the associated push button labels. When pref_choices is not a 2-by-n cell array, MATLAB® constructs lowercase versions of the button labels and returns them in pref_value.

Default: None

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.


State of check box when dialog box opens:

  • false or 0: Check box is not initially selected.

  • true or 1: Check box is initially selected.

Default: 0


Character vector specifying the label for the check box.

Default: 'Do not show this dialog again'


Character vector specifying the label for Help button.

Default: No Help button displays.


Character vector or function handle specifying the callback that executes when you click the Help button. Also, to have a button to trigger the callback, you must specify the HelpString option.

Default: doc('uigetpref')


Character vector or cell array of character vectors specifying labels for extra buttons. The additional buttons are not mapped to any preference settings. If you click any of these buttons, the dialog box closes and uigetpref returns the label text in value.

Default: {}


Character vector specifying the value that uigetpref returns if you close the dialog box without clicking a button. This value does not have to correspond to any preference or ExtraOption.

Default: The first button specified in pref_choices

Output Arguments


Character vector containing the preference corresponding to the button you press. If you cancel the dialog by clicking its close box, uigetpref returns the label of the first button specified in pref_choices or the value for DefaultButton, if specified. After you select the Do not show this dialog again check box, uigetpref does not display a dialog box when you call it with the same group and pref arguments. Instead, it returns the last choice you made (your registered preference) in pref_value immediately.


Logical value that indicates whether or not the dialog displayed. The value is 1 when the dialog displays. The value is 0 when the dialog does not display. If the user selects the Do not show this dialog again check box, then the dialog does not display the next time your code calls the uigetpref function with the same group and pref arguments.


Create a preference dialog for the 'savefigurebeforeclosing' preference in the 'mygraphics' group of preferences.

This function, save_figure_perhaps, displays a dialog that asks the user to save current figure. The function responds appropriately, depending on the value returned by uigetpref.

function save_figure_perhaps
% Closes figure conditionally, asking whether to save it first.
% User can suppress the dialog from UIGETPREF permanently by selecting
% "Do not show this dialog again".

fig = gcf;
[selectedButton dlgshown] = uigetpref(...
    'mygraphics',...                        % Group
    'savefigurebeforeclosing',...           % Preference
    'Closing Figure',...                    % Window title
    {'Do you want to save your figure before closing?'
     'You can save your figure manually by typing ''hgsave(gcf)'''},...
    {'always','never';'Yes','No'},...        % Values and button labels
     'ExtraOptions','Cancel',...             % Additional button
     'DefaultButton','Cancel',...            % Default choice
     'HelpString','Help',...                 % Label for Help button
     'HelpFcn','doc(''closereq'');');        % Callback for Help button
switch selectedButton
    case 'always'  % Open a Save dialog (without testing if saved before)
    [fileName,pathName,filterIndex] = uiputfile('fig', ...
                                  'Save current figure', ...
       if filterIndex == 0     % User cancelled save or named no file
       else                    % Use filename returned from UIPUTFILE
           saveas(fig,[pathName fileName])
   case 'never'                % Close the figure without saving it
   case 'cancel'               % Do not close the figure

To run this example, copy and paste the code into a new program file. Name the file save_figure_perhaps.m and save it on your search path. To use the function as a CloseRequestFcn callback, create a figure as follows:

Clicking the figure's close box displays the dialog box until you select Do not show this dialog again.

Related Examples

More About

collapse all


Preferences provide the ability to specify how applications behave and how users interact with them. For example, you can set a preference for which products display their documentation in the Help browser, or which messages the Code Analyzer displays. In MathWorks® software products, preferences persist across sessions and are stored in a preference data base, the location of which is system-dependent. Use the Preferences option on the File menu to access all built-in preferences.

uigetpref uses the same preference data base as addpref, getpref, ispref, rmpref, and setpref. However, uigetpref registers the preferences it sets as a separate list, so that it and uisetpref can manage those preferences.

To modify preferences registered with uigetpref, you can use setpref and uisetpref to explicitly change preference values to 'ask'. If you specify a preference that does not already exist in the preference data base, uigetpref creates it.


  • You must supply all input arguments up to and including pref_choices.

  • uigetpref creates specified groups and preferences, if they do not currently exist. To delete a preference group you no longer need, use rmpref.

  • The value returned in pref_value is a preference name (as specified in pref), not its button label (as specified in pref_choices).

  • After you select the check box Do not show this dialog again and close the dialog box, the dialog box does not display again for the same preference. To reenable dialogs that are being suppressed by preferences, use the command:

    Executing uisetpref with this command re-enables all preference dialogs you have defined with uigetpref, not just the most recent one.

Introduced before R2006a

Was this topic helpful?