Main Content

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.

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

example

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)

Preferences dialog box with custom title and body text. The dialog box also has a check box with the text "Do not show this dialog again." and two buttons, "Yes" and "No".

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)

Preferences dialog box. The check box is selected, and the mouse cursor is over the "No" button.

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)

Preferences dialog box

Specify the "ExtraOptions" name-value argument as "Cancel" 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");

Preferences dialog box with custom title and body text. The dialog box also has a check box with the text "Do not show this dialog again." and three buttons, "Yes", "No", and "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
 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 execute the function when a figure closes, specify is as the figure CloseRequestFcn callback. For example, create a figure and 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.

Preferences dialog box with custom title and body text. The dialog box also has a check box with the text "Do not show this dialog again." and two buttons, "Yes" and "No".

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 string scalar, string array, character vector, or cell array of character vectors. Line breaks occur within the question text as follows:

  • If the question is specified as a string scalar or 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 string array or a cell array of character vectors, then line breaks occur after each 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 string scalar, string array, character vector, or cell array of character vectors.

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 array, MATLAB stores the lowercase label name as the preference value.

Example: "Yes"

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 Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: uigetpref(group,pref,title,quest,pbtns,"CheckboxState",1) creates a preference dialog box with the check box initially selected.

Example: "Do not ask again."

uigetpref(group,pref,title,quest,pbtns,CheckboxState=1) creates a preference dialog box with the check box initially selected.

Initial state of check box when the dialog box opens, specified as 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.

Check box label, specified as a string scalar or character vector.

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

Example: "Info"

Help button callback, specified as a function handle, string scalar, or character vector (not recommended). The callback executes when a user clicks the Help button. When you specify this name-value argument, you also must specify the HelpString name-value argument.

For more information about callbacks, see Create Callbacks for Apps Created Programmatically

Labels for extra buttons, specified as a string scalar, string array, character vector, or cell array of character vectors. 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: "Cancel"

Default button selection, specified as a string scalar or character vector. The default button selection is returned to pval 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 character vector. The returned value is one of the following:

  • Label of the clicked preference button

  • 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 (false). This value corresponds to whether the Do not show this dialog again check box was selected the last time the dialog box was open.

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 the specified groups and preferences if they do not currently exist. To delete a preference group you no longer need, use the rmpref function.

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

  • After a user selects the Do not show this dialog again check box 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 the setpref function.

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

Version History

Introduced before R2006a

See Also

| | | | |