MATLAB Examples

Contents

Numeric Edit Box

This class provides a numeric editbox uicontrol.

Requirements

  • MATLAB R2014b or newer is required to run this file.
% Sean de Wolski

Background

The typical MATLAB uicontrol edit box allows for any string to be input by the user. Often times, we want numeric values only and have to safe guard against this in the edit box callback like this:

function editbox_callback(src,evt) if isnan(str2double(src.Value)) warning('Not a string') src.Value = 1 end

This class saves the effort of checking this and provides a few additional features as well.

In addition to all of the standard edit uicontrol properties, there are four additional ones:

  • Value: The numeric value of the edit box.
  • RoundFractionalValues: If true, the numericEditbox only accepts integers and rounds to the nearest valid integer.
  • Limits: [Minimum Maximum] These are the inclusive valid limits for the value.
  • ValueChangedFcn: Fired only when a valid new value is entered.

There is also a ValueChanged event that can be listened for when an acceptable input changes the 'Value'.

Example 1

This example makes a numeric editbox that only accepts valid uint8 values.

% Small figure
figure('Units','inches','Position',[5 5 3 2])

% Use all properties
numericEditbox('Value', 100, 'RoundFractionalValues', true, ...
    'Limits', [0 255], 'Units','normalized','Position',[0.2 0.2 0.5 0.1]);

Example 2

This example implements a ValueChangedFcn that fires when the 'Value' changes. The change can occur from a user interaction or code interaction.

% Small figure
figure('Units','inches','Position',[5 5 3 2])

% Set ValueChangedFcn
h = numericEditbox('Value',pi,'Units','normalized',...
    'Position',[0.1 0.1 0.3 0.1],'ValueChangedFcn',@(src,evt)disp(src.Value));

Value doesn't change

disp('I don''t cause a fire!')
h.Value = pi;
drawnow
I don't cause a fire!

Value does change

disp('I do')
h.Value = exp(1);
I do
    2.7183

Example 3

This example demonstrates the behavior when non-acceptable values are entered programatically. See Example 4 for behavior when they are entered by a user.

The general thought process behind this decision is that the developer should make sure bad values can't be set and should not allow the object into an unknown state. A user has no knowledge of this and can only do what is allowed.

% Small figure
figure('Units','inches','Position',[5 5 3 2])

% Build editbox
h = numericEditbox('Value',pi,'Units','pixels','Position',[50 50 150 20]);
h.ForegroundColor = 'b';
disp('Value')
disp(h.Value)
Value
    3.1416

Example 3a

String

try
    disp('Invalid String')
    h.Value = 'hello';
catch ME
    fprintf('\n%s\n',ME.message);
end
Invalid String

Expected Value to be one of these types:

double, single, uint8, uint16, uint32, uint64, int8, int16, int32, int64

Instead its type was char.

Example 3b

Limits

h.Limits = [0 100];
try
    disp('Value exceeds upper limit')
    h.Value = 122;
catch ME
    disp(['Value is still ' h.String])
    fprintf('\n%s\n',ME.message);
end
Value exceeds upper limit
Value is still 3.1416

Expected Value to be a scalar with value <= 100.

Example 3c

Constrained to integer values.

h.RoundFractionalValues = 1;
disp('RoundFractionalValues')
try
    h.Value = pi;
catch ME
    fprintf('\n%s\n',ME.message);
end
disp(h.Value)
RoundFractionalValues

Expected Value to be integer-valued.
     3

Example 4

The behavior is different when a user enters an invalid input.

  • Rather than erroring, a warning is thrown if the input is non-numeric.
  • If the input is non-integer with an integer input, then it is rounded.
  • If the input exceeds the limits, it is saturated to the limit it violates.

Experiment on your own with the following example:

% Small figure
figure('Units','inches','Position',[5 5 3 2])

% Use all properties
numericEditbox('Value', 100, 'RoundFractionalValues', true, ...
    'Limits', [0 255], 'Units','normalized','Position',[0.2 0.2 0.5 0.1]);
  1. Type in a value of 3.5
  2. Type in '4a'
  3. Type in -10

Feedback

Please send all good, bad or ugly feedback to me directly.

firstname.deWolski@whereIwork.com

Developer Note:

If you are interested in extending this class or making it backward compatible to releases less than R2014b, I have unit tests that can be provided to help you. It should not be too difficult to extend it backward as the only things that require R2014b are dot notation for property set/get and groot instead of 0 for the root object.