Класс FarMessage

Класс FarMessage представляет собой обертку вокруг сервисной функции FAR Message.

Использование

Класс поддерживает несколько вариантов использования, в зависимости от требуемой функциональности. Простейший способ использования - показ однострочного сообщения об ошибке с заголовком Error и одной кнопкой Ok:

FarMessage().ErrMsg (MCannotCreateListFile);

В качестве параметра метода ErrMsg может передаваться как строка (const char *), так и номер строки в LNG.

Использование этого варианта вызова требует, чтобы LNG-файл плагина соответствовал требованиям FARPlus (первый элемент LNG должен содержать строку Error или Ошибка, а второй элемент - Ok или Продолжить).

Если требуется показать сообщение из нескольких строк с кнопкой Ok, либо сообщение вообще без кнопок, наиболее удобен второй вариант использования: метод SimpleMsg().

FarMessage().SimpleMsg (FMSG_WARNING | FMSG_MB_OK, MError, 
                              ArcName,  ErrMsg, -1);

Первым параметром в эту функцию передаются флаги сообщения. В этом параметре также указываются кнопки, которые должны быть показаны в сообщении. Если плагин предназначен для работы с FAR 1.70, можно использовать любые стандартные константы FMSG_MB_*. Если же плагин должен быть совместимым с FAR 1.65 (макрос USE_FAR_170 не определен), можно использовать лишь флаг FMSG_MB_OK, который будет преобразован в стандартную кнопку Ok.

После этого в списке параметров указываются заголовок сообщения и произвольное количество строк текста. Заголовок и строки текста сообщения могут указываться как в виде строк (const char *), так и в виде номеров строк в LNG. Если требуется вывести сообщение без заголовка, вторым параметром должна быть передана пустая строка ("").

Последним параметром функции обязательно должен быть -1. Это является маркером, указывающим на то, что список параметров закончен.

Наконец, наиболее полные возможности становятся доступны при явном конструировании сообщения.

FarMessage msg;
msg.AddLine (MDelete);
msg.AddLine (MConfirmDelete);
msg.AddLine (pEntries [Selected]->DisplayName);
msg.AddButton (MDelete);
msg.AddButton (MCancel);
if (msg.Show() == 0) 
    RegDeleteKey (HKEY_LOCAL_MACHINE, pEntries [Selected]->SubkeyName);

При этом вначале создается экземпляр класса FarMessage (в качестве параметров конструктора можно передать флаги сообщения и название темы помощи, ассоциированной с сообщением). Далее в него последовательно добавляются строки (при помощи метода AddLine()) и кнопки (при помощи метода AddButton()). Первая добавленная строка становится заголовком сообщения.

После того, как конструирование сообщения завершено, сообщение выводится на экран при помощи метода Show(). Этот метод возвращает номер кнопки, нажатой пользователем, либо -1, если пользователь закрыл сообщение нажатием Esc.

Использование класса FarMessage имеет те же особенности, что и использование стандартной функции Message() из FAR API:

  1. В версиях FAR до 1.70 beta 3 включительно максимально допустимое количество элементов в сообщении (суммарное количество строк и кнопок) не может быть больше 13.
  2. Если сообщение содержит хотя бы одну кнопку, то оно показывается в модальном режиме, и после того, как пользователь нажал на кнопку, сообщение исчезает с экрана и старое содержимое экрана восстанавливается. Если сообщение не содержит кнопок, то функция Message() возвращает управление сразу, и разработчик плагина должен самостоятельно позаботиться о восстановлении старого содержимого экрана под сообщением.
  3. Для того, чтобы сообщение было показано на экране, оно должно содержать по крайней мере два элемента: заголовок (возможно, пустой) и одну строку текста.

Методы

FarMessage (unsigned int Flags=0, const char *HelpTopic=NULL)

Конструктор. Позволяет задать флаги сообщения (любые из констант FMSG_*, используемых функцией Message), а также тему помощи, которая будет ассоциирована с сообщением.

void AddLine (const char *Text)

void AddLine (int LngIndex)

Добавляет в сообщение строку текста, заданную либо в виде const char *, либо в виде номера строки в LNG. Первая добавленная строка становится заголовком сообщения.

void AddFmt (const char *FmtText, ...)

void AddFmt (int FmtLngIndex, ...)

Добавляет в сообщение строку текста, сформированную на основании указанной форматной строки и параметров. Первый параметр задает форматную строку либо ее индекс в LNG; последующие параметры соответствуют спецификаторам формата, содержащимся в форматной строке. Формат форматной строки тот же, что и для функции sprintf.

void AddSeparator()

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

int AddButton (const char *Text)

int AddButton (int LngIndex)

Добавляет к сообщению кнопку. Текст кнопки задается либо в виде const char *, либо в виде номера строки в LNG.

int Show()

Выводит сформированное сообщение на экран. Если сообщение содержит кнопки, возвращает номер кнопки, выбранной пользователем, или -1, если пользователь закрыл сообщение по Esc. Eсли сообщение не содержит кнопок, возвращает 0.

int SimpleMsg (unsigned int Flags, ...)

Функция для упрощенного показа сообщения. Конструирует сообщение, выводит его на экран и возвращает номер выбранной кнопки, -1, если сообщение закрыто по Esc, или 0, если сообщение не содержит кнопок. Более подробное описание дано в разделе "Использование".

int ErrMsg (const char *Text, int ExtraFlags = 0)

int ErrMsg (int LngIndex, int ExtraFlags = 0)

Функция для упрощенного показа сообщения об ошибке. Конструирует сообщение, выводит его на экран и возвращает номер выбранной кнопки или -1, если сообщение закрыто по Esc. Параметр ExtraFlags содержит дополнительные флаги, передаваемые в функцию Message() (флаг FMSG_WARNING установлен всегда). Более подробное описание дано в разделе "Использование".