Main Content

waitforbuttonpress

Wait for click or key press

Description

example

Note

In App Designer and apps created using the uifigure function, using uiwait and specifying a WindowButtonDownFcn or WindowKeyPressFcn callback that calls uiresume is recommended as opposed to using waitforbuttonpress because it provides more control over the app behavior. For more information, see Alternative Functionality.

w = waitforbuttonpress blocks statements from executing until the user has clicked a mouse button or pressed a key in the current figure.

The return argument, w, can have the following values:

  • 0 if it detects a click

  • 1 if it detects a key press

The waitforbuttonpress function does not return a value when any of the following keys are pressed by themselves or together: Ctrl, Shift, Alt, Caps Lock, Num Lock, or Scroll Lock.

Examples

collapse all

Create a figure and call the waitforbuttonpress function. Then, create axes and note that they do not appear.

figure;
w = waitforbuttonpress;
axes;

Click the figure. Now, waitforbuttonpress returns, execution continues, and the axes appear.

Tips

  • To determine the last key pressed, the mouse selection type, or the location of the mouse pointer within the current figure, query the Figure properties CurrentCharacter, SelectionType, and CurrentPoint, respectively.

Algorithms

Some important points to consider when using waitforbuttonpress:

  • If a WindowButtonDownFcn is defined for the figure, it executes before waitforbuttonpress returns a value.

  • The waitforbuttonpress function errors if the user closes the figure by clicking the window close button unless your code calls the waitforbuttonpress function within a try/catch block.

Alternative Functionality

In App Designer and in apps created using the uifigure function, use uiwait to block statements from executing. To resume program execution when the app user clicks a mouse button or presses a key, specify a WindowButtonDownFcn or WindowKeyPressFcn callback that calls uiresume.

For example, this code creates a UI figure that resumes program execution when a user clicks in the figure window.

fig = uifigure('WindowButtonDownFcn',@(src,event)uiresume(src));

Call uiwait to block program execution until uiresume is called or the figure is deleted. Create a UIAxes object and parent it to the figure. The set of axes does not appear.

uiwait(fig);
ax = uiaxes(fig);

Then, click the figure. The program execution resumes and the UIAxes object appears.

Compatibility Considerations

expand all

Behavior changed in R2014b

Introduced before R2006a