waitforbuttonpress

Wait for click or key press

Syntax

w = waitforbuttonpress

Description

Note

Using uiwait and specifying a WindowButtonDownFcn or WindowKeyPressFcn callback that calls uiresume is recommended over 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

Create Axes After Button Press

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

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.

Version History

Introduced before R2006a

R2014b: waitforbuttonpress is Figure-specific

To resume program execution after the waitforbuttonpress function is called, a click or key press must occur in the current figure, and not just any figure. This change in behavior was introduced in order to prevent program execution from proceeding in an unintended figure. Prior to R2014b, waitforbuttonpress would detect a click or key press event in any open figure. The execution stream would then resume in the figure in which the event was detected.