Описание механизма

1. Описание механизма.

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

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

1.1. Создание файла справки.

Файл справки должен содержать в отдельный htm файл на каждую ошибку, вначале этого файла идет собственно описание ошибки, а дальше перечислены возможные решения проблемы. Перед каждым решением желательно создать якорь (тег <a name='имя якоря'>), тогда при возникновении ошибки в общем случае, если нажали на кнопку помощи, появится сразу описание ошибки и решения ее, а если указали еще и якорь, то сразу откроется решение данной проблемы.

Эта структура очень похожа на структуру Календаря налогоплательщика (файл “Помощь бухгатеру\BuhCalendar. chm”), там для каждого месяца создан отдельный файл htm и в нем в таблице описано, что надо делать в данный день. Решения ошибки можно так же оформить в таблицу.

2. Описание использования.

2.1. Как создать свое сообщение об ошибке.

В ресурсах того модуля, в котором нужно показать сообщение об ошибке, создаем коллекцию записей с форматом “Коды ошибок”, если такой еще не создано, создаем в ней запись. Указываем уникальный код, сообщение об ошибке, и выбираем chm файл. Далее нужно указать страницу внутри chm файла, для этого, открыв файл справки на нужной странице, щёлкаем по ней правой кнопкой и выбираем "Свойства" (строка "Адрес").

2.2. Функции для отображения сообщения об ошибке.

2.2.1. C++

Синтаксис

bool ShowErrorByCode( int code, ... );

bool ShowErrorByCode( int code, const char* anchor, ... );

Описание

Показывают сообщение об ошибке по коду. Дополнительные параметры будут записаны в сообщение об ошибке с помощью функции printf.

Если ошибка с таким кодом не будет найдена, то будет показано сообщение “Ошибка с кодом <код_ошибки>!”.

Параметры

code – код ошибки

anchor – якорь, к которому надо перейти в файле справки.

Возвращает

Функция возвращает true, если ошибка с таким кодом найдена в коллекции записей, иначе false.

2.2.2. СБиС++

Синтаксис

ОшибкаПоКоду( Код[, Якорь] );

Описание

Показывает сообщение об ошибке по коду.

Если ошибка с таким кодом не будет найдена, то будет показано сообщение “Ошибка с кодом <код_ошибки>!”.

Параметры

Код(число) – код ошибки, сообщение о которой надо показать.

Возвращает

Ничего не возвращает.

2.3. Функции для отображения сообщения об ошибке (без кода).

2.3.1. C++

Синтаксис

void ShowError( const char *msg, const char* help, ... )

Описание

Показывают сообщение об ошибке. Дополнительные параметры будут записаны в сообщение об ошибке с помощью функции printf.

Параметры

msg – сообщение, которое надо показать.

help – путь к справке, которую надо показать при нажатии на кнопку.

Возвращает

Ничего.

2.2.2. СБиС++

Синтаксис

ОшибкаСПомощью( Сообщение, Помощь );

Описание

Показывает сообщение об ошибке по коду.

Если ошибка с таким кодом не будет найдена, то будет показано сообщение “Ошибка с кодом <код_ошибки>!”.

Параметры

Сообщение (строка) – текст ошибки, который надо показать.

Помощь (строка) – путь к справке.

Возвращает

Ничего не возвращает.

3. Реализация.

3.1. Описание формата “Коды ошибок”.

В поле “Код” хранится число, которое передается функции для показа этого сообщения об ошибке.

В поле “Текст” хранится само сообщение об ошибке.

Поля “ФайлCправки” и “Файл” определяют, какую страницу файла справки chm показать при нажатии на кнопку “Помощь” в окне сообщения об ошибке. В поле “ФайлСправки” хранится название самого файла chm, а в поле “Файл” название файл htm внутри этого файла. В поле “Файл” так же можно указать якорь, к которому надо перейти, для этого после окончания имени файла htm надо дописать ‘#’ и имя якоря.

3.2 Программная реализация.

Кнопка в сообщение добавляется в функции MsgBoxGeneral, для того чтобы она добавилась достаточно указать в последний параметр файл справки и раздел в нем, переданная строка будет просто передана функции “ОткрытьПомощь”, формат строки к разделу файла справки можно посмотреть в справке по этой функции. Такая реализация позволяет добавить эту кнопку в любое ваше сообщение. Для простоты использования создана функция “ShowError”, которая просто показывает сообщение об ошибке, переданное ей.

Функция

bool ShowErrorByCode( int code, const char* anchor, ... );

загружает RecCol с форматом “Коды ошибок” ищет в ней запись по коду, переданному функцию, получает из нее сообщение об ошибке, печатает в него все дополнительные параметры, переданные в функцию, формирует строку пути к разделу файла справки, и вызывает функцию MsgBoxGeneral. В случае если код не найден показывает сообщение “Ошибка с кодом <код_ошибки>!”.

Остальные функции просто вызывают функцию, описанную выше, передав вместо якоря NULL. Т. е. если вы определяете решение и в определенных случаях решение нельзя определить, можно просто передать NULL вместо якоря и не делать дополнительной проверки.

Функция “ОшибкаПоКоду” не принимает дополнительные параметры кроме кода, это связано с различной реализацией переменного числа параметров в СБиСе и С++, поэтому следует быть осторожней с сообщениями содержащими %, когда сообщение показывается с помощью функции “ОшибкаПоКоду”.