Graphics

Protecting Figures and Axes

There are situations in which it is important to prevent particular figures or axes from becoming the target for graphics output (i.e., preventing them from becoming the gcf or gca). An example is a figure containing the uicontrols that implement a user interface.

You can prevent MATLAB from drawing into a particular figure or axes by removing its handle from the list of handles that are visible to the newplot function, as well as any other functions that either return or implicitly reference handles (i.e., gca, gcf, gco, cla, clf, close, and findobj). Two properties control handle hiding: HandleVisibility and ShowHiddenHandles.

HandleVisibility Property

HandleVisibility is a property of all objects. It controls the scope of handle visibility within three different ranges. Property values can be:

• on -- The object's handle is available to any function executed on the MATLAB command line or from an M-file. This is the default setting.
• callback -- The object's handle is hidden from all functions executing on the command line, even if it is on the top of the screen stacking order. However, during callback routine execution (MATLAB statements or functions that execute in response to user action), the handle is visible to all functions, such as gca, gcf, gco, findobj, and newplot. This setting enables callback routines to take advantage of the MATLAB handle access functions, while ensuring that users typing at the command line do not inadvertently disturb a protected object.
• off -- The object's handle is hidden from all functions executing on the command line and in callback routines. This setting is useful when you want to protect objects from possibly damaging user commands.

For example, if a GUI accepts user input in the form of text strings, which are then evaluated (using the eval function) from within the callback routine, a string such as 'close all' could destroy the GUI. To protect against this situation, you can temporarily set HandleVisibility to off on key objects.

• user_input = get(editbox_handle,'String');
  set(gui_handles,'HandleVisibility','off')
  eval(user_input)
  set(gui_handles,'HandleVisibility','commandline')
  

Values Returned by gca and gcf.   When a protected figure is topmost on the screen, but has nonprotected figures stacked beneath it, gcf returns the topmost unprotected figure in the stack. The same is true for gca. If no unprotected figures or axes exist, calling gcf or gca causes MATLAB to create one in order to return its handle.

Accessing Protected Objects

The root ShowHiddenHandles property enables and disables handle visibility control. By default, ShowHiddenHandles is off, which means MATLAB obeys the setting of the HandleVisibility property. When set to on, all handles are visible from the command line and within callback routines. This can be useful when you want access to all graphics objects that exist at a given time, including the handles of axes text labels, which are normally hidden.

The close function also allows access to nonvisible figures using the hidden option. For example,

• close('hidden') 
  

closes the topmost figure on the screen, even if it is protected. Combining all and hidden options,

• close('all','hidden')
  

closes all figures.

Testing for Hold State

The Close Request Function