uigetpref

Create dialog box that opens according to user preference

collapse all in page

Syntax

pval = uigetpref(group,pref,title,quest,pbtns)
[pval,tf] = uigetpref(group,pref,title,quest,pbtns)
[___] = uigetpref(___,Name,Value)

Description

pval = uigetpref(group,pref,title,quest,pbtns)creates a nonmodal dialog box that opens with the specified group name and preference name. The group and preference names, in combination, uniquely identify the dialog box. The dialog box contains:

  • The specified question (quest) and one or more buttons (pbtns) that enable the dialog box user to answer the question. The clicked button value is returned as pval.

  • A check box that, by default, is labeled Do not show this dialog again.

If the user selects the check box, MATLAB® stores and returns the value of the clicked button as the preference value (pval). Subsequent calls to uigetpref for the same dialog box, detect that the preference value was stored and apply that choice without opening the dialog box.

If the user does not select the check box, then MATLAB returns, but does not store the value of the clicked button. Instead, MATLAB stores the value 'ask'. MATLAB opens the specified dialog box on subsequent calls to uigetpref.

example

[pval,tf] = uigetpref(group,pref,title,quest,pbtns) returns a logical value that indicates whether the dialog box opened. If the dialog box opened, then the value of tf is 1 (true). Otherwise, the value of tf is 0 (false).

example

[___] = uigetpref(___,Name,Value) specifies one or more optional name-value pairs that enable you to do any of the following.

  • Customize the check box label.

  • Specify whether the check box is selected when the dialog box opens.

  • Provide a help button and the help button callback.

  • Specify buttons that are not mapped to preference values.

  • Specify the value that uigetpref returns for pval if the user closes the dialog box without clicking a preference button. For example, this value is returned if the user clicks the dialog box close button (X), presses the keyboard Esc key, or clicks a button that is not mapped to a preference value.

Use this option with any of the output argument combinations in the previous syntaxes.

Examples

collapse all

Define each of the required uigetpref input arguments, and then pass them to uigetpref.

group = 'Updates';
pref =  'Conversion';
title = 'Converting';
quest = {'Are you sure you want to convert this code?',...
         'Conversions cannot be undone.'};
pbtns = {'Yes','No'};

[pval,tf] = uigetpref(group,pref,title,quest,pbtns)

Click Yes. The MATLAB Command Window shows that the value of pval is 'yes' and that value of tf is 1, indicating that the dialog box was displayed.

Run the uigetpref command again, but this time select Do not show this dialog again, and then click No.

[pval,tf] = uigetpref(group,pref,title,quest,pbtns)

The MATLAB Command Window shows that the value of pval is 'no' and that value of tf is 1.

Run the uigetpref command again.

[pval,tf] = uigetpref(group,pref,title,quest,pbtns)

As expected, the dialog box does not display. The MATLAB Command Window shows that the value of pval is 'no' and that value of tf is 0.

Reenable the dialog box display by setting the preference value to 'ask'.

setpref('Updates','Conversion','ask');

Run the uigetpref command again. The dialog box opens.

[pval,tf] = uigetpref(group,pref,title,quest,pbtns)

Specify 'ExtraOptions','Cancel' as a name-value pair to add a Cancel button to the dialog box. If the user clicks Cancel, MATLAB returns the button label to pval.

group = 'Updates';
pref =  'Conversion';
title = 'Converting';
quest = {'Are you sure you want to convert this code?',...
         'Conversions cannot be undone.'};
pbtns = {'Yes','No'};
[pval] = uigetpref(group,pref,title,quest,pbtns,...
'ExtraOptions','Cancel');

Create a function that creates a preferences dialog box. The dialog box asks the user about saving the figure before closing it. Based on the value of the button that the user clicks, the function opens a Save dialog box or closes the figure without saving it.

function savefigconditionally
fig = gcf;

group ='mygraphics';
pref = 'savefigbeforeclosing';
title = 'Closing Figure';
quest = {'Do you want to save your figure before closing?'
         ''
         'If you do not save the figure, all changes will be lost'};
pbtns = {'Yes','No'};
[pval,tf] = uigetpref(group,pref,title,quest,pbtns);

switch pval
    case 'yes'  
    [file,path,indx] = uiputfile('fig', ...
                                  'Save current figure', ...
                                  'untitled.fig');
       if indx == 0    
           delete(fig);
       else                   
           saveas(fig,[path,file])
           delete(fig);
       end
   case 'no'               
       delete(fig);
       return
 end

To run this example, copy and paste the code into a new program file. Name the file savefigconditionally.m and save it on your search path. To use the function as a CloseRequestFcn callback, create a figure and optionally plot some data.

figure('CloseRequestFcn','savefigconditionally');
x = [1 2 3 4 5];
y = [10 50 25 75 25];
plot(x,y);
Each time you run the preceding block of commands and click the close button (X) in the figure title bar, the dialog box opens unless you select Do not show this dialog again.

Input Arguments

collapse all

Preference group name, specified as a character vector or string scalar. The group includes the preference specified by the pref input argument. If the group does not exist, MATLAB creates it.

Example: 'My Graphics'

Preference name, specified as a character vector or string scalar.

This preference stores the value of the button within the specified pbtns that the user clicks. If the preference name does not exist, then MATLAB creates it.

Example: 'Save Graphic'

Dialog box title, specified as a character vector or string scalar.

Example: 'Save preference'

Dialog box question, specified as a character vector, a cell array of character vectors, or a string array. Line breaks occur within the question text as follows:

  • If the question is specified as a character vector, then line breaks occur after a vertical bar (|) character or a newline character specified with the newline function.

  • If the question is specified as a cell array of character vectors, then line breaks occur after each cell array element.

Example: {'Are you sure you want to convert this code?', 'Conversions cannot be undone.'}

Example: 'Do you want to save this file before closing?'

Preference button labels, specified as a character vector, a cell array of character vectors, a vertical bar-delimited character vector, or a string array.

If you want to specify internal preference values that are different from the button labels, then specify the pbtns value as a 2-by-n cell array or string array. The first row contains the preference names and the second row contains the associated button labels. For example, consider using this approach if you plan to localize your dialog box for various languages. You can specify the button labels using a foreign language without having to change your code logic (for instance, switch and case statements) for each localization.

When pbtns is not a 2-by-n cell array, MATLAB stores the label name as the preference value.

Example: 'Yes'

Example: {'Yes','No'}

Example: ['Yes|No']

Example: {'Oui','Non';'yes','no'} sets the button labels to 'Oui' and 'Non' and their corresponding preference values to 'yes' and 'no'.

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 quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: line(x,y,'Color','red','LineWidth',3) creates a red line that is 3 points wide.Example: 'CheckboxSting','Do not ask again.'

Initial state of check box when the dialog box opens, specified as the comma-separated pair consisting of 'CheckboxState' and 1,0, true, or false.

  • The check box is selected when the value is true or 1

  • The check box is not selected when the value is false or 0.

Example: 'CheckboxState',0

Check box label, specified as the comma-separated pair consisting of 'CheckboxString' and a character vector or string scalar.

Help button label, specified as the comma-separated pair consisting of 'Help' and a character vector or a string scalar. If you do not specify this name-value pair, no help button is displayed in the dialog box. If you specify this name-value pair, but do not specify the HelpFcn name-value pair, then MATLAB uses 'HelpFcn','doc(uigetpref)' by default.

Example: 'HelpString','Info'

Help button callback, specified as the comma-separated pair consisting of 'HelpFcn' and a function handle, string array, or character vector (not recommended). The callback executes when a user clicks the help button. When you specify this name-value pair, you also must specify the 'HelpString' name-value pair.

See also, Write Callbacks for Apps Created Programmatically

Example: 'HelpFcn',@myfunc specifies the HelpFcn callback function as a function handle.

Labels for extra buttons, specified as the comma separated pair consisting of 'ExtraOptions' and a character vector, cell array of character vectors, or a string array. The additional buttons are not mapped to any preferences. If a user clicks any of these buttons, the dialog box closes and returns the button label as the output argument pval.

Example: 'ExtraOptions','Cancel'

Default button selection, specified as the comma separated pair consisting of 'DefaultButton' and a character vector or string scalar. The default button selection is returned to p if a user closes the dialog box without clicking any button. This value does not have to correspond to any preference button or an ExtraOption button.

Example: 'nobtn'

Output Arguments

collapse all

Selected preference button returned as a string scalar. The returned value is one of the following:

  • Label of the clicked preference button (pbtns)

  • Internal value of the clicked preference button

True or false result, returned as 1 or 0. The function returns 1 (true) if the dialog box opened. Otherwise, it returns 0. This value corresponds to the check box selection stored the last time the dialog box was open and the user selected the check box (which is labeled 'Do not show this dialog again' by default).

More About

collapse all

Nonmodal Dialog Box

A nonmodal dialog box enables a user to interact with other MATLAB windows before responding to the dialog box. A nonmodal dialog box is also referred to as a normal dialog box.

Preferences

Preferences enable you to specify how applications behave and how users interact with them. Preferences persist across sessions and are stored in a preference data base.

The uigetpref function uses the same preference data base as MATLAB built-in products. 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, use uisetpref or setpref. For example, use setpref to change a preference value to 'ask'.

Tips

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

  • To get a structure of previously created groups and preferences, use the getpref function.

  • After a user selects the check box Do not show this dialog again and closes the dialog box, the dialog box does not open again for the same group and preference. To reenable dialog boxes that are being suppressed set the preference value to 'ask' using setpref.

  • Users of your dialog box do not know the group and preference names you specified when creating the dialog box. Therefore, to reenable dialog boxes that are being suppressed by preferences, users can call the uisetpref command.

    uisetpref('clearall')
    Executing uisetpref as shown reenables all preference dialog boxes defined with uigetpref, not just the most recent one.

See Also

| | | | |

Introduced before R2006a

MATLAB Documentation

Support