dialog

Display a dialog box.

Syntax

dialog(str)
ok = dialog(str)
(x1,x2,...) = dialog(str,x10,x20,...)
(ok,x1,x2,...) = dialog(str,x10,x20,...)
... = dialog(opt, ...)
dialog(opt1=value1,...)
ok = dialog(opt1=value1,...)
... = dialog(x10,x20,...,opt1=value1,...)

Description

dialog(str) displays the string str in a dialog box with a button labeled OK, and waits until the user clicks the button.

With an output argument, ok=dialog(str) displays the string str in a dialog box with two buttons, labeled OK and Cancel, and waits until the user clicks one of them; the result is true if the user clicks OK and false if he clicks Cancel.

With more than one input argument and the same number of input and output arguments, (ok,x1,x2,...)=dialog(str,x10,x20,...) displays in a dialog box the string str, a text field with the value of the remaining input arguments separated by commas, and two buttons labeled OK and Cancel. The user may edit the values in the text field. If he clicks OK, the first output argument is set to true, and the remaining arguments are set to the new value of the expressions in the text field. Should the user click the Cancel button, ok is set to false and all the other outputs are set to an empty matrix. With one output argument less, (x1,x2,...)=dialog(str,x10,x20,...) returns the new values if the user clicks OK; otherwise, it throws a Cancel error, which may simplify menu handlers.

Instead of a string, the first input argument of dialog can be a structure of options created by dialogset. In addition to the prompt message, options permit to provide a title for the dialog window and to limit the precision of double numbers.

Alternatively, all options can be provided as named arguments. Named option arguments may not be mixed with an initial message string or an initial option structure; the unnamed arguments are all considered to be the initial values to be edited in a text field.

The syntax permitted for the expressions typed in the dialog box is a small subset of LME's. In addition to scalars, complex numbers (entered as 2+3j without the multiplication operator), arrays and strings, are authorized the addition and subtraction operators, the negation, the transpose and complex transpose, the matrix construction functions zeros, ones, and eye, and the range operator :. Functions struct, class and inline and operator @ are also permitted to create structures, objects, inline and anonymous functions respectively. If the expression typed by the user does not satisfy these rules, or if the number of comma-separated values is not equal to the number of expected arguments, the entry is rejected and the dialog box is displayed again. The user can always click the Cancel button to close the dialog box, whatever is typed in the entry field.

Examples

Simple alert box:

dialog(sprintf(['You cannot have more zeros than poles ',...
                '(currently %d)'], np));

Dialog box with OK and Cancel buttons:

if dialog('Do you really want to reset the weights?')
    w = [];
end

Dialog with options:

opt = dialogset(Title='System',
    Prompt='Transfer function of the system',
    NPrec=4);
num = 1/3;
den = [1/3, 1/7];
(num, den) = dialog(opt, num, den);

The same dialog with options provided directly to dialog as named arguments:

(num, den) = dialog(num, den,
    Title='System',
    Prompt='Transfer function of the system',
    NPrec=4);

Two equivalent menu handlers:

function (num, den) = menuHandler1(num, den)
  (ok, num, den) = dialog('Numerator, denominator', num, den);
  if ~ok
      cancel;
  end
function (num, den) = menuHandler2(num, den)
  (num, den) = dialog('Numerator, denominator', num, den);

Caveats

Some simplified versions of Sysquake may not implement dialog. In this case, dialog does not display any dialog box and always returns false and empty values.

See also

dialogset, cancel

dialogset

Options for dialog.

Syntax

options = dialogset
options = dialogset(name1, value1, ...)
options = dialogset(options0, name1, value1, ...)

Description

dialogset(name1,value1,...) creates the option argument used by dialog. Options are specified with name/value pairs, where the name is a string which must match exactly the names in the table below. Case is significant. Options which are not specified have a default value. The result is a structure whose fields correspond to each option. Without any input argument, dialogset creates a structure with all the default options.

When its first input argument is a structure, dialogset adds or changes fields which correspond to the name/value pairs which follow.

Here is the list of permissible options (empty arrays mean "automatic"):

Name	Default	Meaning
Title	''	title of the dialog
Prompt	''	prompt (message)
NPrec	15	maximum number of digits for double numbers
OKIsDefault	true	Return key is a shortcut for OK
SingleLine	false	single-line representation
NoChangeIsCancel	false	no change means Cancel

Option NPrec is used only to display the initial value in the dialog edit field. The full precision entered is used when decoding output values.

Option SingleLine can be used to display values without line breaks in the edit field (for example, matrix rows are separated with semicolons instead of line breaks).

If option NoChangeIsCancel is true and the edit field has not been changed at all by the user, the dialog is reported to be cancelled.

Examples

Default options:

dialogset
  Title: ''
  Prompt: ''
  NPrec: 15

See also

dialog

getfile

Display a dialog box for choosing a file.

Syntax

path = getfile
path = getfile(prompt)
path = getfile(prompt, mimetypes)

Description

Without input argument, getfile displays a dialog box where the user may choose an existing file. It gives the full path of the selected file if the user clicks the OK button, or an empty string if he clicks the Cancel button. getfile(prompt) displays the string prompt in the file dialog box. getfile(prompt,mimetypes) displays only the files corresponding to the MIME types enumerated in the string mimetypes. Different MIME types are separated by semicolons.

Note that the actual functionality may be limited by the implementation of the standard file dialog of the windowing system. For instance, the prompt may be ignored. Versions of Sysquake without low-level access return an empty string without displaying any dialog.

Example

path = getfile('Image file:', 'image/tiff;image/jpeg;image/png')
  /Users/sysquake/sunset.jpg

See also

putfile

putfile

Display a dialog box to enter a filename at a specific location.

Syntax

path = putfile
path = putfile(prompt)
path = putfile(prompt, defaultfilename)

Description

Without input argument, putfile displays a dialog box where the user may enter the name of a new file at a specific location. It gives the full path of the file if the user clicks the OK button, or an empty string if he clicks the Cancel button. putfile(prompt) displays the string prompt in the file dialog box. putfile(prompt,defaultfilename) proposes the string defaultfilename as default file name.

Note that the actual functionality may be limited by the implementation of the standard file dialog of the windowing system. For instance, the prompt may be ignored. Versions of Sysquake without low-level access return an empty string without displaying any dialog.

Example

path = putfile('Save as HTML:', 'report.html')
  D:\WORK\REP02.HTM

See also

getfile