Приложения

Приложение А. Функции, константы и структуры RDS

А.5. Сервисные функции и макросы RDS

А.5.5. Вызов стандартных диалогов

А.5.5.6. rdsMessageBox – вывод окна сообщения

Функция rdsMessageBox выводит стандартное окно сообщения Windows, не останавливая при этом поток расчета, даже если она вызвана из него.

  int RDSCALL rdsMessageBoxA(
    RDSCSTR Text,     // Текст сообщения (UTF8)
    RDSCSTR Caption,  // Заголовок окна сообщения (UTF8)
    int Flags         // Флаги Windows API (MB_*)
  );
  int RDSCALL rdsMessageBoxW(
    RDSWCSTR Text,    // Текст сообщения (UTF16)
    RDSWCSTR Caption, // Заголовок окна сообщения (UTF16)
    int Flags         // Флаги Windows API (MB_*)
  );
  // Функция-псевдоним
  int RDSCALL rdsMessageBox(
    RDSXCSTR Text,    // Текст сообщения (кодировка по умолчанию)
    RDSXCSTR Caption, // Заголовок окна сообщения (кодировка по умолчанию)
    int Flags         // Флаги Windows API (MB_*)
  );

Тип указателя на эту функцию

RDS_ISSI (для UTF8) или RDS_IWsWsI (для UTF16)

Параметры

Text (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с текстом выводимого сообщения. Сообщение может состоять из нескольких строк, разделенных символом перевода строки «\n» (код 10).

Caption (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с заголовком окна выводимого сообщения.

Flags (int)

Битовые флаги сообщения, определяющие набор кнопок в окне, иконку сообщения и т.п. Эти флаги совпадают с флагами стандартной функции Windows API MessageBox. Для задания иконки сообщения чаще всего используются следующие флаги:

MB_ICONERROR	Знак «стоп» – обычно используется в сообщениях о фатальных ошибках.
MB_ICONINFORMATION	Знак информационного сообщения – обычно используется в различных сообщениях, не связанных с ошибками.
MB_ICONQUESTION	Вопросительный знак – используется в запросах пользователю, когда он должен ответить «да»/«нет» или подтвердить/отменить какое-либо действие.
MB_ICONWARNING	Восклицательный знак – обычно используется в предупреждающих сообщениях.

Для задания набора кнопок в окне сообщения используются следующие флаги:

MB_ABORTRETRYIGNORE	В окне три кнопки: «стоп», «повтор» и «пропустить».
MB_OK	В окне единственная кнопка «OK».
MB_OKCANCEL	В окне две кнопки: «OK» и «отмена».
MB_RETRYCANCEL	В окне две кнопки: «повтор» и «отмена».
MB_YESNO	В окне две кнопки: «да» и «нет».
MB_YESNOCANCEL	В окне три кнопки: «да», «нет» и «отмена».

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

MB_DEFBUTTON1	По умолчанию выбрана первая кнопка.
MB_DEFBUTTON2	По умолчанию выбрана вторая кнопка.
MB_DEFBUTTON3	По умолчанию выбрана третья кнопка.

В параметре Flags могут также указываться прочие флаги, используемые в функции Windows API MessageBox.

Возвращаемое значение

Стандартная константа Windows API, указывающая на нажатую пользователем кнопку окна сообщения:

Если сообщение выведено в режиме расчета, всегда возвращается константа IDCANCEL.

Примечания

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

Если же rdsMessageBox вызвана из потока расчета, она немедленно вернет константу IDCANCEL не открывая окна. Окно с сообщением откроется позже, при первой возможности, в главном потоке RDS, при этом флаги кнопок будут проигнорированы и в окне будет единственная кнопка «OK».

Таким образом, функцию rdsMessageBox можно безопасно вызывать из потока расчета (например, из реакции блока на такт моделирования RDS_BFM_MODEL) для вывода сообщений пользователю, не вызывая при этом остановку потока. Разумеется, в этом случае нельзя будет узнать, какую кнопку нажал пользователь, поскольку моменты вызова функции и фактического открытия окна будут разнесены во времени.

См. также

rdsBlockMessageBox.