Листер плагин на Borland C++ Builder 6 для "начинающих"

Copyright © 22.04.2004 Евгений Савич, Mutex Ltd

Данная статья является попыткой обобщить опыт, полученный автором в процессе разработки плагина xBaseView на Delphi 7 для популярного файл менеджера Total Commander, когда пришлось столкнуться с проблемами, довольно неприятными программисту, привыкшему мощной поддержке VCL среды.

Задача: создать плагин для просмотра RTF файлов

Создаем проект DLL библиотеки и сохраняем его под именем ListSimpleBcb.bpr в отдельной папке, изменим расширение имени плагина на WLX в опциях проекта. Модуль Unit1.cpp сохраняем под именем ListSimple.cpp.

Плагин должен экспортировать из библиотеки три функции:
    ListGetDetectString,
    ListLoad,
    ListCloseWindow.

ListGetDetectString должна записать в параметр DetectString строку, которая содержит RTF.

ListLoad вызывает плагин для работы и передает параметры:
    ListerWin – дескриптор окна Листера;
    FileToLoad – полное имя RTF файла.

Плагин должен создать свое окно в качестве дочерней по отношению к окну Листера и вернуть дескриптор этого окна. Эту инициализацию мы будем осуществлять в функции ShowRTF:
    HWND ShowRTF(HWND ListerWin, char* FileToLoad);

ListCloseWindow требует от плагина завершения работы, передавая дескриптор окна плагина. Это освобождение ресурсов мы будем делать в функции HideRTF:
    void HideRTF(HWND PluginWin);

Надо добавить в проект форму, изменить ее имя на fmMain и сохранить модуль формы под именем unMain.pas. Эта форма и есть окно плагина. В модуле unMain можно удалить бесполезную глобальную переменную:
    extern PACKAGE TfmMain *fmMain;

Замечание: ПЛАГИН НЕ МОЖЕТ ИСПОЛЬЗОВАТЬ ГЛОБАЛЬНЫЕ ПЕРЕМЕННЫЕ! Потому что, пользователь может запустить сразу несколько его экземпляров, которые будут выполняться в одном и том же адресном пространстве.

Объект RichEdit1 обеспечивает всю работу с RTF файлом, поэтому бросив на форму компонент RichEdit, надо установить ему такие свойства:
    Align = alClient,
    ReadOnly = True,
    ScrollBars = ssBoth.

В окне плагина можно использовать контекстное меню, поэтому надо бросить на форму компонент PopupMenu и создать два пункта меню Help и About, назначив им клавиши F1 и F2, соответственно. Необходимо прикрепить контекстное меню объекту RichEdit1, установив свойство RichEdit1:
    PopupMenu = PopupMenu1.

Окно плагина является дочерним, следовательно, оно не должно иметь рамку и заголовок. Для этого надо переопределить виртуальную функцию CreateParams класса TCustomForm. Здесь, мы кроме настройки стилей окна:
    Params.Style = WS_CHILD | WS_MAXIMIZE & !WS_CAPTION & !WS_BORDER;

Зарезервируем память для хранения указателя на нашу форму:
    Params.WindowClass.cbWndExtra = sizeof(void *);

Указатель нужен функции HideRTF для корректного закрытия плагина. В функции ShowRTF мы сохраняем указатель в WinAPI структуре окна плагина следующим вызовом:
    SetWindowLong(fmMain->Handle, GWL_USERDATA, (LONG)p);

Позднее мы вытащим указатель из структуры, используя дескриптор нашего окна, который является параметром HideRTF, вызывая функцию GetWindowLong:
    GetWindowLong(PluginWin, GWL_USERDATA);

Чтобы создать дочернее окно воспользуемся статической функцией CreateParentedControl класса TWinControl, т.е. в теле функции ShowRTF воспользуемся следующим оператором:
    fmMain = (TfmMain *)(TWinControl::CreateParentedControl(__classid(TfmMain), ListerWin));

Для работы плагина нам понадобятся следующие данные: дескрипторы окон Тотал Командира и Листера, и режим работы плагина: в обычном окне или на одной из двух панелей Тотал Командира (так называемый Quick View – режим быстрого просмотра). Дескрипторы нужны, чтобы избежать краха по клавишам выхода Alt+X и для реагирования на быстрые клавиши Листера. Эти данные будем хранить, соответственно, в переменных TotCmdWin, ParentWin и QuickView. Добавим их определения в public раздел класса формы в файле unMain.h. Дескриптор окна Тотал Командира мы можем найти по имени класса этого окна (это не VCL класс!) с помощью WinAPI функции FindWindow.

Немного теорий. Особенностью библиотеки визуальных компонентов Borland VCL является использование глобального объекта "приложение" – Application. Этот Application имеет скрытое окно, которое должно быть владельцем всех окон приложения, что обеспечивает корректное поведение всех окон программы. И DLL библиотека плагина, и исполняемый EXE файл Тотал Командира имеют собственный глобальный объект Application, следовательно, требуется их синхронизация. Для этого надо присвоить дескриптор скрытого окна объекта Application исполняемого файла дескриптору объекта Application библиотеки. К сожалению, Тотал Командир, хотя он написан на Delphi, не передает нам дескриптор данного скрытого окна. (Может причиной этого является проблема версии компиляторов Delphi?). За неимением оного, вместо него будем использовать для синхронизации дескриптор окна Листера, в противном случае, наше модальное окно (например, окно About) поведет себя неестественно, оно появится на панели задач Windows. Эта синхронизация является задачей для функции ShowRTF.

Чтобы защитить, Тотал Командир от сбоев плагина, будем использовать событие OnException объекта Application, которое перехватывает необработанное исключение. Кинем на форму компонент ApplicationEvents, переименуем его на App и создаем обработчик события OnException, куда введем вызов функции MessageBox для выдачи сообщения о сбое. Сохранив проект и модуль, можно удалить из формы ненужный компонент ApplicationEvents. Установка адреса обработчика события в Application -> OnException также является задачей для функции ShowRTF.

Все готово для ShowRTF? Увы, "маленькая неточность" в Plugin API Тотал Командира (включая v.6.02) значительно усложняет нашу работу. Если пользователь откроет окно плагина, затем переключится на Тотал Командир и закроет Тотал Командир, то мы не получим вызов через ListCloseWindow для завершения своей работы. Вместо этого Тотал Командир или Листер (кто его знает?) уничтожает наше окно вызовом WinAPI функции DestroyWindow, а потом, то же самое попытается сделать наш объект Application, и в конечном счете плагин вылетает с нарушением защиты памяти (General Protection Fault)!

Если мы не будем делать вышеописанную синхронизацию, этой проблемы удалось бы избежать. Что ж, будем расплачиваться за это и поставим ловушку для перехвата сообщении, которое получает наше же окно. Не будем вдаваться в подробности Windows API, вкратце суть дела такова. Объявляем структуру TPlugInfo, где будем хранить данные, которые нужны для закрытия плагина. При инициализации выделяем память под эту структуру и заполняем ее. Определяем функцию HookDestroy, которая будет перехватывать оконные сообщения, чтобы среагировать на сообщение WM_DESTROY (уничтожение окна). Вызовом SetWindowLong(…, GWL_WNDPROC, …) подменяем стандартный обработчик оконных сообщений на функцию HookDestroy. Похожим вызовом SetWindowLong в функции завершения HideRTF обратно восстанавливаем прежний обработчик. Важно то, что когда функция HookDestroy поймает сообщение WM_DESTROY, она вызывает функцию завершения HideRTF точно так же, как это делает функция ListCloseWindow. В результате мы всегда успеваем нормально закрыть окно и убрать за собой, что, к примеру демонстрирует free(p) из HideRTF, освобождая память, выделенную в ShowRTF.

Остается создать диалоговую форму About, обработчики контекстного меню и обработчик RichEdit1KeyDown, который ловит нажатие специальных клавиш и передает их с помощью PostMessage в соответствующее окно. Если здесь не перехватывать клавиши Alt+X, это приведет к краху плагина.

Об отладке и тестировании плагина

Листер имеет встроенную возможность просмотра RTF файлов, поэтому перед запуском плагина надо отключить ее, сняв пометку у флага RTF в окне “Configure Lister”. Чтобы использовать интегрированный отладчик IDE BCB, закройте Total Commander, а в BCB через меню “Run/Parameters” откройте диалог и в поле Host Application введите путь к Total Commander с помощью кнопки [Browse]. Теперь можно запускать плагин из-под BCB.

Ссылка для скачивания архива с примером http://www.wincmd.ru/plugring/ListSimpleBcb.html или с DelphiPlus (17.7K).

PS. Уважаемый Читатель! Программирование – многовариантно и я никак не претендую на абсолютную истину. В качестве дополнительного материала, предлагаю Вам ознакомиться с исходными текстами плагина xBaseView – "Просмотр и правка FoxPro, dBase, Clipper, Visual FoxPro, Paradox, Access, Interbase, Firebird, Excel, BDE, ADO и ODBC баз данных", который предоставляется с исходными текстами, и где применяется аналогичный подход.

Copyright © 2004 Евгений Савич, Mutex Ltd