Message

Programming Far Manager plugins

previous page next page

Message

Функция Message показывает сообщение.

intptr_t WINAPI Message(
  const GUID *PluginId,
  const GUID *Id,
  FARMESSAGEFLAGS Flags,
  const wchar_t *HelpTopic,
  const wchar_t * const *Items,
  size_t ItemsNumber,
  intptr_t ButtonsNumber
);

Параметры

PluginId

Указатель на GUID плагина (для вашего плагина, GUID должен быть таким же, что и в поле GlobalInfo.Guid функции GetGlobalInfoW).

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

Flags

Может быть комбинацией следующих значений (тип FARMESSAGEFLAGS):

Флаг	Описание
FMSG_WARNING	Используются цвета "Предупреждения" (обычно белые буквы на красном фоне).
FMSG_ERRORTYPE	Если тип ошибки, возвращаемый функцией `GetLastError`, известен Far Manager'у или Windows, то описание ошибки будет выведено после строк, переданных плагином.
FMSG_KEEPBACKGROUND	Не перерисовывать фон сообщения.
FMSG_LEFTALIGN	Использовать для строк сообщения выравнивание влево (по умолчанию строки выводятся по центру).
FMSG_ALLINONE	В этом случае аргумент `Items` не является массивом указателей на строки - это УКАЗАТЕЛЬ на одну строку, в которой разделителем выводимых строк является символ `'\n'`. Минимальное количество строк - 2 - заголовок и одна строка сообщения. При указании флага `FMSG_ALLINONE` аргумент `ItemsNumber` игнорируется и количество выводимых строк вычисляется автоматически (с учётом флагов-кнопок `FMSG_MB_*`). Для подавления вывода заголовка при использовании флага `FMSG_ALLINONE` начните строку с символа `'\n'`.
FMSG_MB_OK	Дополнительно выводится кнопка <Ok>
FMSG_MB_OKCANCEL	Дополнительно выводятся кнопки <Ok> и <Cancel>
FMSG_MB_ABORTRETRYIGNORE	Дополнительно выводятся кнопки <Abort>, <Retry> и <Ignore>
FMSG_MB_YESNO	Дополнительно выводятся кнопки <Yes> и <No>
FMSG_MB_YESNOCANCEL	Дополнительно выводятся кнопки <Yes>, <No> и <Cancel>
FMSG_MB_RETRYCANCEL	Дополнительно выводятся кнопки <Retry> и <Cancel>
FMSG_NONE	Нулевой флаг

HelpTopic

Тема подсказки в файле помощи связанная с сообщением. Установите это значение в NULL если подсказка не требуется.

Items

Адрес массива с указателями на Unicode строки. Первая строка - заголовок сообщения, последние ButtonsNumber строк - кнопки, все остальные строки принадлежат телу сообщения.
Для отрисовки одинарной разделительной линии начните строку с символа с кодом 1 (L"\1").
Для отрисовки двойной разделительной линии начните строку с символа с кодом 2 (L"\2").
Смотрите также описание флага FMSG_ALLINONE.

ItemsNumber

Количество указателей в массиве Items. Минимальное значение - 2 строки.

ButtonsNumber

Количество заключительных строк, которые будут использоваться в качестве кнопок. При указании флагов FMSG_MB_* параметр ButtonsNumber игнорируется.

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

Функция возвращает -1, если пользователь отменил сообщение (или системе не удалось выделить достаточно памяти для внутренних буферов), или выбранный номер кнопки (для первой кнопки - 0, для второй - 1 и так далее).

Замечания

Если ButtonsNumber равен 0 (флаги FMSG_MB_* не используются) и выведенное сообщение больше не нужно, то плагин должен восстановить экран, используя функцию RestoreScreen или любым другим путём.
Если ButtonsNumber не равен 0, то экран восстанавливает сам Far Manager.
Диалог не выводится, если в качестве Items указан NULL или количество элементов меньше двух.
При указании флагов-кнопок FMSG_MB_* параметр ButtonsNumber игнорируется.
Кнопки могут иметь горячие клавиши.

При использовании флага FMSG_ALLINONE для корректной компиляции кода необходимо произвести явное преобразование типов:

  Info.Message(&MainGUID;,&MsgGUID;,
  FMSG_ALLINONE|FMSG_MB_OKCANCEL,
  L"HelpTopic",
  (const wchar_t * const *)L"Title\nItem1\nItem2\nItem3",
  0,0);

или

const wchar_t *Msg=L"Title\nItem1\nItem2\nItem3\nOk\nCancel";
Info.Message(&MainGUID;,&MsgGUID;,
  FMSG_ALLINONE,
  L"HelpTopic",
  (const wchar_t * const *)Msg,
  0,2);

Пример

Следующая функция выводит на экран диалог-подтверждение на удаление файла:

BOOL IsDeleted(wchar_t *filename)
{
  const wchar_t *Msg[5];

  Msg[0]=GetMsg(MTitle);       // заголовок сообщения
  Msg[1]=GetMsg(MIsDeleted);   // тело сообщения
  Msg[2]=filename;
  Msg[3]=GetMsg(MDelete);      // последние ButtonsNumber (2) строк - кнопки
  Msg[4]=GetMsg(MCancel);

  return Info.Message(&MainGUID;,&MsgGUID;,
               0,
               L"DeleteFile",
               Msg,
               sizeof(Msg)/sizeof(Msg[0]),
               2) == 0;
}

Причём, Info определяется как глобальная переменная:

struct PluginStartupInfo Info;

...а инициализируется она в функции SetStartupInfoW:

void WINAPI SetStartupInfoW(struct PluginStartupInfo *Info)
{
  ...
  ::Info=*Info;
  ...
}

Смотрите также:

DialogInit

previous page start next page