35.1 Диалоговые окна ввода-вывода

Для выбора каталогов или файлов доступны простые диалоговые меню. Они возвращают строковую переменную, которую затем можно использовать с любой командой, требующей имени файла.

: dirname = uigetdir ()

: dirname = uigetdir (init_path)

: dirname = uigetdir (init_path, dialog_name)

Открывает диалоговое окно с графическим интерфейсом для выбора каталога.

Если init_path не задан, используется текущий рабочий каталог.

Параметр dialog_name можно использовать для настройки заголовка диалогового окна.

Выходной параметр dirname — это строка символов с именем выбранного каталога. Однако если нажать кнопку «Cancel», выходное значение будет иметь тип double и значение 0.

См. также: uigetfile, uiputfile.

: [fname, fpath, fltidx] = uigetfile ()

: […] = uigetfile (flt)

: […] = uigetfile (flt, dialog_name)

: […] = uigetfile (flt, dialog_name, default_file)

: […] = uigetfile (…, "MultiSelect", mode)

Открывает диалоговое окно с графическим интерфейсом для выбора файла и возвращает имя файла fname, путь к нему fpath и индекс фильтра fltidx.

flt содержит строку (или список строк) фильтра файлов в одном из следующих форматов:

"/path/to/filename.ext"

Если задано имя файла, его расширение извлекается и используется в качестве фильтра. Кроме того, путь выбирается как текущий путь в диалоговом окне, а имя файла указывается как файл по умолчанию. Пример: uigetfile ("myfcn.m")

Одно расширение файла "*.ext"

Пример: uigetfile ("*.ext")

Ячейковый массив из двух столбцов

содержащий расширение файла в первом столбце и краткое описание во втором столбце. Пример: uigetfile ({"*.ext", "My Description";"*.xyz", "XYZ-Format"})

Строка фильтра также может содержать список расширений фильтра, разделённых точками с запятой. Пример: uigetfile ({"*.gif;*.png;*.jpg", "Supported Picture Formats"})

Имя каталога или путь

Если имя папки или путь заканчивается разделителем файлов, отображается содержимое этой папки. Если завершающего разделителя файлов нет, отображается родительский каталог. Подстрока справа от крайнего правого разделителя файлов (если он есть) интерпретируется как имя файла или каталога; если такой файл или каталог существует, он будет выделен. Если путь или имя каталога полностью или частично не существует, будет отображён текущий рабочий каталог. Фильтр не будет активен.

Параметр dialog_name можно использовать для настройки заголовка диалогового окна.

Если задан параметр default_file, он будет выбран в диалоговом окне. Если дополнительно задан путь, он также используется как текущий путь.

Можно выбрать два или более файла, установив ключ "MultiSelect" в значение "on". В этом случае fname представляет собой ячейковый массив с именами файлов.

Выходные параметры fname и fpath — это строки, возвращающие соответственно выбранное имя и путь. Однако если нажать кнопку «Cancel», выходные значения будут иметь тип double и значение 0. fltidx — это индекс выбранного фильтра в списке расширений фильтра flt.

См. также: uiputfile, uigetdir.

: [fname, fpath, fltidx] = uiputfile ()

: [fname, fpath, fltidx] = uiputfile (flt)

: [fname, fpath, fltidx] = uiputfile (flt, dialog_name)

: [fname, fpath, fltidx] = uiputfile (flt, dialog_name, default_file)

Открывает диалоговое окно с графическим интерфейсом для выбора файла.

flt содержит строку (или список строк) фильтра файлов в одном из следующих форматов:

"/path/to/filename.ext"

Если задано имя файла, его расширение извлекается и используется в качестве фильтра. Кроме того, путь выбирается как текущий путь в диалоговом окне, а имя файла указывается как файл по умолчанию. Пример: uiputfile ("myfcn.m")

"*.ext"

Одно расширение файла. Пример: uiputfile ("*.ext")

{"*.ext", "My Description"}

Ячейковый массив из двух столбцов, содержащий расширение файла в первом столбце и краткое описание во втором столбце. Пример: uiputfile ({"*.ext","My Description";"*.xyz", "XYZ-Format"})

Строка фильтра также может содержать список расширений фильтра, разделённых точками с запятой. Пример: uiputfile ({"*.gif;*.png;*.jpg", "Supported Picture Formats"})

Параметр dialog_name можно использовать для настройки заголовка диалогового окна. Если задан параметр default_file, он будет предварительно выбран в диалоговом окне. Если дополнительно задан путь, он также используется как текущий путь.

fname и fpath возвращают соответственно выбранное имя и путь. fltidx — это индекс выбранного фильтра в списке расширений фильтра flt.

См. также: uigetfile, uigetdir.

Кроме того, предусмотрены диалоговые окна для отображения справочных сообщений, предупреждений или ошибок, а также для получения текстовых данных от пользователя.

: errordlg ()

: errordlg (msg)

: errordlg (msg, title)

: errordlg (msg, title, opt)

: h = errordlg (…)

Отображает диалоговое окно ошибки с сообщением об ошибке msg и заголовком title.

Сообщение об ошибке по умолчанию — "This is the default error string.", а заголовок по умолчанию — "Error Dialog".

Сообщение об ошибке может состоять из нескольких строк, разделённых символами новой строки ("\n"), или быть массивом cellstr, содержащим по одному элементу для каждой строки.

Третий необязательный аргумент opt управляет поведением диалогового окна. Подробнее см. в разделе msgbox.

Возвращаемое значение h — это дескриптор объекта figure, используемого для создания диалогового окна.

Примеры:

errordlg ("Some fancy error occurred.");
errordlg ("Some fancy error\nwith two lines.");
errordlg ({"Some fancy error", "with two lines."});
errordlg ("Some fancy error occurred.", "Fancy caption");

См. также: helpdlg, warndlg, msgbox, inputdlg, listdlg, questdlg.

: helpdlg ()

: helpdlg (msg)

: helpdlg (msg, title)

: h = helpdlg (…)

Отображает справочное диалоговое окно с сообщением msg и заголовком title.

Справочное сообщение по умолчанию — "This is the default help string.", а заголовок по умолчанию — "Help Dialog".

Справочное сообщение может состоять из нескольких строк, разделённых символами новой строки ("\n"), или быть массивом cellstr, содержащим по одному элементу для каждой строки.

Возвращаемое значение h — это дескриптор объекта figure, используемого для создания диалогового окна.

Примеры:

helpdlg ("Some helpful text for the user.");
helpdlg ("Some helpful text\nwith two lines.");
helpdlg ({"Some helpful text", "with two lines."});
helpdlg ("Some helpful text for the user.", "Fancy caption");

См. также: errordlg, warndlg, msgbox, inputdlg, listdlg, questdlg.

: cstr = inputdlg (prompt)

: cstr = inputdlg (prompt, title)

: cstr = inputdlg (prompt, title, rowscols)

: cstr = inputdlg (prompt, title, rowscols, defaults)

: cstr = inputdlg (prompt, title, rowscols, defaults, options)

Возвращает введённые пользователем данные из диалогового окна с несколькими текстовыми полями в виде ячейкового массива строк или пустой ячейковый массив, если диалоговое окно закрыто кнопкой «Cancel».

Входные параметры:

prompt

Ячейковый массив строк, задающих подписи для каждого текстового поля. Этот параметр обязателен.

title

Строка, используемая в качестве заголовка диалогового окна. По умолчанию — "Input Dialog".

rowscols

Задаёт размер текстовых полей и может иметь одну из трёх форм:

1. скалярное значение, задающее количество строк для каждого текстового поля.
2. вектор, задающий индивидуальное количество строк для каждого текстового поля.
3. матрица, задающая индивидуальное количество строк и столбцов для каждого текстового поля. Каждая строка матрицы описывает одно текстовое поле. Первый столбец задаёт количество строк ввода, а второй — ширину текстового поля.

defaults

Список значений по умолчанию, помещаемых в каждое текстовое поле. Должен быть ячейковым массивом строк того же размера, что и prompt.

options

Не поддерживается; предусмотрен только для совместимости с MATLAB.

Пример:

prompt = {"Width", "Height", "Depth"};
defaults = {"1.10", "2.20", "3.30"};
rowscols = [1,10; 2,20; 3,30];
dims = inputdlg (prompt, "Enter Box Dimensions", ...
                 rowscols, defaults);

См. также: errordlg, helpdlg, listdlg, msgbox, questdlg, warndlg.

: [sel, ok] = listdlg (key, value, …)

Возвращает введённые пользователем данные из диалогового окна со списком в виде вектора индексов выбранных элементов (sel) и флага, указывающего, как пользователь закрыл диалоговое окно (ok).

Индексы в sel начинаются с 1.

Значение ok равно 1, если пользователь закрыл окно кнопкой OK; в противном случае оно равно 0, а sel пуст.

Входные аргументы задаются парами key, value. Пара аргументов "ListString" обязательно должна быть указана.

Допустимые пары key и value:

"ListString"

ячейковый массив строк, задающих элементы для отображения в списке диалогового окна.

"SelectionMode"

может быть равен "Single" (одновременно можно выбрать только один элемент) или "Multiple" (значение по умолчанию).

"ListSize"

двухэлементный вектор [width, height], задающий размер поля списка в пикселях. По умолчанию — [160, 300].

"InitialValue"

вектор, содержащий начинающиеся с 1 индексы элементов, которые будут предварительно выбраны при первом отображении диалогового окна со списком. По умолчанию — 1 (первый элемент).

"Name"

строка, используемая в качестве заголовка диалогового окна. По умолчанию — "".

"PromptString"

ячейковый массив строк, отображаемых над списком элементов. По умолчанию — {}.

"OKString"

строка, используемая в качестве подписи кнопки OK. По умолчанию — "OK".

"CancelString"

строка, используемая в качестве подписи кнопки Cancel. По умолчанию — "Cancel".

Пример:

my_options = {"An item", "another", "yet another"};
[sel, ok] = listdlg ("ListString", my_options,
                     "SelectionMode", "Multiple");
if (ok == 1)
  disp ("You selected:");
  for i = 1:numel (sel)
    disp (sprintf ("\t%s", my_options{sel(i)}));
  endfor
else
  disp ("You cancelled.");
endif

См. также: menu, errordlg, helpdlg, inputdlg, msgbox, questdlg, warndlg.

: h = msgbox (msg)

: h = msgbox (msg, title)

: h = msgbox (msg, title, icon)

: h = msgbox (msg, title, "custom", cdata)

: h = msgbox (msg, title, "custom", cdata, colormap)

: h = msgbox (…, opt)

Отображает msg в диалоговом окне сообщения.

Сообщение может состоять из нескольких строк, разделённых символами новой строки ("\n"), или быть массивом cellstr, содержащим по одному элементу для каждой строки.

Необязательный входной параметр title (строка символов) можно использовать для задания заголовка диалогового окна.

Необязательный аргумент icon задаёт значок диалогового окна. Он может принимать одно из значений "none" (по умолчанию), "error", "help", "warn" или "custom". За последним значением должен следовать массив изображения cdata, а для индексированных изображений — соответствующая карта цветов.

Последний необязательный аргумент opt управляет поведением диалогового окна. Если opt — строка, она может принимать одно из следующих значений:

"non-modal" (по умолчанию)

Диалоговое окно работает в обычном режиме.

"modal"

Если уже существуют диалоговые окна с таким же заголовком, используется самое последнее из них, а все остальные закрываются. Диалоговое окно отображается "modal", то есть не позволяет пользователям взаимодействовать с другими элементами графического интерфейса, пока диалоговое окно не будет закрыто.

"replace"

Если уже существуют диалоговые окна с таким же заголовком, используется самое последнее из них, а все остальные закрываются. Созданное диалоговое окно получает свойство "non-modal".

Если opt — структура, она должна содержать поля "WindowStyle" и "Interpreter":

"WindowStyle"

Значение должно быть "non-modal", "modal" или "replace". См. выше.

"Interpreter"

Управляет свойством "interpreter" текстового объекта, используемого для отображения сообщения. Значение должно быть "tex" (по умолчанию), "none" или "latex".

Возвращаемое значение h — это дескриптор объекта figure, используемого для создания диалогового окна.

Примеры:

msgbox ("Some message for the user.");
msgbox ("Some message\nwith two lines.");
msgbox ({"Some message", "with two lines."});
msgbox ("Some message for the user.", "Fancy caption");

## A message dialog box with error icon
msgbox ("Some message for the user.", "Fancy caption", "error");

См. также: errordlg, helpdlg, inputdlg, listdlg, questdlg, warndlg.

: btn = questdlg (msg)

: btn = questdlg (msg, title)

: btn = questdlg (msg, title, default)

: btn = questdlg (msg, title, btn1, btn2, default)

: btn = questdlg (msg, title, btn1, btn2, btn3, default)

Отображает msg в диалоговом окне вопроса и возвращает подпись активированной кнопки.

Сообщение может состоять из нескольких строк, разделённых символами новой строки ("\n"), или быть массивом cellstr, содержащим по одному элементу для каждой строки.

Необязательный параметр title (строка символов) можно использовать для задания заголовка диалогового окна. По умолчанию используется "Question Dialog".

Диалоговое окно может содержать две или три кнопки, каждая из которых закрывает окно.

Строка default указывает кнопку по умолчанию, которая активируется нажатием клавиши ENTER. Она должна совпадать с одной из строк, заданных в btn1, btn2 или btn3.

Если заданы только msg и title, используются три кнопки со стандартными подписями "Yes", "No" и "Cancel".

Если заданы только две подписи кнопок — btn1 и btn2, — в диалоговом окне будут только эти две кнопки.

Примеры:

btn = questdlg ("Close Octave?", "Some fancy title", ...
                "Yes", "No", "No");
if (strcmp (btn, "Yes"))
  exit ();
endif

См. также: errordlg, helpdlg, inputdlg, listdlg, msgbox, warndlg.

: warndlg ()

: warndlg (msg)

: warndlg (msg, title)

: warndlg (msg, title, opt)

: h = warndlg (…)

Отображает диалоговое окно предупреждения с сообщением msg и заголовком title.

Сообщение предупреждения по умолчанию — "This is the default warning string.", а заголовок по умолчанию — "Warning Dialog".

Сообщение предупреждения может состоять из нескольких строк, разделённых символами новой строки ("\n"), или быть массивом cellstr, содержащим по одному элементу для каждой строки.

Третий необязательный аргумент opt управляет поведением диалогового окна. Подробнее см. в разделе msgbox.

Возвращаемое значение h — это дескриптор объекта figure, используемого для создания диалогового окна.

Примеры:

warndlg ("Some warning text for the user.");
warndlg ("Some warning text\nwith two lines.");
warndlg ({"Some warning text", "with two lines."});
warndlg ("Some warning text for the user.", "Fancy caption");

См. также: errordlg, helpdlg, msgbox, inputdlg, listdlg, questdlg.

: uisetfont ()

: uisetfont (h)

: uisetfont (fontstruct)

: uisetfont (…, title)

: fontstruct = uisetfont (…)

Открывает диалоговое окно выбора шрифта.

Если первый аргумент — это дескриптор объекта text, axes или uicontrol, нажатие кнопки OK изменит свойства шрифта этого объекта.

Первый аргумент также может быть структурой с полями FontName, FontWeight, FontAngle, FontUnits и FontSize, задающими изначально выбранный шрифт.

Заголовок диалогового окна можно задать с помощью последнего аргумента title.

Если запрошен выходной аргумент fontstruct, возвращается структура выбранного шрифта. В противном случае сведения о шрифте отображаются на экране.

Примечание по программированию: в системах, которые не используют FontConfig изначально (во всех системах, кроме Linux), кэш шрифтов создаётся при установке Octave. После установки новых шрифтов необходимо вручную выполнить system ("fc-cache -fv").

См. также: listfonts, text, axes, uicontrol.

Для создания новых типов диалоговых окон предусмотрена функция dialog.

: h = dialog ()

: h = dialog ("property", value, …)

Создаёт пустое модальное диалоговое окно, в которое можно добавлять другие элементы uicontrol.

Диалоговое окно представляет собой объект figure со свойствами, рекомендованными для диалоговых окон.

Свойства по умолчанию, отличающиеся от свойств объекта figure:

buttondownfcn

if isempty (allchild(gcbf)), close (gcbf), endif

colormap

[]

color

defaultuicontrolbackgroundcolor

dockcontrols

off

handlevisibility

callback

integerhandle

off

inverthardcopy

off

menubar

none

numbertitle

off

paperpositionmode

auto

resize

off

windowstyle

modal

Для объекта диалогового окна можно указать несколько пар «свойство-значение», но они должны задаваться попарно. Полный список свойств приведён в разделе Свойства Figure.

Возвращаемое значение h — это графический дескриптор созданного объекта figure.

Пример:

## create an empty dialog window titled "Dialog Example"
h = dialog ("name", "Dialog Example");

## create a button (default style)
b = uicontrol (h, "string", "OK",
                  "position", [10 10 150 40],
                  "callback", "delete (gcf)");

## wait for dialog to resume or close
uiwait (h);

См. также: errordlg, msgbox, questdlg, warndlg, figure, uiwait.