Documentation Center

  • Trial Software
  • Product Updates

uigetpref

Specify and conditionally open dialog box according to user preference

Syntax

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

Description

pref_value = uigetpref(group,pref,title,question,pref_choices) returns one of the strings 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

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

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.

More About

expand all

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

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.

See Also

| | | | | |

Tutorials

Was this topic helpful?