uigetpref (MATLAB Functions)

Display dialog box for retrieving preferences

Syntax

value = uigetpref(group,pref,title,question,pref_choices)

Description

value = uigetpref(group,pref,title,question,pref_choices) returns one of the strings in pref_choices, by doing one of the following:

Prompting the user with a multiple-choice question dialog box
Returning a previous answer stored in the preferences database

By default, the dialog box is shown, with each choice on a different pushbutton, and with a checkbox controlling whether the returned value should be stored in preferences and automatically reused in subsequent invocations.

If the user checks the checkbox before choosing one of the push buttons, the push button choice is stored in preferences and returned in value. Subsequent calls to uigetpref detect that the last choice was stored in preferences, and return that choice immediately without displaying the dialog.

If the user does not check the checkbox before choosing a pushbutton, the selected preference is not stored in preferences. Rather, a special value, 'ask', is stored, indicating that subsequent calls to uigetpref should display the dialog box.

Note uigetpref uses the same preference database as addpref, getpref, ispref, rmpref, and setpref. However, it registers the preferences it sets in a separate list so that it, and uisetpref, can distinguish those preferences that are being managed with uigetpref.

For preferences registered with uigetpref, you can use setpref and uisetpref to explicitly change preference values to 'ask'.

group and pref define the preference. If the preference does not already exist, uigetpref creates it.

title defines the string displayed in the dialog box titlebar.

question is a descriptive paragraph displayed in the dialog, specified as a string array or cell array of strings. This should contain the question the user is being asked, and should be detailed enough to give the user a clear understanding of their choice and its impact. uigetpref inserts line breaks between rows of the string array, between elements of the cell array of strings, or between '|' or newline characters in the string vector.

pref_choices is either a string, cell array of strings, or '|'-separated strings specifying the strings to be displayed on the push buttons. Each string element is displayed in a separate push button. The string on the selected pushbutton is returned.

Make pref_choices a 2-by-n cell array of strings if the internal preference values are different from the strings displayed on the pushbuttons. The first row contains the preference strings, and the second row contains the related pushbutton strings. Note that the preference values are returned in value, not the button labels.

[val,dlgshown] = uigetpref(...) returns whether or not the dialog was shown.

Additional arguments can be passed in as parameter-value pairs:

(...'CheckboxState',state) sets the initial state of the checkbox, either checked or unchecked. state can be either 0 (unchecked) or 1 (checked). By default it is 0.

(...'CheckboxString',cbstr) sets the string cbstr on the checkbox. By default it is 'Never show this dialog again'.

(...'HelpString',hstr) sets the string hstr on the help button. By default the string is empty and there is no help button.

(...'HelpFcn',hfcn) sets the callback that is executed when the help button is pressed. By default it is doc('uigetpref'). Note that if there is no 'HelpString' option, a button is not created.

(...'ExtraOptions',eo)creates extra buttons which are not mapped to any preference settings. eo can be a string or a cell array of strings. By default it is {} and no extra buttons are created. If the user chooses one of these buttons, the dialog is closed and the string is returned in value.

(...'DefaultButton',dbstr) sets the string value dbstr that is returned if the dialog is closed. By default, it is the first button. Note that dbstr does not have to correspond to a preference or ExtraOption.

Note If the preference does not already exist in the preference database, uigetpref creates it. Preference values are persistent and maintain their values between MATLAB sessions. Where they are stored is system dependent.

Examples

This example creates the following preference dialog for the 'savefigurebeforeclosing' preference in the 'mygraphics' group.

It uses the cell array {'always','never';'Yes','No'} to define the preference values as 'always' and 'never', and their corresponding button labels as 'Yes' and 'No'.

[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

See Also

addpref, getpref, ispref, rmpref, setpref, uisetpref

uigetfile uiimport