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.

Tips

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 string 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:
```
uisetpref('clearall')
```
Executing uisetpref with this command re-enables all preference dialogs you have defined with uigetpref, not just the most recent one.

Input Arguments

`group`	String specifying the name of the preference group that preference `pref` belongs to. If the group does not already exist, `uigetpref` creates it. Default: None
`pref`	String 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`	String to display in the dialog box title bar
`question`	String or cell array of strings 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 that `uigetpref` generates inserts line breaks between rows of the string array, between elements of the cell array of strings, and between '\|' or newline characters within a string vector. Default: None
`pref_choices`	String, cell array of strings, or `'\|'`-separated strings specifying the labels for the dialog box push buttons. The string on the selected push button is returned. If the internal preference values are different from the strings displayed on the push buttons, provide a 2-by-n cell array of strings. The first row contains the preference strings, and the second row contains the associated push button strings. 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`. If your code tests returned values, make sure it compares them against the appropriate strings. Default: None

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments, where 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.

`'CheckboxState'`	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`
`'CheckboxString'`	String specifying the label for the check box. Default: `'Do not show this dialog again'`
`'HelpString'`	String specifying the label for Help button. Default: No Help button displays.
`'HelpFcn'`	String 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')`
`'ExtraOptions'`	String or cell array of strings specifying extra buttons. The additional buttons are not mapped to any preference settings. If you click any of these buttons, the dialog closes and `uigetpref` returns the string in `value`. Default: `{}`
`'DefaultButton'`	String specifying the value that `uigetpref` returns if you close the dialog without clicking a button. This string does not have to correspond to any preference or `ExtraOption`. Default: The first button specified in `pref_choices`

Output Arguments

pref_value

String 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.

dlgshown

Logical value that specifies the state of the check box when the dialog box closed. The value is 1 if selected, 0 if not selected. 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 0 in dlgshown immediately.

Definitions

Preferences

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.

Examples

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

Call uigetpref to display the dialog (or not) from a figure window CloseRequestFcn callback. The callback code takes action via a switch statement. The action (to delete or not to delete the figure) depends on whether the answer returned by uigetpref was 'always' or 'never':

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 strings
     'ExtraOptions','Cancel',...             % Additional button
     'DefaultButton','Cancel',...            % Default choice
     'HelpString','Help',...                 % String 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', ...
                                  'untitled.fig');
       if filterIndex == 0     % User cancelled save or named no file
           delete(fig);
       else                    % Use filename returned from UIPUTFILE
           saveas(fig,[pathName fileName])
           delete(fig);
       end
   case 'never'                % Close the figure without saving it
       delete(fig);
   case 'cancel'               % Do not close the figure
       return
 end

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

figure('CloseRequestFcn','save_figure_perhaps');

Clicking the figure close box or selecting File > Close displays the dialog box until you select Do not show this dialog again.

Tutorials

Free MATLAB Interactive Kit

Explore how to use MATLAB to make advancements in engineering and science.

Download free kit

Trials Available

Try the latest version of MATLAB and other MathWorks products.

Get trial software

uigetpref - Specify and conditionally open dialog box according to user preference

Syntax

Description