en fr

Sysquake Pro – Table of Contents

Sysquake – Table of Contents

Sysquake for LaTeX – Table of Contents

Sysquake Graphical Functions

Functions

button

Button control.

Syntax

button(label, b, 'checkmark', style, id)
button(label, n, 'radiobutton', style, id)

Description

button(label,b,'checkmark',style,id) displays one or several checkmark controls. Checkmark controls are graphical elements whose state can be set on or off individually. The label argument contains several fields separated by tabulator characters (\t); the first field is displayed aligned to the left, and each subsequent field is displayed to the right of a checkmark button. The number of tabulators fixes the number of checkmarks. Each bit of the b argument corresponds to the state of one checkmark; the least significant bit corresponds to the leftmost checkmark. The style argument, if present and not empty, is a string which specifies the color(s) of the controls, and the id argument is the object id (cf. their description above).

Several rows of controls can be displayed by a single button command. Labels of each row are separated by newline characters (\n), and the state b becomes a column vector.

button(label,n,'radiobutton',style,id) displays one or several radio buttons. Radio buttons are similar to checkmarks, but are mutually exclusive. Their state is given by the n argument, which is the number of the active radio button on that row. If n is smaller than 1 or larger than the number of radio buttons, none is displayed as active.

You can display one or several rows of buttons in a single subplot. You can mix them with text and sliders (commands text and slider), but not with other graphics.

With plotoption math, label fields can contain MathML or LaTeX.

Usually, figure which contain buttons are associated with a mousedrag handler. The new state is provided in _x1 and corresponds to the value of the second argument of button.

Examples

A single checkmark button:

settabs('Style:XX\t');
button('Style:\tbold', isBold, 'checkmark', '', 1);

Two rows of checkmark buttons:

settabs('Style:XX\t\bboldXXX\t');
button(['Style:\tbold\titalic\n',...
        'Border:\ttop\tbottom\tleft\tright'], ...
          [isBold+2*isItalic; borders], 'checkmark', '', 1);

Mutually-exclusive radio buttons on three lines:

settabs('Radio:XX\t\b1XX\t');
button('Radio:\t1\t2\t3\n\t4\t5\t6\n\t7\t8\t9', ...
          [x;x-3;x-6], 'radiobutton', '', 1);

See also

settabs, pushbutton, popupmenu, slider, textfield, text, plotoption

clf

Clear the figure window.

Syntax

clf

Description

clf erases all the subplots, sets only one plot, and resets its scale. It can only be used from the command-line interface (directly or in a function), not in SQ files where figures are erased automatically before being updated.

If graphical commands are issued at the command line interface without clf, but after an SQ file has been loaded, their behavior is undefined.

drawnow

Immediate drawing of the plots.

Syntax

drawnow
drawnow(id)

Description

drawnow makes Sysquake immediately draws the result of graphical commands which were executed before. It should be used only from the command-line interface, or in functions called from the command line interface. Graphics generated for interactive subplots are buffered to provide optimal performances. drawnow may be useful for basic animations or for benchmarking Sysquake.

Without input argument, drawnow draws the contents of the current figure. An input argument can be used to specify the figure window identifier.

Example

tic;for i=1:100;clf;step(1,1:4);drawnow;end;toc
  2.2212

See also

clf

currentfigure

Get or set current figure window.

Syntax

id = currentfigure
currentfigure(id)

Description

Without input argument, currentfigure gets the identifier of the current figure window.

With an input argument, currentfigure(id) sets the figure window whose identifier is id as the current figure window. Contrary to figure, it does not bring it to the front.

currentfigure is not implemented in versions of Sysquake without support for multiple figure windows.

See also

figure

defaultstyle

Default figure style.

Syntax

defaultstyle(name, style)
style = defaultstyle(name)

Description

defaultstyle sets or gets the default style of figures. It has the same arguments as figurestyle. Default style settings are used in new figures, unless they are overridden by figurestyle.

See also

figurestyle

figure

Create or switch figure window.

Syntax

id = figure
figure(id)

Description

Without input argument, figure creates a new figure window which becomes the current figure window, i.e. the default target of graphical commands not in the context of SQ file draw handlers. It returns an integer number used as an identifier.

With an input argument, figure(id) sets the figure window whose identifier is id as the current figure window and brings it to the front.

figure is not implemented in versions of Sysquake without support for multiple figure windows.

Example

id1 = figure;
plot(rand(10));
id2 = figure;
fplot(@sin, [-5, 5]);
figure(id1);
plot(rand(10), 'r');

See also

currentfigure, figuretitle

figuretitle

Set the title of current figure window.

Syntax

figuretitle(str)

Description

Command figuretitle(str) sets the title of the current figure window to string str.

figuretitle is not implemented in versions of Sysquake without support for multiple figure windows.

See also

figure

popupmenu

Pop-up menu.

Syntax

popupmenu(label, entries, selection)
popupmenu(label, entries, selection, style)
popupmenu(label, entries, selection, style, id)

Description

popupmenu(label,entries,selection) displays a pop-up menu. Pop-up menu are simple menus which permits to select an entry among several alternatives. Their normal appearance displays the selected entry in a rectangular shape similar to a push button. When clicked, a menu is displayed at the same location, and the user can move the mouse with the button held down, select another entry, and release the mouse button.

Argument label contains a string which is displayed on the left. Argument entries contains the entries as a list of strings. Argument selected is the current selection, as an integer between 1 and the number of entries. The style argument, if present and not empty, is a string which specifies the color of the buttons, and the id argument is the object id (cf. their description above).

With plotoption math, label can contain MathML or LaTeX.

Usually, figures which contain pop-up menus and buttons are associated with a mousedrag handler only. Clicking a pop-up menu calls the mousedrag handler once, when the mouse button is released. The button is identified with _id; the index of the new selected entry is contained in _x1.

Example

A simple menu:

popupmenu('Color:', {'Red', 'Blue', 'Green'}, 1, '', 1);

The corresponding mousedrag handler:

function colorMenuHandler(_id, _x1)
  switch _id
    case 1
      fprintf('New color index: %d\n', _x1);
    otherwise
      cancel;
  end

See also

settabs, button, pushbutton, slider, textfield, text, plotoption

pushbutton

Push button control.

Syntax

pushbutton(label, style, id)

Description

pushbutton(label,style,id) displays one or several push buttons. Push buttons are simple buttons which triggers an action when they are pushed and released. They do not maintain any state, unlike checkmarks and radio buttons created with button. The label argument contains several fields separated by tabulator characters (\t); the first field is displayed aligned to the left, and each subsequent field is displayed as a separate rectangular button. The number of tabulators fixes the number of buttons. The style argument, if present and not empty, is a string which specifies the color(s) of the buttons, and the id argument is the object id (cf. their description above).

You can display one or several rows of buttons in a single subplot. You can mix them with text, other kinds of buttons and sliders, but not with other graphics.

Usually, figures which contain buttons are associated with a mousedrag handler only. Clicking a button calls the mousedrag handler once, when the mouse button is released. The button is identified with _id and _ix; no value can be retrieved.

Examples

A single button aligned to the left (a tabulator is placed to the left with settabs):

settabs('\t');
pushbutton('\tCalculate', '', 1);

Two buttons on the same row, green and red:

settabs(10);
pushbutton('Motion:\tStart\tStop', 'gr', 1);

The corresponding mousedrag handler:

function motionButtonHandler(_ix)
  switch _ix
    case 1
      fprintf('Start\n');
    case 2
      fprintf('Stop\n');
    otherwise
      cancel;
  end

See also

settabs, button, popupmenu, slider, textfield, text

redraw

Force the display of new graphics.

Syntax

redraw

Description

redraw forces Sysquake to immediately update the display of all subplots. It can only be used from the command-line interface (directly or in a function). It is useful to update the graphics of an SQ script after the variables have been changed manually from the command-line interface, or for SQ files and SQ scripts whose graphics may change at each evaluation because of random data or data imported from the outside.

scalesync

Set scale synchronization between subplots.

Syntax

scalesync(s)
scalesync(s, a)

Description

scalesync(a) sets scale synchronization between the subplots whose indices are given in array a. Subplot are numbered from the top-left one, row by row, starting from 1. When subplots have their scale synchronized, zooming or dragging one of the subplots is applied to all the members of the group.

With two arguments, scalesync(s,a) synchronizes subplots along the specified axes: X axis if a is 'x', Y axis if a is 'y', or both X and Y axes if a is 'xy'.

scalesync is typically used in the init handler after a call to subplots.

In subplots where a scale overview rectangle has been defined with scaleoverview, it is the scale area which is synchronized and not the figure itself, as a source when the user drags or resizes the area or as a target when the user zooms or drags the subplot it is synchronized with.

Examples

Synchronize the frequency scale of the magnitude and phase subplots:

subplots('Step\tBode Magnitude\nNyquist\tBode Phase');
scalesync([2, 4], 'x');

SQ file illustrating scale overview:

init subplots('Simple Plot\tScale Overview')
init scalesync([1, 2])

figure "Simple Plot"
	draw plotSinc(false)

figure "Scale Overview"
	draw plotSinc(true)

functions
{@

function plotSinc(isOverview)
	if isOverview
		scaleoverview([-1, 4, -0.25, 0.2]);
	else
		scale([-1, 4, -0.25, 0.2]);
	end
	fplot(@sinc, [-10, 10]);
@}

See also

subplots, subplotsync, scaleoverview

settabs

Set the vertical alignment of text, buttons and sliders.

Syntax

settabs(str)
settabs(vec)

Description

settabs sets tabulator marks which are used by the commands text, slider, and button which follow. Its argument is either a string of runs of characters separated by the tabulator character (\t), or a vector of one or more integers representing the number of 'x' characters in runs. Each run is measured and correspond to the width of a column of text, sliders, and buttons. The argument of settabs is not displayed. It should typically match the widest string, plus some margin, to avoid overlapping columns. Right after a tabulator character, the backspace character (\b) represents the width of a checkmark or radio button. The trailing tabulator may be omitted.

If more columns are required by text, slider, or button than what is defined by settabs, the last column width is replicated.

Examples

Alignment of text:

settabs('Results:xx\t999.99 \t');
text(sprintf('Results:\t%.2f\t%.2f', 2.435, 5.243));
text(sprintf('Log:\t%.2f\t%.2f', log(2.435), log(5.243)));

Alignment of radio buttons:

settabs('Choice:XXX\t\boneXX\t');
button('Choice:\tone\ttwo\tthree', 2, 'radiobutton', '', 1);

Two ways to set one large column followed by multiple small columns:

settabs('xxxxxxxxxx\txxxxx\t');
settabs([10,5]);

See also

text, button, popupmenu, slider, textfield

slider

Slider control for interactive manipulation of a scalar.

Syntax

slider(label, x, [min,max])
slider(label, x, [min,max], scale)
slider(label, x, [min,max], scale, style)
slider(label, x, [min,max], scale, style, id)

Description

The two main ways to manipulate variables in Sysquake consist in moving an element of a figure or in entering new values in a dialog box. The command slider provides an additional mean. It displays a set of sliders in a subplot, i.e. user-interface objects with a cursor you can drag to change continuously a scalar value. Like for any other user manipulation in a subplot, the other subplots are updated continuously if a mousedrag handler is provided.

You can display one or several sliders in a single subplot, and multiple thumbs (control element) per slider. You can mix them with text and buttons (commands text and button), but not with other graphics.

The label argument is a string which contains the labels for each slider, separated by a linefeed character (\n). Its width can be set with the settabs command. Argument x is the current value of the slider. It has one row per slider, and one column per thumb per slider. The rows of the third argument, an array of two columns, contain the minimum and maximum values corresponding to each slider when they are dragged to the left or right, respectively; it can be a 1-by-2 vector if the minimum and maximum values are the same for all the sliders. Argument scale is a string made of characters '-' for a linear scale, and 'l' or 'L' for a logarithmic scale; each character corresponds to a slider. If the string is empty, all sliders are linear; if the string contains one character, it applies to all sliders.

The style argument has its usual meaning; but only the color is used. Each color corresponds to a thumb. The corresponding thumbs of each slider have the same color. The scale argument may be omitted if the style is a structure or a named argument.

With plotoption math, label fields can contain MathML or LaTeX.

Sliders are either read-only if the id argument is missing, or interactive if it is provided. In the mousedown, mousedrag, and mouseup handlers, each slider is identified by _nb and each thumb by _ix. The _x, _x0, and _x1 parameters can be used to obtain the value corresponding to the position of the click in the slider, the initial value, and the current value. Note that contrary to other plot commands where _x is always defined, _x is non-empty only if the click is made inside a slider; this is so because the scale can be different for each slider.

During a mouse drag, the range of the manipulated slider is locked by Sysquake, even if you change it in the draw handler. Thus, you can specify a range relative to the current value:

slider('x', x, [x-5, x+5], '', '', 1)

Examples

Two sliders are displayed. The first one, for variable weight, is linear and has a fixed range between 0 and 1; the second slider, for variable alpha, has a logarithmic scale and a dynamic range between 20 % and 500 %.

variable weight, alpha
figure "Sliders"
  draw drawSliders(weight, alpha)
  mousedrag (weight, alpha) = dragSliders(weight, alpha, _nb, _x1)
functions
{@
  function drawSliders(w1, w2)
    slider('Weight (0-1):\nAlpha:', ...
           [w1; w2], [0,1; w2*[0.2,5]], ...
           '-L', 'kr', 1);
  function (w1, w2) = dragSliders(w1, w2, nb, x1)
    if isempty(nb)
      cancel;
    end
    switch nb
      case 1
        w1 = x1;
      case 2
        w2 = x1;
    end
@}

A slider with two thumbs, blue and red. An empty placeholder argument is used for the scale so that the style string is interpreted correctly.

slider('Values', [2, 3], [0, 10], '', 'br', 1);

The same slider with a structure array for the colors and a named argument for the id:

slider('Values', [2, 3], [0, 10], {Color='blue'; Color='red'}, id=1);

Four sliders in two rows, where the layout is set in the first argument (labels separated by \t correspond to sliders in the same row). The same limits, defined in a row vector, are used for the four sliders.

settabs([5,20,5,20]);
slider('A\tB\nC\tD', [2;5;3;9], [0,10], id=5);

See also

settabs, textfield, button, pushbutton, popupmenu, text, plotoption

subplot

Manage subplots.

Syntax

subplot(m, n, i)
subplot(mni)
subplot mni

Description

The subplot function specifies the layout of subplots and where the graphical output produced by the commands which follow will be displayed. It can be used from the command-line interface (directly or indirectly in functions) or in SQ scripts. SQ files rely on a different mechanism, where each subplot is defined with a different draw handler and may be displayed on demand.

subplot(m,n,i), subplot(mni) with a three-digits number, or subplot mni all set an m-by-n grid layout and select the i:th subplot, with i between 1 for the top-left subplot and m*n for the bottom-right subplot. subplot should be executed before each subplot with the same values of m and n.

Example

Four subplots in a 2-by-2 layout:

subplot 221
title('Top-left');
step(1,[1,2,3,4]);
subplot 222
title('Top-right');
plot(rand(10));
subplot 223
title('Bottom-left');
scale equal
nyquist(1,1:4);
subplot 224
title('Last one');
contour(randn(10));

See also

subplots, title

subplotparam

Get or restore the parameter of subplots.

Syntax

subplotparam({p1, p2, ...})
p = subplotparam

Description

The subplotparam function handles the parameter of each subplot. The subplot parameter is the value of _param, which is specific to each subplot and can contain any kind of data.

subplotparam({p1,p2,...}) sets the parameter of each subplot. Each element corresponds to a subplot.

Without input argument, subplotparam returns the list of parameters of all subplots.

subplotparam complements subplots, subplotprops, and subplotpos by getting or restoring the subplots set by the user. It is typically used in the input and output handlers. It may also be used in the init, menu or key handlers. For restoring the settings, it must be placed after subplots.

See also

subplots, subplotprops, subplotpos, scale

subplotpos

Get or restore the position of subplots.

Syntax

subplotpos([left1,right1,top1,bottom1;...])
P = subplotpos

Description

The subplotpos function handles the position of subplots in Free Position mode, which can be enabled in the View menu.

subplotpos(P) sets the position of each subplot in the Figure window. Unit is typically 4 pixels, equal to the grid used to snap figures when you move or resize them with the mouse; the origin is at the top left corner of the window. subplotpos(P) enables Free Position mode. Each line corresponds to a subplot.

Without input argument, subplotpos returns the current position of all subplots if Free Position mode is enabled, or the empty array [] otherwise.

subplotpos complements subplots and subplotprops by getting or restoring the subplot positions set by the user. It is typically used in the input and output handlers. It may also be used in init, menu, or key handlers. For restoring the settings, it must be placed after subplots.

Example

x = subplotpos
  x =
    0 30.3125 0 20.625
    30.3125 60.625 0 20.625
    0 30.3125 20.625 41.25
    30.3125 60.625 20.625 41.25
subplotpos([0,29,0,20; 31,60,0,20;0,60,21,25])

See also

subplots, subplotspring, subplotsize, subplotprops, subplotparam, scale

subplotprops

Get or restore the properties of subplots.

Syntax

P = subplotprops
(P, P3)  = subplotprops
subplotprops(P)
subplotprops(P, P3)

Description

subplotprops complements subplots and subplotpos by getting or restoring the display options set by the user. These options include the kind of scale (linear, logarithmic or dB, equal for both axis or not, grids, etc.), the scale itself, set with the Zoom, Zoom X, and Drag modes, and the scale overview rectangle if any. Each line corresponds to a subplot. The second argument, if it exists, contains the options for 3D graphics.

subplotprops is typically used in the input and output handlers. It may also be used in init, menu, or key handlers. For restoring the settings, it must be placed after subplots.

Example

subplotprops
  1 0.1 10 1 100
  0 -1 1 -1 1
  0 -2 0 -1 1
  1 0 10 0 0
subplotprops([1,0.1,10,1,100;0,-1,1,-1,1;0,-2,0,-1,1;1,0,10,0,0])

See also

subplots, subplotpos, subplotparam, scale

subplots

Get or restore the number and kind of subplots.

Syntax

s = subplots
subplots(s)

Description

The subplots can be seen as a matrix of figures. Each figure is identified by the name given after the figure keyword in the SQ file; an empty name corresponds to an empty subplot. The subplots function uses a single string to identify all the subplots. The names of subplots in a row are separated by the tabulator character '\t'; rows are separated by the linefeed character '\n'. These characters play the same role as respectively the comma and the semicolon in a numeric matrix. However, rows do not have to have the same length; the row with the more subplots determines the size of the subplot array.

In Free Position mode, subplots are specified as a one-dimension array: names are separated by the linefeed character '\n'. The position of each subplot is specified with subplotpos.

The subplots command can be used either with no input and one output argument to retrieve the subplots currently displayed, or with one input and no output to set the number of subplots and their contents.

The most common use of subplots is in init handlers to set the initial set of figures, and in menu handlers to switch easily to preconfigured layouts.

With an input argument, subplots must not be executed in the draw, mousedown, mousedrag, mousedragcont, mouseover, mouseout, mousescroll, dragin, dragout, or fighandler handlers (the subplots must not be changed during a drag). However, it can be used in a mouseup or mousedoubleclick handler to emulate a button click which could change subplots.

Example

Set the layout to two rows of two subplots, with figures "Step" and "Nyquist" at top, and "Poles" and "Bode" at bottom:

subplots('Step\tNyquist\nPoles\tBode');

See also

scalesync, subplotprops, subplotpos, subplotparam

subplotsize

Window size assumed for subplot placement.

Syntax

subplotsize(width, height)
subplotsize([width, height])
S = subplotsize

Description

subplotpos sets the position and size of subplots, and subplotspring how they are resized and moved when the window is resized. Hence the initial window size has an effect on the subplot placement for a given size of the window. Function subplotsize specifies the window size assumed for subplotpos. If the actual window size is different, subplots are resized using the values provided with subplotspring.

Important: since subplotsize resizes all subplots using the values set by subplotpos and subplotspring, it must be executed after both of them.

subplotsize(width,height) or subplotsize(S), where S is an array of two elements [width,height, sets the assumed size to width and height, with the same units as those used by subplotpos. Both numbers must be positive on all platforms.

Without input argument, subplotsize returns the current window size.

See also

subplotpos, subplotspring

subplotspring

Get or restore the resizing properties of subplots.

Syntax

subplotspring([sl1,sw1,sr1,st1,sh1,sb1;...])
S = subplotspring

Description

The subplotspring function handles how the position of subplots in Free Position mode is adjusted when the window is resized.

In Free Position mode, the automatic adjustment properties of each subplot is specified independently by six numbers in the range [0,1]: three for horizontal size and position, three for vertical size and position. These numbers are used when the window is resized, not when the position of subplots is changed manually or with subplotpos. Subplots are resized as if they were made of three springs along the horizontal axis, and three springs along the vertical axis. subplotspring sets or retrieves the relative spring stiffness. For instance, if the spring corresponding to the subplot width is infinitely stiff and the springs corresponding to the left and to the right have the same values, resizing the window will keep the subplot width and move it such that spaces at left and right grow or shrink proportionally.

Actual values are e/(1+e), where e=k/l, k=dF/dl is the spring constant, l is the length, and F is the force. Changing the window size preserves the force equilibrium. A value of 0 is infinitely flexible (i.e. other springs will keep their length for any window size change), and a value of 1 is infinitely stiff (i.e. the corresponding length will be preserved).

The following triplets are worth mentioning:

0.5,0.5,0.5
subplot size and position proportional to the window size
1,1,0
fixed size and position with respect to the left or top of the window
1,0,1
fixed space on the left and on the right of, or above and below, the subplot
0,1,1
fixed size and position with respect to the right or bottom of the window

subplotspring(S) sets the spring values of each subplot in the Figure window. Each row of array S corresponds to a subplot, in the same order as they are enumerated by function subplots. In each row, values correspond to the left, width, right, top, height, and bottom springs.

Without input argument, subplotspring returns the current spring values of all subplots if Free Position mode is enabled, or the empty array [] otherwise.

subplotspring complements subplots and subplotpos. It should be followed by subplotsize so that subplots are immediately resized if the window size does not match the size assumed by subplotpos. It is typically used in the input and output handlers; it may also be used in init, menu, or key handlers.

See also

subplots, subplotpos, subplotsize, subplotprops, subplotparam, scale

subplotsync

Set scale synchronization between all subplots.

Syntax

S = subplotsync
subplotsync(S)

Description

Without input argument, subplotsync(S) returns an n-by-2 array which defines if and how subplot scales are synchronized. When there is no synchronization at all, S is the empty array []. Otherwise, it has as many rows as there are subplots. First row correspond to first subplot (top-left for a grid array), second row to second subplot of first row, and so on. For each row, the first element is 0 for no scale synchronization, 1 for synchronization of X axis, 2 for Y axis, and 3 for both X and Y axes; and the second element is an integer different for each group of synchronized subplots.

subplotsync(S) sets scale synchronization globally for all subplots. While scalesync synchronize the scale of a group of subplots together, subplotsync defines the synchronization for all subplots in a single call. Typically, subplotsync(S) should be used to restore the synchronization state obtained with S=subplotsync, while scalesync is simpler and clearer when writing an init handler.

subplotprops is typically used in the input and output handlers. It may also be used in init, menu, or key handlers. For restoring the settings, it must be placed after subplots.

See also

scalesync, subplots, subplotpos, subplotparam

text

Display formatted text in a figure.

Syntax

text(string)
text(string, font)

Description

With a single argument, text displays its string argument in the current subplot figure. It can be mixed with sliders and buttons, but no other graphics should be displayed. The string is split in rows and columns; columns are separated by the tab character ('\t'), and lines by the linefeed character ('\n'). The width of the columns can be specified with settabs.

A second argument specifies the type face and color to use. It is a structure which is typically created with fontset. The font and size are ignored. Alternatively, named arguments can be used directly, without fontset.

With plotoption math, label segments (defined by tab and linefeed characters) can contain MathML or LaTeX.

With three arguments or more, text displays a string at the specified position in graphics.

Examples

Two lines and two columns are displayed, with labels in the first column and numeric values in the second column. Note the use of sprintf to format the numbers.

text(sprintf('One\t%.2f\nPi\t%.f', 1, pi))

Red bold text:

text('Results', Bold=true, Color='red');

See also

text (in graphics), settabs, textfield, slider, button, sprintf, plotoption

textfield

Text field.

Syntax

textfield(label, format, value)
textfield(label, format, value, style)
textfield(label, format, value, style, id)

Description

textfield(label,format,value) displays a text field. Text fields are rectangular areas which display a numeric or string value and permit the user to edit it with the keyboard. Argument label contains a string which is displayed on the left. Argument value, a scalar number or a string, is the contents of the text field; it is formatted after argument format and aligned to the right (number) or left (string) of the text field. format is a string similar to the first argument of sprintf, with a single number-formatting or string sequence; it begins with a percent sign, an optional width, an optional dot and precision, and a single letter which must be one of fFgGeEkKdoxX for numbers, or s for string. Format o interprets input in octal and formats x and X in hexadecimal. The width limits the maximum number of characters (actually the number of bytes for the UTF-8 representation of the string), but is extended to accept the representation of value. It is useful mainly with strings.

The style argument, if present and not empty, is a string which specifies the color of the text field. The id argument is the object id (cf. their description above).

With plotoption math, label can contain MathML or LaTeX.

Usually, figures which contain text fields are associated with a mousedrag handler only. Editing a text field calls the mousedrag handler once, when the user types the Return key or clicks in any figure. The text field is identified with _id. For numbers, the new value is contained in _x1, with full precision (argument format is used only to format the value before displaying it, not to decode it). For strings, the new value is contained in _str1.

A single textfield command can display text fields for multiple numbers: in that case, argument value is a vector or array of values, argument label contains the labels displayed in front of each value as a single string where labels are separated with tabulators (\t) for values on the same line or line feeds (\n) for values on different lines, and arguments format and style can contain multiple format and style specifications. The layout is controlled by the tabulators set with settabs: the first label left-aligned in the first column, the first value in the second column, the second label in the third column if it follows a tabulator chacter, and so on. In the mousedrag handler, each value is identified with _nb.

Examples

A simple numeric text field:

T = 21.3;
textfield('Temperature:', '%.1f', T, '', 1);

The corresponding mousedrag handler:

function T = temperatureHandler(_id, _x1)
  switch _id
    case 1
      T = _x1;
      fprintf('New temperature: %g\n', T);
    otherwise
      cancel;
  end

Four text fields with different formats and styles:

v = [1, 2.3, pi/2, -1.7];
settabs('First value: \t 0000000\t Second value: \t0000000');
labels = 'First value:\t Second value:\nAlpha:\t Beta:';
formats = '%.1g%.1g%.3f%.3f';
styles = 'rgbk';
textfield(labels, formats, v, styles, 1);

A string text field for a string of up to 10 bytes, whose id is specified with a named argument:

str = 'Hello';
textfield('String:', '%10s', str, id = 1);

The corresponding mousedrag handler, with id and new value read directly in the function instead of being passed as arguments:

function str = stringHandler()
  switch _id
    case 1
      str = _str1;
      fprintf('New string: %s\n', str);
    otherwise
      cancel;
  end

See also

settabs, slider, text, button, pushbutton, popupmenu, sprintf, plotoption