[Папка Template]

В этой папке содержится готовый для сборки шаблон нового объекта с примерами условий событий (example conditions), действий (actions) и выражений (expressions). Шаблон состоит из нескольких файлов:

Common.h. Общий заголовочный файл, который нужно подключить ко всем Вашим файлам исходного кода. Содержит несколько определений, которые позволят ограничить Ваше расширение для определенных версий и определенных сборок CF.

Edittime.cpp. Содержит функции, вызываемые редакторами фрейма (Frame editor) и событий (Event editor).

Ext.def. Файл определения экспорта для линкера (export definition file). Этот файл очень важен: здесь перечислены все функции, к которым нужно получить доступ из CF. Если Вы включите функцию, вызываемую из CF, то убедитесь, что она также включена и в файле .def (удалите точку с запятой перед именем функции), поскольку CF знает только те имена, которые находятся в файле .def, и не осуществляет доступ к функциям через их декорированные имена.

Ext.rc. Файл ресурсов для Вашего проекта. Содержит все строки, рисунки, окна диалога объекта.

General.cpp. Содержит подпрограммы, которые вызываются во время редактирования (edit time) и во время выполнения (run time).

Main.cpp. Содержит действия (actions), условия (conditions) и выражения (expressions) для Вашего объекта.

Main.h. Файл определения для Вашего расширения, содержит структуры EDITDATA и RUNDATA, необходимые для редактирования и запуска объекта.

Runtime.cpp. Содержит функции, необходимые для запуска объекта, которые работают только во время выполнения (run time). Включает подпрограммы для отладчика, подпрограммы для отображения Вашего объекта во время выполнения приложения, и т. д.

Resource.h. Файл определения для ресурсов. Содержит идентификаторы разных элементов в файле ресурсов.

Template.sln. Файл решения (Solution file) для использования в среде разработки MS Visual C++ 2005 (или более новой версии).

Template.vcproj. Файл проекта для использования в среде разработки MS Visual C++ 2005 (или более новой версии).

Res\ExtIcon.bmp. Иконка для объекта: эта картинка используется для отображения объекта в окне объекта редактора фрейма и редактора событий. Удалите этот файл, если Вы рисуете свою иконку вручную с помощью функции MakeIconEx.

Res\ExtImg.bmp. Картинка объекта: будет использоваться для отображения объекта в редакторе фрейма. Удалите этот файл, если Вы рисуете объект вручную с помощью функции EditorDisplay.

[Папка Inc]

Папка Inc содержит все подключаемый файлы, необходимые для компиляции Вашего расширения.

Ccx.h. Этот файл содержит определения, используемые расширением и компилятором ресурсов. Вы должны подключить его в начало своего кода.

Ccxhdr.h. Этот файл сразу подключает все необходимые файлы. Вы должны подключить его в начало своего кода.

CfcError.h. Содержит некоторые коды ошибки, возвращаемые функциями из mmfs2.dll и в фильтрах.

CfcFile.h. Содержит декларации файловых функций в mmfs2.dll.

Cncf.h. Этот файл содержит основное определение для выполняемого кода (runtime). Содержит все структуры, объекты, действия и условия, используемые во время работы объекта. Он автоматически подключается из файла Ccxhdr.h.

Cncy.h. Содержит другие структуры для работы приложения (runtime) и среды CF (edittime). Он автоматически подключается из файла Ccxhdr.h.

Cncr.h. Маленький файл, который подключает все другие файлы. Он автоматически подключается из файла Ccxhdr.h.

Cnpdll.h. Содержит основную часть определений для mmfs2.dll. Он автоматически подключается из файла Ccxhdr.h.

Colors.h. Маленький файл, который содержит определения базовых цветов, используемых в программах (таких как BLACK, к примеру). Он автоматически подключается из файла Ccxhdr.h.

EvtCcx.h. Этот файл определяет структуры информации события, используемые в главном исходном коде расширения, чтобы определить действия (actions) и условия (conditions) событий. Он автоматически подключается из файла Ccxhdr.h.

Fill.h. Содержит структуры, используемые для функций заливки (Rectangle, Ellipse, и т. д.) в классе cSurface.

FilterMgr.h. Содержит базовый класс для менеджеров фильтров изображения и звука.

ImageFlt.h. Содержит менеджер фильтра изображения (image filter manager) и классы фильтра изображений (image filter classes).

ImageDefs.h. Игнорируйте этот файл, он присутствует только для поддержки совместимости с внутренними подключаемыми файлами Clickteam.

Palet.h. Содержит функции палитры в mmfs2.dll.

PictEdDefs.h. Содержит определения для редактора изображений (picture editor). Для использования в функциях mvEditImage и mvEditAnimation.

Props.h. Этот файл содержит определения новой системы свойств CF. Он автоматически подключается из файла Ccxhdr.h.

PType.h. Этот файл содержит определения некоторых типов переменных, используемых программой. Он автоматически подключается из файла Ccxhdr.h.

SndDefs.h. Игнорируйте этот файл, он присутствует только для поддержки совместимости с внутренними подключаемыми файлами Clickteam.

SoundFilter.h. Содержит класс фильтра звука (sound filter class).

SoundFilterMgr.h. Содержит класс менеджера фильтра звука (sound filter manager class).

StdDefs.h. Игнорируйте этот файл, он присутствует только для поддержки совместимости с внутренними подключаемыми файлами Clickteam.

Surface.h. Содержит класс cSurface class. Подключается файлом Common.h в шаблоне расширения (Extension template).

SurfaceDefs.h. Игнорируйте этот файл, он присутствует только для поддержки совместимости с внутренними подключаемыми файлами Clickteam.

TigsExt.hpp. Содержит некоторые полезные макросы, созданные для старого SDK стороннего производителя.

WinMacro.h. Набор макросов, определенных для Win32.

[Папка Lib]

Папка Lib содержит только один файл: Mmfs2.Lib. Он используется для линковки CF DLL к расширению, если это необходимо.

CF 2.5 может загрузить расширения Unicode или расширения не-Unicode, однако конечно же символы Unicode поддерживаются только расширениями Unicode, поэтому если Ваши расширения используют текст, то Вы должны портировать их для поддержки Unicode.

[Как преобразовать расширение, чтобы оно поддерживало Unicode]

Чтобы скомпилировать расширение Unicode, добавьте определения препроцессора _UNICODE и UNICODE в настройки своего проекта расширения. Если Вы не определите эти символы, то расширение будет скомпилировано в режиме не-Unicode.

Первое, что нужно сделать, это папку расширения MMF2 (extension folder) в папку Fusion25SDK/Extensions, и затем нужно:

• Отредактировать этот проект.
• Добавить в проект новые конфигурации Debug Unicode, Release Unicode и Runtime Unicode на основе конфигураций Debug, Release и Runtime.
• Для этих новых добавленных конфигураций добавить _UNICODE и UNICODE в определения для препроцессора.

Замечание 1: расширения Unicode устанавливаются в папки и Extensions\Unicode и Data\Runtime\Unicode, находящиеся в каталоге установки CF.

Замечание 2: если Вы используете MSVC++ 2005 или более новую версию этой системы разработки, то установите опцию "Threat wchar_t as Built-in Type" в значение "No" раздела "C++ / Language" настроек проекта, иначе будут появляться ошибки линковки, если Вы используете функции в DLL с текстовыми параметрами.

[Что делают символы _UNICODE и UNICODE]

Все структуры и функции Windows, которые используют текст, как и все структуры CF, существуют в 2 версиях: без поддержки Unicode и с поддержкой Unicode. Когда определены макросы _UNICODE и UNICODE, используется Unicode-версия структур, а когда эти макросы не определены, то используется non-Unicode версия.

Например, на самом деле Windows-функция DrawText не существует, и Windows содержит 2 функции DrawTextA и DrawTextW, и DrawText на самом деле макрос, который устанавливается на функцию DrawTextW, если определены _UNICODE/UNICODE, и устанавливается на DrawTextA, если _UNICODE/UNICODE не определены.

Структуры наподобие LOGFONT также макросы, и реальные структуры для него это LOGFONTA и LOGFONTW.

Такие функции и структуры не используют типы char или char*, они также используют вместо них макросы, поэтому для определения строк нужно соблюдать определенные правила, если хотите, чтобы расширение могло компилироваться и для поддержки Unicode, и без поддержки Unicode, если это необходимо. Поэтому замените определения символов и строк следующим образом:

char замените на TCHAR
LPSTR замените на LPTSTR
LPCSTR замените на LPCTSTR

Замечание: Вы все еще можете использовать char для символов, которые всегда не Unicode, или WCHAR для символов, которые всегда Unicode.

Функции из библиотеки C++ runtime также заменяются на макросы (это определено в tchar.h):

strlen заменяется на _tcslen
strcpy заменяется на _tcscpy
splitpath заменяется на _tsplitpath

... и так далее.

Для строк констант используйте макрос _T:

"это строка" замените на _T("это строка")

Если Ваше расширение компилируется в режиме Unicode, то _T("это строка") будет заменено на L"это строка", иначе это будет заменено на "это строка".

[Изменения в Main.h]

Структура EDITDATA. Эта наиболее проблематичная часть в преобразовании расширений. Если расширение не содержит и не использует никакого текста, то ничего делать не нужно. Если же текст используется, то нужно обеспечить поддержку 2 версий этой структуры:

• Структура EDITDATAA, non-Unicode, со значениями типа char (например, char array[2], LOGFONTA lfnt, и т. д.).
• Структура EDITDATAW, Unicode, со значениями типа WCHAR (например, WCHAR array[2], LOGFONTW lfnt, и т. д.).

И еще сделайте следующее определение:

#ifdef _UNICODE

 #define EDITDATA EDITDATAW

 #define LPEDATA LPEDATAW

#else

 #define EDITDATA EDITDATAA

 #define LPEDATA LPEDATAA

#endif

Внимание: не используйте в EDITDATA тип TCHAR.

Вы также также должны конвертировать Вашу структуру EDITDATA в Unicode и из Unicode в функции UpdateEditStructure, находящейся в модуле General.cpp: если Вы уже не используете функцию UpdateEditStructure в своем приложении, то реализуйте её так, чтобы она могла конвертировать не-Unicode EDITDATA из не-Unicode приложений в Unicode.

Вы можете проверить, загружен ли файл приложения как Unicode, вызовом функции mvIsUnicodeApp(pMV, pMV->mvEditApp). Если Вам не нужно преобразовывать текст из Unicode и в Unicode, то используйте функции MultiByteToWideChar и WideCharToMultiByte, и используйте в качестве кодовой страницы mvGetAppCodePage(pMV, pMV->mvEditApp).

Как все это делается, можно подсмотреть в примере Simple Control. И не забудьте разрешить эту функцию в файле .DEF!

Если уже используете UpdateEditStructure для обновления EDITDATA старых версий Вашего объекта, то это немного более сложнее: сначала Вам нужно обновить старую структуру EDITDATAA, и затем преобразовать обновленную структуру EDITDATAA в Unicode.

Структура RUNDATA. С ней ничего делать не нужно, просто используйте типы TCHAR, LPTSTR, и т. д.

[Изменения в других модулях исходного кода]

EditTime.cpp. Замените LPSTR (или LPCSTR) на LPTSTR (или LPCTSTR) в заголовочных файлах следующих функций:

GetObjInfos
GetHelpFileName
MakeIconEx
UsesFile
CreateFromFile
GetTextFont
GetCodeTitle
GetConditionTitle
GetActionTitle
GetExpressionTitle
GetConditionString
GetActionString
GetExpressionString
GetExpressionParam
GetParameterString

И замените функцию menucpy на следующий код:

void menucpy(HMENU hTargetMenu, HMENU hSourceMenu)
{

#ifndef RUN_ONLY
   int n, id, nMn;
   LPTSTR strBuf;
   HMENU hSubMenu;

   nMn = GetMenuItemCount(hSourceMenu);
   strBuf = (LPTSTR)calloc(80, sizeof(TCHAR));
   for (n = 0; n < nMn; n++)
   {
      if (0 == (id = GetMenuItemID(hSourceMenu, n)))
         AppendMenu(hTargetMenu, MF_SEPARATOR, 0, 0L);
      else
      {
         GetMenuString(hSourceMenu, n, strBuf, 80, MF_BYPOSITION);
         if (id != -1)
            AppendMenu(hTargetMenu, GetMenuState(hSourceMenu, n, MF_BYPOSITION), id, strBuf);
         else
         {
            hSubMenu = CreatePopupMenu();
            AppendMenu(hTargetMenu, MF_POPUP | MF_STRING, (uint)hSubMenu, strBuf);
            menucpy(hSubMenu, GetSubMenu(hSourceMenu, n));
         }
      }
   }
   free(strBuf);

#endif
}

Свойства (Properties). Не нужно делать изменений в свойствах, кроме строковых свойств. Вы использовали ранее CPropDataValue, чтобы передать/получить строки в/из менеджера свойств (CF property manager). Теперь здесь новый класс CPropStringValue. В функции GetPropValue:

   // Было раньше так:
   case PROPID_MYSTRING:
      return new CPropDataValue((LPCSTR)edPtr->myString);

   // Теперь стало так:
   case PROPID_MYSTRING:
      return new CPropStringValue(edPtr->myString);

В функции SetPropValue:

   // Было раньше так:
   case PROPID_MYSTRING:
      LPSTR ps = (LPSTR)((CPropDataValue*)pValue)->m_pData;

   // Теперь стало так:
   case PROPID_MYSTRING:
      LPCTSTR ps = ((CPropStringValue*)pValue)->GetString();

Runtime.cpp. Замените заголовочный файл функции GetDebugItem:

void WINAPI DLLExport GetDebugItem(LPTSTR pBuffer, LPRDATA rdPtr, int id)

General.cpp. Добавьте в функции GetInfos:

   case KGI_UNICODE:

#ifdef _UNICODE
      return TRUE;

#else
      return FALSE;

#endif

Это позволит системе CF узнать, каким является Ваше расширение: Unicode или non-Unicode. Тогда CF преобразует эти строки, если это необходимо, перед передачей из в функции Вашего расширения, или после получения строк из Вашего расширения.

Замените LPCSTR на LPCTSTR в функции GetDependencies() и в таблице, которую она возвращает, если это нужно (и добавьте _T() в имена dll в этой таблице). Замените LPSTR на LPTSTR в заголовочном файле функции UpdateFileNames.

Реализуйте структуру UpdateEditStructure, если это необходимо, так как это было описано выше.

Main.cpp. Действия/условия/выражения (Actions/Conditions/Expressions): если Ваше расширение Unicode, то оно будет принимать строковые параметры в формате Unicode (и будет возвращать строковые параметры в формате Unicode). Если Ваше расширение не Unicode, то оно будет получать/возвращать строки non-Unicode.

Замечание: параметр size в функциях RFUNCTION_GETSTRINGSPACE и RFUNCTION_GETSTRINGSPACE_EX указывается в байтах. Умножьте длину строки на sizeof(TCHAR), чтобы получить size байтах.

Изменения в runtime-структурах. Есть несколько изменений в некоторых внутренних структурах, особенно в структуре objInfoList. Теоретически Вам нужно заботиться о них только если Ваше расширение не Unicode, и Вы хотите получить прямой доступ к этим структурам.

1. Сделайте копию директории исходного кода Вашего расширения в папку MMF2SDK\Extensions.

2. Откройте Ваш файл проекта в Visual Studio, отредактируйте настройки проекта, выберите All Configurations.

2a. В combo-боксе Settings For выберите закладку C/C++, Preprocessor и введите ..\..\inc как дополнительную директорию для подключаемых файлов (Additional Include directory).
2b. Сделайте то же самое для закладки Resources.
2c. На закладке Link замените ..\lib\cncs32.lib на ..\..\lib\mmfs2.lib (обратите внимание: это mmfs2, не mmfs32).
2d. Рекомендуется: MMF2 runtime линкуется с MSVCRT.DLL, так что не нужно для Вашего расширения подключать код из библиотеки C runtime. Чтобы линковать расширение с MSVCRT.DLL, выберите закладку C/C++, Code Generation и выберите Multithreaded DLL. Имейте в виду, что некоторые расширения используют расширения C++, которые являются частью другой MS VC DLL, msvcp60.dll (например, если Вы используете объект "string"). Поскольку эта DLL может быть не установлена в старых системах, Вы должны сохранить старые установки (или поменять их на Multithreaded или Single-threaded, если Ваше расширение было линкован с этой DLL).

Если Вы используете Visual Studio 2005 или Visual Studio 2005 Express, то не должны использовать "Multithreaded DLL", так как файлы VS2005 runtime пока не присутствуют на некоторых машинах, и от пользователя может потребоваться загрузить и установить эти файлы runtime библиотек (2.5 мегабайта) с сайта microsoft.com.

Чтобы узнать, какие DLL требуются для Вашего расширения, запустите утилиту MS "Dependency Viewer", и загрузите Ваш файл .MFX.

3. Отредактируйте Ваш файл Common.h, сохранив свои определения (если они есть) и перезапишите остальную часть Common.h новым шаблоном. Также, если есть файл TigsExt.hpp в Вашей директории, то удалите его. Обновленная версия этого файла подключается из директории Inc.

4. Важно: функции UsesFile и CreateFromFile (модуль EditTime.cpp) теперь в качестве первого параметра имеют LPMV mV. В должны добавить его, иначе MMF упадет, если Вы бросите файл в редактор фрейма.

BOOL WINAPI DLLExport UsesFile (LPMV mV, LPCTSTR fileName)

void WINAPI DLLExport CreateFromFile (LPMV mV, LPCTSTR fileName, LPEDATA edPtr)

5. Важно: если используете RFUNCTION_SUBCLASSWINDOW, то количество окон, которое Вы передаете в эту функцию, теперь int вместо short int. Вы должны модифицировать свою структуру RUNDATA, чтобы она получила соответствующее изменение.

6. Менее важно:

• Некоторые функции MMFireSDK не находились в правильных файлах исходного кода. EnumElts, LoadObject, UnloadObject, Initialize, Free, UpdateEditStructure, UpdateFileNames должны быть перемещены в модуль General.cpp, так как они тоже вызываются из runtime, и их пустые клоны должны быть удалены из RunOnly.cpp.
• Заголовок параметров выражения теперь отображается в редакторе выражения (expression editor). Проверьте определение в своих расширениях, чтобы увидеть, имеют ли их параметры корректные имена, и реализуйте функцию GetExpressionParam (скопируйте её из шаблона в Edittime.cpp).
• mvGetExtUserData и mvSetExtUserData, используемые для сохранения глобальных данных в приложении, получили незначительные изменения. Вы должны передать параметр CRunApp*. Используйте либо CRunApp*, передаваемый как параметр функций StartApp / EndApp / StartFrame / EndFrame, или используйте rhPtr->rhApp, если Вы вызвали если Вы вызываете их из другой функции.

7. Отредактируйте Ваши строки ресурсов, поменяйте значение строки KPX_MARK на "MF2", и удалите строку KPX_CREATETITLE. Вы также можете удалить M_DESC, если не используете это, так как это не используется в MMF2.

8. Скомпилируйте Ваше расширение. Ниже см. описание и способы устранения возможных ошибок компиляции и линковки.

[Возможные ошибки линковки]

"Cannot find unique match for symbol xxx".

("Не получается найти уникальное совпадение для символа xxx"). Обычно эта проблема происходит с функциями Initialize и Free. Чтобы исправить их, либо добавьте extern "C" перед заголовком функции, например так:

extern "C" int WINAPI DLLExport Initialize(mv _far *knpV, int quiet)

Или замените определения Initialize и Free в своем файле .def:

Initialize = ?Initialize@@YGHPAVmv@@H@Z @25
Free = ?Free@@YGHPAVmv@@@Z @26

[Возможные ошибки компиляции]

"error C2664: 'DialogBoxParamA': cannot convert parameter 4 from etc."

("ошибка C2664: 'DialogBoxParamA': не могу преобразовать параметр 4 из ..."). Функция DialOpen теперь простой макрос (переопределение для DialogBoxParam). Удалите приведение типа FARPROC перед параметром оконной процедуры (window proc), чтобы избежать этой ошибки компиляции (также Вы можете напрямую использовать DialogBoxParam).

Ошибка в RunOnly.cpp, "loOiNum not a member of 'LO'" ("loOiNum не член 'LO'"). Удалите строку "loPtr->loOiNum = 0".

Структура rhy больше не существует. Как теперь получить доступ к переменным, которые были раньше членами этой структуры:

ryPtr->ryHmainWin замените на rhPtr->rhHMainWin
ryPtr->ryHeditWin замените на rhPtr->rhHEditWin

DibToImage и AddImage теперь не возвращают DWORD, но старшее слово всегда равно 0 в MMF2, так что Вы можете безопасно использовать приведение типа результата к WORD.

oiHFran больше не является членом ObjInfo. Вам не нужен этот параметр в MMF2, можно просто удалить все ссылки на него.

Члены oiEffect и oiEffectParam структуры ObjInfo теперь oiHdr.oiInkEffect и oiHdr.oiInkEffectParam. Если Вы их используете, то убедитесь, что наложили маску EFFECT_MASK на oiInkEffect.

GetKnpPalette был переименован в GetPaletteAppli.

Изменен параметр AntiA функций cSurface::Blit. Если используете этот параметр, то просто замените TRUE на BLTF_ANTIA для blit с анти-алиасингом.

Изменены параметры по умолчанию Blit и Stretch, так что это иногда может привести к ошибкам компиляции, или даже с проблемами компилятора, который ошибется с 2 функциями и не выдаст какое-либо предупреждение. Если встретитесь с любой ошибкой компиляции, просто добавьте параметры по умолчанию к функции (BMODE_OPAQUE, BOP_COPY, и т. д.).

Изменены параметры функции cSurface::DrawText. Вставьте счетчик символов (или -1) перед вторым параметром.

cSurface::BeginRaster и EndRaster заменены на LPBYTE cSurface::LockBuffer() и void cSurface::UnlockBuffer(LPBYTE spBuffer).

mvKncHelp была заменена на mvHelp.

Изменена функция mvEditImage. Редактор изображений (Picture Editor) теперь работает как диалоговое окно (dialog box), наподобие TGF, так что больше не нужно закрывать Ваше окно настройки (setup box) для редактирования изображения. Вы можете редактировать свою картинку примерно так:

EditImageParams eip;
eip.m_dwSize = sizeof(EditImageParams);
eip.m_pWindowTitle = NULL;
eip.m_dwImage = edPtr->nImage;
eip.m_dwOptions = PICTEDOPT_NOALPHACHANNEL | PICTEDOPT_CANBETRANSPARENT;
eip.m_dwFixedWidth = 32;
eip.m_dwFixedHeight = 32;

if ( spa->kv->mvEditImage(edPtr, &eip, hDlg) )
{
  edPtr->nImage = (WORD)eip.m_dwImage;
}

Символы PICTEDOPT_ определены в PicEdDefs.h.

Применение функции mvEditAnimation. Вы можете редактировать анимацию примерно так:

EditAnimationParams eap;
eap.m_dwSize = sizeof(EditAnimationParams);
eap.m_pWindowTitle = NULL;
eap.m_nImages = number_of_images;
eap.m_nMaxImages = max_number_of_images_in_image_list;
eap.m_nStartIndex = 0;
eap.m_pImages = image_list;   // LPWORD
eap.m_pImageTitles = NULL;
eap.m_dwOptions = PICTEDOPT_etc.;
eap.m_dwFixedWidth = 32;
eap.m_dwFixedHeight = 32;

if ( spa->kv->mvEditAnimation(edPtr, &eap, hDlg) )
{
   number_of_images = eap.m_nImages;
}

[Как реализовать новые функции MMF2 в Вашем расширении]

Функция MakeIcon все еще вызывается, если в Вашем расширении она есть, но это устарело. Если эта функции только загружает EXO_ICON bitmap из своих ресурсов, то Вы можете удалить её, MMF2 теперь загружает эту растровую картинку по умолчанию, и берет цвет первой точки как цвет прозрачности (transparent color). Иначе Вы можете заменить это функцией MakeIconEx, которая использует параметр cSurface и она проще для применения (и может поддерживать большее количество цветов).

Функция EditorDisplay теперь не обязательна. Если эта функция отсутствует, то MMF загружает и отображает EXO_IMAGE bitmap из ресурсов расширения. Цвет первой точки этой картинки считается цветом прозрачности (transparent).

Устарели функции AppendPopup, SelectPopup, ModifyObject, RebuildExt и EndModifyObject:

- Функции AppendPopup, RebuiltExt и EndModifyObject больше не вызываются.
- Функция SelectPopup все еще существует по соображениям совместимости, но Вы должны заменить её функцией EditObject, которая вызывается, когда пользователь делает двойной клик на объекте, или выбирает Edit в контекстном меню редактора фрейма (frame editor).
- ModifyObject все еще существует по соображениям совместимости (для расширений, размеры которых могут быть изменены), но Вы должны заменить её функцией SetEditSize, если Ваше расширение может менять размер, или удалить её, если расширение не может менять размер.

Если Вы хотите использовать новую систему свойств, то реализуйте следующие функции:

- GetProperties
- GetPropValue / SetPropValue
- GetPropCheck / SetPropCheck
- IsPropEnabled
- EditProp

Также определите идентификаторы свойств и определения в файле Edittime.cpp.

Если Вы хотите отобразить значения в отладчике (Debugger) для своего объекта, то реализуйте следующие функции:

- GetDebugTree
- GetDebugItem
- EditDebugItem

Также задайте идентификаторы элемента и определения в Runtime.cpp.

Реализуйте функцию GetHelpFileName в Edittime.cpp, с ней MMF может отобразить Ваш файл подсказки (help file), когда пользователь кликает на кнопку Help в меню свойств About объекта.

Замечание: окне диалога настройки (setup dialog box), если Вы все еще его используете, вызовите mV->mhHelp для отображения своего файла подсказки, например:

mV->mvHelp(GetHelpFileName(), HH_DISPLAY_TOPIC, (LPARAM)"index.html");

Если Вашему расширению для работы нужны внешние DLL (bass.dll и т. п.), то реализуйте функцию GetDependencies, и установите эти DLL в папку Data\Runtime системы MMF, чтобы они были включены в автономные приложения.

Если Вы хотите, чтобы Ваш объект поддерживал переходы (transitions), то можно это реализовать. Добавьте OEPREFS_TRANSITIONS к флагам OEPREFS в своем файле .h, и затем реализуйте GetRunObjectSurface. Если эта функция имеется, то она будет вызвана вместо DisplayRunObject, и возвратит поверхность (surface), которая отображается на экране.

Замечание: если Вы хотите, чтобы расширение использовало эффекты чернил (ink effects), то это можно реализовать вручную в DisplayRunObject, или Вы можете позволить системе MMF делать это автоматически, если реализуете GetRunObjectSurface, описанную ранее. Примечание: Вы также должны добавить опцию OEPREFS_INKEFFECT к своим опциям OEPREFS.

Если хотите реализовать для своего объекта точное детектирование коллизий, то Вам нужно реализовать функцию GetRunObjectCollisionMask. Эта функция должна вернуть маску монохромной коллизии. Для получения дополнительной информации обратитесь к документации по этой функции.

Если Ваш объект отображает текст, и Вы хотите поддерживать автоматические текстовые функции MMF:

- edittime (во время редактирования приложения): реализуйте функции GetTextCaps, GetTextFont, и т. д. (обратите внимание: они такие же в MMF 1.5).
- runtime (во время работы приложения): добавьте OEFLAG_TEXT в свои OEFLAGS, и реализуйте функцию GetRunObjectFont и другие функции.

Если Вы хотите ограничить использование расширения для некоторых версий или сборок MMF2, то добавьте следующий код к GetInfos:

case KGI_PRODUCT: 
   return PRODUCT_VERSION_STANDARD; // Стандартная систем MMF, или более новая

case KGI_BUILD: 
   return 219;                      // Сборка 219 или более новая

Если Ваше расширение загружает файлы, и Вы хотите реализовать поддержку новых двоичных встроенных файлов MMF2, то рассмотрите callback-функции mvOpenHFile, mvCloseHFile, mvGetFile, mvReleaseFile в Help-файле SDK [1].

Каждое расширение должно иметь свой собственный идентификатор. Этот идентификатор используется, например, когда Вы копируете (copy) / вставляете (paste) действия или условия (actions, conditions), связанные с объектами расширения. Если 2 расширения используют одинаковый идентификатор, то CF не будет знать, с каким расширением связать вставленные события. Таким образом первое, что Вам нужно сделать при создании своего расширения, это дать ему уникальный идентификатор.

Идентификатор определяется в файле Main.h. Идентификатор по умолчанию следующий:

#define IDENTIFIER MAKEID(S,A,M,2)

Просто поменяйте буквы в макросе MAKEID. Когда это будет сделано, удалите перед ним директиву #pragma message, чтобы удалить предупреждающее сообщение.

Иконки определены как растровые картинки (bitmaps), находящиеся во внешних файлах в формате BMP.

EXO_ICON (файл Exticon.bmp): иконка объекта, как он выглядит в окне "Object" редактора фрейма (Frame editor) и редактора событий (Event editor). Цвет первой точки картинки считается цветом прозрачности (transparent color). Если Вы хотите поменять цвет прозрачности, то реализуйте функцию MakeIconEx, загрузите свою иконку в параметр поверхности (surface) и поменяйте её цвет прозрачности функцией cSurface::SetTransparentColor.

EXO_IMAGE (файл Extimg.bmp): картинка объекта, отображаемая в игровом поле редактора фрейма. Вы должны сделать трехмерный вид этой иконки, чтобы её было проще идентифицировать на игровом поле. Цвет первой точки дает цвет прозрачности. Если Вы не хотите использовать цвет прозрачности, или хотите нарисовать свою иконку вручную (программно), то реализуйте функцию EditorDisplay.

В файле Ext.rc Вы найдете разные строки, описывающие объект, отображаемые в свойствах закладки About объекта (окно Property системы CF).

KPX_NAME и IDST_OBJNAME: содержат имя объекта.
IDST_AUTHOR должна содержать Ваше имя.
IDST_COPYRIGHT должна содержать Ваш копирайт.
IDST_COMMENT короткое описание объекта, отображаемое в окне диалога Insert New Object в редактора фрейма.
IDST_HTTP адрес Вашего веб-сайта.

Также Вы должны поменять информацию, содержащуюся в части "Version" ресурсов, просто отредактируйте эти поля и введите корректную информацию. Замечание: Вы должны увеличить номер версии каждый раз, когда выпускаете новый релиз своего расширения.

Перед тем, как перейти к непосредственному кодированию поведения расширения, Вы должны уделить время для того, чтобы определить, какие свойства должны быть у объекта. Например, должен ли он двигаться, использовать анимацию наподобие активного объект, должен ли использовать свои собственное окно, и т. д. В должны сообщить системе CF о всех свойствах Вашего объекта.

В подпрограмме GetRunObjectInfos расширение должно заполнить 2 поля флагов:

infoPtr->editFlags=OEFLAGS;
infoPtr->editPrefs=OEPREFS;

Первое поле флагов содержит текущие флаги для объекта (объект создается с использованием этих флагов, когда Вы бросаете его в игровое поле). Эти флаги могут быть изменены позже с использованием настройки расширения (extension setup).

Второе поле содержит флаги редактирования, и позволяет редактировать определенные свойства расширения таким образом, как нужно расширению.

OEFLAGS и OEPREFS определены в конце файла MAIN.H.

[OEFLAGS]

OEFLAGS очень важны для Вашего объекта расширения. CF использует эти флаги, чтобы определить, как обрабатывать объект - как спрайт или фон (backdrop object), должны ли быть добавлены свойства движения и т. д.

Главные свойства OEFLAGS

OEFLAG_MOVEMENTS. Флаг OEFLAG_MOVEMENTS добавляет объекту свойство передвижения (movement property). Если Вы используете этот флаг, то должны подключить структуры rCom и rMov к структуре RUNDATA объекта.

OEFLAG_ANIMATIONS. Флаг OEFLAG_ANIMATIONS добавляет объекту свойство анимации (animation property), основанное на спрайтах (sprite-based). Если используете этот флаг, то должны подключить структуры rCom и rAni к структуре RUNDATA объекта.

Если у объекта есть оба флага OEFLAG_ANIMATIONS и OEFLAG_SPRITE, то отображение будет автоматически выполняться системой CF. Таким образом, Вам не нужно определять подпрограмму рисования в своем расширении.

OEFLAG_VALUES. Флаг OEFLAG_VALUES добавляет объекту свойство значения (value property), которое содержит 26 изменяемых значений и 10 изменяемых строк. Если используете этот флаг, то должны добавить структуру rVal в структуру RUNDATA объекта.

Свойства отображения OEFLAGS

OEFLAG_BACKGROUND. OEFLAG_BACKGROUND говорит CF отображать этот объект посередине объектов фона (background objects).

Замечание: этот флаг должен использоваться с осторожностью. Используйте его для объектов, которые не обновляются очень часто, и которые не перемещаются. Всякий раз, когда объект перемещается, перерисовывается весь экран. Объект Picture является примером объекта, который использует подпрограмму OEFLAG_BACKGROUND. Этот флаг не должен использоваться вместе с OEFLAG_SPRITES и OEFLAG_QUICKDISPLAY, и т. п.

OEFLAG_SPRITES. OEFLAG_SPRITES говорит CF обрабатывать этот объект расширения как спрайт. Если также установлен флаг OEFLAG_ANIMATIONS, то CF будет использовать реальные спрайты для отображения этого объекта, и Вам не нужно для этого писать ни одной строки кода. Будет иметь эффект только OEFLAG_BACKSAVE.

OEFLAG_BACKSAVE. CF будет сохранять фон объекта, если этот флаг установлен, и не будет сохранять этот фон, если флаг не установлен. Сохраняемая зона вычисляется по координатам объекта и полям hoImgXHot, hoImgYHot, hoImgWidth, hoImgHeight, возвращаемым подпрограммой HandleRunObject.

OEFLAG_INTERNALBACKSAVE. Если установлен флаг OEFLAG_INTERNALBACKSAVE, и также установлен флаг OEFLAG_BACKSAVE, то CF будет вызывать подпрограммы сохранения фона расширения (extension background saving routines, которые должны быть определены). SaveBackground должна сохранять background в буфер, и RestoreBackground должна восстанавливать сохраненный буфер по тем же самым координатам. KillBackground должна очищать буфер из памяти.

Если Вы используете функции SaveRect / RestoreRect / KillRect из mmfs2.dll, то можете использовать поле hoBackSave структуры headerObject. Или Вы можете использовать поверхность (surface) для сохранения фона.

OEFLAG_QUICKDISPLAY. Отображение объекта как реальных спрайтов может значительно замедлить Ваше приложение. Если Ваш объект отображается медленно (например, Вы создали большой текстовый объект с использованием многих текстовых функций Windows), то каждый раз, когда другой спрайт отображается спереди этого объекта, то объект должен быть очищен и перерисован. Это приведет к тому, что Ваше приложение будет работать очень медленно.

Чтобы не перерисовывать объект все время, используйте флаг QUICKDISPLAY. Этот флаг можно использовать только совместно с флагом OEFLAG_SPRITE. Такой спрайт удаляется из главного списка спрайтов, но рисуется только поверх фона. Когда спрайт поступает на верх, он не перерисовывается. Таким образом, Вы можете отобразить большой текст при движущихся спрайтах на полной скорости.

Объекты QUICKDISPLAY могут или не могут сохранить фон в зависимости от флагов OEFLAG_BACKSAVE и OEFLAG_INTERNALBACKSAVE. Одна из вещей, которые эти флаги не делают правильно, это обработка сохранения фона, при пересечении друг друга. Некоторые часть второго объекта могут или не могут быть сохранены как часть фоновой сохраняемой области, и наоборот. В результате не помещайте объекты quickdisplay один поверх другого.

Не использование OEFLAG_SPRITE или OEFLAG_BACKGROUND. Если не используете флаг OEFLAG_SPRITE или OEFLAG_BACKGROUND, то Вы не можете получить прямой доступ к экрану CF. Это не означает, что Вы не можете ничего отображать, Ваша подпрограмма DisplayRunObject может использоваться для открытия (open), перемещения (move) или изменения размера окна поверх экрана CF. Разработчики реально используют эту технику для объектов AVI, QuickTime, Button, List, Edit, Combo, и всех объектов с окном.

Другие флаги

OEFLAG_TEXT. Флаг OEFLAG_TEXT добавляет меню "Text" в действия (actions), условия (conditions) и выражения (expressions). Этот пункт меню содержит условия наподобие "IsBold", "IsItalic" и т. д., действия наподобие "Set font name" (установить имя шрифта), "Set italic" (установить наклонный вид шрифта), "Set bold" (установить толстый вид шрифта) и т. д. Если хотите реализовать этот флаг (если Ваш объект текстовый), то нужно определить 4 функции в исходном коде Вашего расширения: "GetRunObjectFont", "SetRunObjectFont", "GetRunObjectTextColor" и "SetRunObjectTextColor". Эти функции вызываются основным кодом работающего приложения (main runtime) для изменения/запроса данных шрифта и цвета шрифта, используемого в Вашем объекте. Этот флаг сейчас используется в объектах Button, Clock, Edit, List, ListView и других.

OEFLAG_DISPLAYINFRONT. Если Вы установили флаг OEFLAG_DISPLAYINFRONT, то объект будет отображен спереди всех других объектов в редакторе. Вы должны использовать этот флаг, когда Ваш объект отображается как окно, так чтобы редактор учитывал отображение, которое Вы получаете в приложении.

OEFLAG_WINDOWPROC. Если Ваш объект нуждается в перехвате оконных сообщений CF, то Вы должны установить флаг OEFLAG_WINDOWPROC. CF будет вызывать подпрограмму "WindowProc" в объекте расширения. См. раздел "How to control a window from an extension".

OEFLAG_TABSTOP. Элементы управления интерфейса пользователя (Controls), такие как объект Edit или объект List, нуждаются в активизации клавишей TAB. Используйте флаг OEFLAG_TABSTOP, если хотите, чтобы Ваш объект перехватывал команды табуляции.

OEFLAG_SCROLLINGINDEPENDANT. Если установлен флаг OEFLAG_SCROLLINGINDEPENDANT, то объект не будет следовать игровому полю, когда оно прокручивается. Таким образом, объект останется статическим на экране, наподобие объекта Score (очки игрока) или объекта Lives (жизни игрока).

OEFLAG_NEVERKILL. Установите флаг OEFLAG_NEVERKILL, чтобы предотвратить удаление объекта, если он уйдет далего от границ игрового поля.

OEFLAG_RUNBEFOREFADEIN. Этот флаг позволяет объекту расширения быть созданным перед переходом постепенного появления изображения (fade-in transition). Этот флаг устанавливается пользователем через свойство Create Before Fade-In Transition.

OEFLAG_MANUALSLEEP. Обычно объект деактивируется, если он уходит слишком далеко из окна отображения - он все еще существует, но удаляется из окна отображения. Принятие решения о том, должен ли быть деактивирован этот объект, обычно осуществляет CF. Если объект не управляется игроком, и не является частью детектирования столкновения (collision detection), то он может быть деактивирован. Если нет, то он будет оставаться активным, даже если уйдет за границы области отображения. OEFLAG_MANUALSLEEP меняет этот процесс на ручной режим. В этом случае флаг OEFLAG_NEVERSLEEP используется как триггер, и если этот флаг установлен, то объект никогда не деактивируется.

Изменения флагов. Какой флаг можно изменить в диалоге настройки (setup dialog)?

Окно диалога настройки (или подпрограммы свойства SetPropValue/SetPropCheck) Вашего объекта расширения можно использовать для изменения любого из флагов, кроме следующих:

OEFLAG_MOVEMENTS
OEFLAG_ANIMATIONS
OEFLAG_VALUES
OEFLAG_BACKGROUND
OEFLAG_SPRITE
OEFLAG_TEXT

Эти флаги устанавливаются только один раз для каждого объекта. Так что пожалуйста обратите внимание, что некоторые из этих флагов сохранены в файле MFA, так что если Вы поменяете их, то возможно придется удалить и заново создать эти экземпляры Вашего объекта, чтобы эти изменения были учтены.

В соответствии с флагами, которые используете, Вы должны задать определенные структуры в своей структуре RUNDATA. Для дополнительной информации см. "Важные структуры".

Важные структуры. Эти структуры Вы должны использовать в своей структуре RUNDATA. Базовая структура RUNDATA должна содержать структуру headerObject в качестве первого элемента:

typedef struct tagRDATA
{
   headerObject rHo;
} RUNDATA;

Если установлены флаги OEFLAG_MOVEMENTS, OEFLAG_ANIMATIONS или OEFLAG_SPRITES, то Вы должны добавить структуру rCom после структуры rHo:

typedef struc tagRDATA
{
   headerObject rHo;
   rCom rc;
} RUNDATA;

Если также установлен флаг OEFLAG_MOVEMENTS, то Вы должны добавить структуру rMvt сразу после структуры rCom.

typedef struc tagRDATA
{
   headerObject rHo;
   rCom rc;
   rMvt rm;
} RUNDATA;

Вот различные случаи:

OEFLAG_MOVEMENTS
headerObject rHo;
rCom rc;
rMvt rm;

OEFLAG_ANIMATIONS
headerObject rHo;
rCom rc;
rAni ra;

OEFLAG_SPRITE
headerObject rHo;
rCom rc;
rSpr rs;

OEFLAG_VALUE
headerObject rHo;
rVal rv;

OEFLAG_MOVEMENTS | OEFLAG_ANIMATIONS
headerObject rHo;
rCom rc;
rMvt rm;
rAni ra;

OEFLAG_MOVEMENTS | OEFLAG_ANIMATIONS|OEFLAG_SPRITE
headerObject rHo;
rCom rc;
rMvt rm;
rAni ra;
rSpr rs;

Если вышеуказанные комбинации включают OEFLAG_VALUE, то Вы должны поместить rVal как последний элемент.

Помните:

• Должен быть представлен элемент rCom, если используются флаги OEFLAG_MOVEMENTS, OEFLAG_ANIMATIONS или OEFLAG_SPRITES.
• Должен быть представлен элемент rMvt, если используется OEFLAG_MOVEMENTS. Элемент rMvt должен идти непосредственно после rCom.
• Элементы rAni, rSpr и rVal всегда используются в этом порядке.

[OEPREFS]

Флаги OEPREFS управляют некоторыми свойствами, отображаемыми CF в окне редактора свойств (Property window). Каждая опция управляется соответствующей опцией OEFLAG_ в поле hoOEFlag.

OEPREFS_BACKSAVE. OEPREFS_BACKSAVE разрешит опцию "Save background", сохранить задний фон (OEFLAG_BACKSAVE).

OEPREFS_BACKEFFECTS. OEPREFS_BACKEFFECTS разрешит опцию эффектов очистки фона, если установлен флагOEPREFS_BACKSAVE.

OEPREFS_QUICKDISPLAY. OEPREFS_QUICKDISPLAY разрешит опцию быстрого отображения (OEFLAG_QUICKDISPLAY).

OEPREFS_SCROLLINGINDEPENDANT. OEPREFS_SCROLLINGINDEPENDANT разрешит опцию следования за игровым полем (Follow the playfield, OEFLAG_SCROLLINGINDEPENDANT).

OEPREFS_LOADONCALL. OEPREFS_LOADONCALL разрешит опцию "load on call" (загрузка при вызове). Имейте в виду, что эта опция не имеет эффекта на объектах расширений.

OEPREFS_GLOBAL. OEPREFS_GLOBAL разрешит опцию "global object" (глобальный объект). Имейте в виду, что эта опция не имеет эффекта на объектах расширений.

OEPREFS_SLEEP. OEPREFS_SLEEP разрешит опции ручного входа в сон (manual sleep, OEFLAG_MANUALSLEEP).

OEPREFS_KILL. OEPREFS_KILL разрешит уничтожение (Destroy), если объект далеко от игрового поля (OEFLAG_NEVERKILL).

OEPREFS_INKEFFECTS. OEPREFS_INKEFFECTS разрешит свойства эффекта чернил (Ink Effect).

OEPREFS_TRANSITIONS. OEPREFS_TRANSITIONS разрешит свойства переходов (Transitions). Вы должны реализовать в своем объекте функцию GetRunObjectSurface.

OEPREFS_FINECOLLISIONS. OEPREFS_FINECOLLISIONS разрешит опцию точного детектирования столкновений (Collisions / Use Fine Detection). Вы должны реализовать в своем объекте функцию GetRunObjectCollisionMask.

[Примеры объектов и флагов]

Без вывода на экран:

Ini object

• OEFLAG_DISPLAYINFRONT
• 0

MCI object

• OEFLAG_DISPLAYINFRONT
• 0

Window control object

• OEFLAG_DISPLAYINFRONT
• 0

CD Audio object

• OEFLAG_DISPLAYINFRONT
• 0

Print object

• OEFLAG_DISPLAYINFRONT
• 0

Mixer object

• OEFLAG_DISPLAYINFRONT
• 0

ODBC object

• OEFLAG_DISPLAYINFRONT
• 0

SEARCH object

• OEFLAG_DISPLAYINFRONT
• 0

Открытие элемента управления. Объекты, открывающие элемент управления интерфейса пользователя (control) в окне фрейма:

Button object

• OEFLAG_WINDOWPROC | OEFLAG_DISPLAYINFRONT | OEFLAG_TABSTOP | OEFLAG_MOVEMENT | OEFLAG_TEXT
• OEPREFS_GLOBAL | OEPREFS_SCROLLINGINDEPENDANT

List object

• OEFLAG_WINDOWPROC | OEFLAG_DISPLAYINFRONT | OEFLAG_TABSTOP | OEFLAG_MOVEMENT | OEFLAG_TEXT
• OEPREFS_GLOBAL | OEPREFS_SCROLLINGINDEPENDANT

Combo object

• OEFLAG_WINDOWPROC | OEFLAG_DISPLAYINFRONT | OEFLAG_TABSTOP | OEFLAG_MOVEMENT | OEFLAG_TEXT
• OEPREFS_GLOBAL | OEPREFS_SCROLLINGINDEPENDANT

Открытие окна. Объекты, открывающие окно в окне фрейма:

AVI object

• OEFLAG_MOVEMENTS | OEFLAG_WINDOWPROC | OEFLAG_DISPLAYINFRONT
• OEPREFS_GLOBAL

QT3 object

• OEFLAG_MOVEMENTS | OEFLAG_DISPLAYINFRONT | OEFLAG_WINDOWPROC
• OEPREFS_GLOBAL

Рисование на экране. Объекты, непосредственно рисующие в окне фрейма:

Anim object

• OEFLAG_SPRITES | OEFLAG_BACKSAVE | OEFLAG_MOVEMENTS | OEFLAG_VALUES
• OEPREFS_BACKSAVE | OEPREFS_BACKEFFECTS | OEPREFS_KILL | OEPREFS_SCROLLINGINDEPENDANT | OEPREFS_INKEFFECTS | OEPREFS_TRANSITIONS | OEPREFS_FINECOLLISIONS

Hiscore object

• OEFLAG_SPRITES | OEFLAG_QUICKDISPLAY | OEFLAG_BACKSAVE | OEFLAG_TEXT
• OEPREFS_GLOBAL | OEPREFS_BACKSAVE | OEPREFS_BACKEFFECTS

Date & Time object

• OEFLAG_SPRITES | OEFLAG_MOVEMENTS | OEFLAG_QUICKDISPLAY | OEFLAG_BACKSAVE | OEFLAG_SCROLLINGINDEPENDANT | OEFLAG_TEXT
• OEPREFS_GLOBAL | OEPREFS_QUICKDISPLAY | OEPREFS_BACKSAVE | OEPREFS_BACKEFFECTS | OEPREFS_SCROLLINGINDEPENDANT

1. С среде Visual C++ откройте настройки проекта.

2. Убедитесь, что выбрана конфигурация отладки (Debug Unicode), и выбрана секция отладки (Debugging) настроек.

3. Введите путь до копии установки CF в поле ввода Command.

4. Введите директорию копии установки CF в поле ввода Working directory.

5. В разделе настроек линкера (Linker) введите в качестве пути до выходного файла (Output File) путь до файла расширения в каталоге Extensions\Unicode Вашей копии каталога установки CF. Измените права на запись в этот файл, если на Вашем компьютере разрешена работа системы UAC, чтобы Вы могли осуществить сборку этого файла.

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

Отладка расширения во время выполнения приложения, где используется расширение, несколько сложнее, так как CF запускает процесс runtime как внешнюю программу, но это важный шаг для отладки условий и действий. Выполните следующие шаги:

1. Откройте папку Extensions \ Help \ Misc Documentation в SDK, и сделайте копию файла CopyRun.Bat в корневую папку CF, где находится файл MMF2U.EXE.

2. Если папка C:\Temp еще не существует, то создайте её в корне диска C:. В этой директории создайте папку Rt. Примечание: также можно отредактировать файл CopyRun.bat, и поменять имя директории, см. далее.

3. Загрузите файл проекта Вашего расширения в Visual C++, откройте настройки проекта (Project Settings), перейдите в раздел отладки (Debugging). В опции командной строки (Command line), введите путь до файла EdRt.exe, который находится в папке Data\Runtime\Unicode каталога установки системы CF.

4. В строке опции аргумента приложения (Program argument) введите "/fC:\Temp\Rt\App0.ccn".

long WINAPI DLLExport Condition(LPRDATA rdPtr, long param1, long param2)

Каждое условие, которое Вы определяете, должно иметь свою подпрограмму. Эта подпрограмма вызывается системой CF, когда условие требует анализа.

Параметры:

LPRDATA rdPtr указатель на run-time структуру объекта.
long param1 первый параметр, если он необходим.
long param2 второй параметр, если он необходим.

Возвращаемое значение: FALSE, если условие не удовлетворяется, TRUE если удовлетворяется. Если один из параметров PARAM_COMPARAISON или PARAM_CMPSTRING, то возвращаемое значение должно быть результатом сравнения.

Замечания:

- Эта подпрограмма должна быть как можно более быстрой, потому что она может вызываться довольно часто при работе приложения.
- Параметры param1 и param2 определяются только если Вы укажете параметр в массиве conditionsInfos, в начале модуля MAIN.CPP.
- Когда используется больше 2 параметров, Вы должны использовать макросы CNC_GetIntParameter, CNC_GetStringParameter или CNC_GetFloatParameter для захвата параметров. Для дополнительной информации см. секцию "CallBack Functions / Runtime / Others".
- Каждая подпрограмма должна иметь указатель на саму себя в массиве ConditionJumps.

Пример, условие без параметров:

long WINAPI DLLExport Condition(LPRDATA rdPtr, long param1, long param2)
{
   return TRUE;         // это условие всегда верное
}

Пример, условие с одним параметром:

long WINAPI DLLExport Condition(LPRDATA rdPtr, long param1, long param2)
{
   return (param != 0); // это условие верно, если параметр не равен 0
}

Пример, условие с двумя параметрами:

long WINAPI DLLExport Condition(LPRDATA rdPtr, long param1, long param2)
{
   return (param1==param2);   // это условие верно, если параметры идентичны
}

Пример, условие с тремя параметрами:

long WINAPI DLLExport Condition(LPRDATA rdPtr, long param1, long param2)
{
    int p1 = CNC_GetIntParameter(rdPtr);
    int p2 = CNC_GetIntParameter(rdPtr);
    int p3 = CNC_GetIntParameter(rdPtr);
    
   return (p1==p2 && p1==p3); // это условие верно, если параметры идентичны
}

short WINAPI DLLExport Action(LPRDATA rdPtr, long param1, long param2)

Каждое действие, которое Вы определяете, должно иметь свою подпрограмму. Эта подпрограмма вызывается системой CF, когда действие запускается приложением.

Параметры:

LPRDATA rdPtr указатель на run-time структуру объекта
long param1 первый параметр, если он необходим
long param2 второй параметр, если он необходим

Возвращаемое значение: должен быть возвращен 0.

Замечания:

- Делайте Вашу подпрограмму обработки действия максимально быстрой, насколько это возможно, потому что она может вызываться довольно часто при работе приложения.
- Параметры param1 и param2 определяются только если Вы укажете параметр в массиве actionsInfos, в начале модуля MAIN.CPP.
- Когда используется больше 2 параметров, Вы должны использовать макросы CNC_GetIntParameter, CNC_GetStringParameter или CNC_GetFloatParameter для захвата параметров. Для дополнительной информации см. секцию "CallBack-функции / Runtime / Другие функции".
- Каждая подпрограмма должна иметь указатель на саму себя в массиве ActionJumps.
- Подпрограмме действия не разрешено рисовать что-либо на экране. Это должно осуществляться путем вызова процесса перерисовки объекта, что делается при переходе приложения к следующему экрану и обновлению с вызовом подпрограммы DisplayRunObject. Эту работу делает для Вас вызов callRuntimeFunction(rdPtr, RFUNCTION_REDRAW, 0, 0).

Пример, действие без параметров:

short WINAPI DLLExport Action(LPRDATA rdPtr, long param1, long param2)
{
   Beep();
   return 0;
}

Пример, действие с одним параметром:

short WINAPI DLLExport Action(LPRDATA rdPtr, long param1, long param2)
{
   if ( param1 == 0 )
      Beep(0);
   else
      Beep(1);
   return 0;
}

Пример, действие с двумя параметрами:

short WINAPI DLLExport Action(LPRDATA rdPtr, long param1, long param2)
{
   Beep(param1, param2);
   return 0;
}

Пример, действие с тремя параметрами:

short WINAPI DLLExport Action(LPRDATA rdPtr, long param1, long param2)
{
   int p1 = CNC_GetIntParameter(rdPtr);
   int p2 = CNC_GetIntParameter(rdPtr);
   int p3 = CNC_GetIntParameter(rdPtr);

   Beep(p1, p2, p3);

   return 0;
}

long WINAPI DLLExport Expression(LPRDATA rdPtr,long param1)

Каждое выражение (expression), которое Вы задаете для своего расширения, должно иметь собственную подпрограмму обработки выражения. Эта подпрограмма вызывается системой CF, когда это выражение нуждается в вычислении.

Параметры:

LPRDATA rdPtr указатель на run-time структуру объекта.
long param1 первый параметр, если он необходим.

Возвращаемое значение: если выражение числовое, то подпрограмма выражения должна возвратить вычисленное значение типа long. Если выражение строковое, то подпрограмма должна вернуть указатель на вычисленную строку.

Важный момент: если выражение возвращает строку, то оно должно также установить флаг HOF_STRING в поле rdPtr->rHo.hoFlags, вот так:

rdPtr->rHo.hoFlags |= HOF_STRING;

Вы должны сделать это перед возвратом из функции выражения (это должно быть после захвата параметров). Установите флаг HOF_FLOAT, если выражение возвращает float (предупреждение: не делайте приведение типа float к long, см. пример ниже).

Замечания:

- Делайте Вашу подпрограмму обработки выражения максимально быстрой, насколько это возможно, потому что она может вызываться довольно часто при работе приложения.
- Для получения параметров используйте макросы CNC_GetFirstExpressionParameter и CNC_GetNextExpressionParameter. Для дополнительной информации см. секцию "CallBack Functions / Runtime / Others".

Пример, выражение с 1 параметром:

long WINAPI DLLExport Expression(LPRDATA rdPtr,long param1)
{
   long p1 = CNC_GetFirstExpressionParameter(rdPtr, param1, TYPE_INT);

   // В этом месте выполняется вычисление выражения:
   return p1 * 2;
}

Пример, выражение с 2 параметрами:

long WINAPI DLLExport Expression(LPRDATA rdPtr,long param1)
{
   long p1 = CNC_GetFirstExpressionParameter(rdPtr, param1, TYPE_INT);
   long p2 = CNC_GetNextExpressionParameter(rdPtr, param1, TYPE_INT);

   // В этом месте выполняется вычисление выражения:
   return p1+p2;
}

Пример, выражение с 3 параметрами:

long WINAPI DLLExport Expression(LPRDATA rdPtr,long param1)
{
   long p1 = CNC_GetFirstExpressionParameter(rdPtr, param1, TYPE_INT);
   long p2 = CNC_GetNextExpressionParameter(rdPtr, param1, TYPE_INT);
   long p3 = CNC_GetNextExpressionParameter(rdPtr, param1, TYPE_INT);

   // В этом месте выполняется вычисление выражения:
   return p1+p2+p3;
}

Пример, выражение, которое возвращает строку:

long WINAPI DLLExport Expression(LPRDATA rdPtr,long param1)
{
   long p1 = CNC_GetFirstExpressionParameter(rdPtr, param1, TYPE_INT);
   // тут может быть получение других параметров
   // Установка флага строки:
   rdPtr->rHo.hoFlags |= HOF_STRING;

   // Возврат строки:
   return (long)_T("Hello world");
}

Пример, выражение, которое возвращает float:

long WINAPI DLLExport Expression(LPRDATA rdPtr,long param1)
{
   long p1 = CNC_GetFirstExpressionParameter(rdPtr, param1, TYPE_INT);
   // тут может быть получение других параметров
   // Установка флага "Float":
   rdPtr->rHo.hoFlags |= HOF_FLOAT;
   // Возврат float:
   float fResult = 1.0f;

   // Не возвращайте fResult напрямую, так как это значение должно 
   // быть преобразовано в long:
   return *((long*)&fResult);
}

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

• Пункт меню для всплывающего меню действий условия.
• Отображаемая строка, которую CF может показать для действий или условий в списке редактора событий.

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

Важное замечание: определение строки это одна из вещей, однако Вы должны редактировать файл ресурса для изменения идентификатора для новой опции меню: CF сравнивает этот идентификатор выбранной опции с граничными значениями и детектирует, чем является последняя выбранная опция с этим методом - действием или условием. Обратите внимание: Вы также можете делать это напрямую в редакторе ресурсов Visual C, когда Вы вводите новый идентификатор, например вводите IDMN_YOURACTION = 25011 для присваивания значения идентификатора.

Идентификаторы меню действий должны лежать между 25000 и 25999.

Идентификаторы меню условий должны лежать между 26000 и 26999.

Если Вы не меняете идентификаторы, то Ваша опция меню не будет детектироваться системой CF.

Строка отображения. Это строка, которую CF может показать для действий или событий в списке редактора событий. Отображение несколько более сложное, потому что CF должна вставить параметры и иконку объекта, когда отображает строку в редакторе событий. Система CF была разработана, чтобы справиться со всеми комбинациями одной строки (строка условия/действия), имени объекта и параметров.

Эти строки кодируются с символами %, каждый из этих символов заменяется строкой, либо именем объекта, либо параметрами:

%o заменяется именем объекта
%0 заменяется первым параметром
%1 заменяется вторым параметром
%2 заменяется третьим параметром

и т. д.

Пример 1:

"Number of objects in %0=%1"

С первым параметром как параметром zone и вторым параметром сравнения, будет отображено:

"Number of objects in zone(0,0) to (10,10)=15"

Пример 2:

"%o is facing a direction %0"

Оригинальная строка в программе выдает:

Romeo is facing a direction south

Пример 3:

"Number of %o in %0=%1"

Number of Romeo in zone () to () = 10

Выражения, как и условия и действия, нуждаются в 2 строках, находящихся в файле ресурсов:

• Пункт меню во всплывающем меню выражения.
• Отображаемая строка, с которой CF может составить список в редакторе событий.

Добавить пункт меню во всплывающем меню выражений довольно просто. Используйте обычную опцию меню в нормальном всплывающем меню Windows, и в меню максимально кратко опишите, что возвращает Ваше выражение.

Важное замечание: определение строки это одна из вещей, однако Вы должны отредактировать файл resource.h для смены идентификатора в новой опции меню: CF сравнивает этот идентификатор выбранной опции с границей значений, и определяет этим методом, является ли последняя выбранная опция выражением. Обратите внимание: Вы также можете делать это напрямую в редакторе ресурсов Visual C, когда вводите новый идентификатор, например введите IDMN_YOUREXPRESSION = 27005 чтобы определить значение для этого идентификатора.

Идентификаторы меню выражения должны лежать между 27000 и 27999.

Если Вы не меняете идентификаторы, то Ваша опция меню не будет детектироваться системой CF.

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

Примеры из объекта Clock:

"seconds of("
"minutes of("
"hours of("
"day of week of("

Все показанные выше выражения возвратят числовое значение. Чтобы показать, что выражение возвращает строку, Вы должны поместить знак доллара перед скобкой.

Пример строки выражения из объекта system:

"str$("

Вставка знака доллара перед скобкой всего лишь показывает, что Ваше выражение возвращает строку.

Если Вы просматривали исходный код объектов примеров, то наверное заметили, что некоторые флаги в массивах conditionsInfos и actionsInfos в начале файла EVFLAGS_ALWAYS или EVFLAGS_NOTABLE. Эти флаги очень важны, потому что они определяют поведение каждого условия (condition).

Условия событий, управляемые true и false event-driven. CF может обработать 2 разных типа условий: событийные и не событийные условия.

Действительно событийные условия полагаются на реальное событие, такое как клик мышью, столкновение (collision), нажатие кнопки клавиатуры или выбранная опция меню. Возьмем например клик мышью: пользователь кликает где-нибудь во фрейме, CF получает сообщение клика, и затем просматривает список событий, чтобы увидеть, существует ли условие, работающее с кликом, как первое условие в группе событий. Если да, то условие оценивается, и если результат оценки TRUE, то вычисляются другие (событийные) условия этой группе событий. Условие, которое реально событийное, и первое условие в группе условий, вычисляется по-настоящему быстро, потому что вычисление происходит только когда событие реально происходит.

Не событийные условия обычно вовлекают сравнение, такое как Global Value 1 < 10, и оно не срабатывает по реальному событию. CF вычисляет эти условия на каждом цикле приложения. Условие также может быть не событийным, когда реально событийное условие находится в позиции 2 (или с большим номером по списку) группы списка условий. В этом случае CF вызывает подпрограмму оценки, когда это необходимо.

Что Вам следует делать? Если Ваше условие отвечает за клик мышью или другое очень специфичное событие, то Вы должны сделать его реально событийным. Если нет, то оно должно вычисляться на каждой итерации цикла приложения. Флаги, которые можно использовать, следующие:

EVFLAGS_ALWAYS: говорит CF, что условие должно вычисляться на каждой прокрутке цикла. Если Вы просмотрите исходный код, то увидите, что это случай для большинства условий в примерах объектов.

Нет флага EVFLAGS_ALWAYS: говорит CF, что Ваше условие будет вычисляться только если генерируется событие (для Вас это может быть реализовано функциями RFUNCTION_GENERATEEVENT, RFUNCTION_PUSHEVENT), если оно первое в группе событий, или когда необходимо, если оно не первое в группе событий.

В случае не событийных условий Вы также можете добавить флаг:

EVFLAGS_NOTABLE: показывает, что Ваше условие может быть инвертировано. В этом случае будет доступна опция Negate, когда Вы кликаете на условии правой кнопкой мыши.

CF содержит функции, позволяющие Вам определить свои собственные параметры действия. Это новые параметры находятся в зоне памяти, в которой Вы можете сохранить то, что хотите (строки, цвета, и т. д.). Вам нужно только определить 3 функции для создания своего нового параметра.

Что нужно для этого сделать: сначала в файле main.h определяется новое значение параметра: первый должен быть PARAM_EXTBASE, следующий PARAM_EXTBASE+1 и так далее. Пример:

#define PARAM_MYPARAM (PARAM_EXTBASE)

В файле EditTime.cpp Вы должны определить 3 функции: InitParameter, EditParameter и GetParameterString. Пожалуйста обратитесь к описанию функции в главе "Список необходимых функций / Edit time".

В файле Main.cpp, в записи Вашего действия (таблица actionsInfos), используйте свой пользовательский параметр в качестве типа параметра (PARAM_MYPARAM в примере выше).

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

Сначала нужно определить идентификатор для каждого из свойств, которые Вы намереваетесь реализовать. Это делается через простое перечисление (enum). Поместите её в начало файла EDITTIME.CPP. Пример:

// Это перечисление определяет идентификаторы свойств:

enum
{
   PROPID_SETTINGS = PROPID_EXTITEM_CUSTOM_FIRST,
   PROPID_TEXTTITLE,
   PROPID_TEXT,
   PROPID_CHECK,
   PROPID_COMBO,
   PROPID_COLOR,
};

Обратите внимание, что Ваши идентификаторы свойств должны быть в диапазоне от PROPID_EXTITEM_CUSTOM_FIRST до PROPID_EXTITEM_CUSTOM_LAST. Другие значения используются CF для других свойств объекта.

Вы должны дать понятные имена для идентификаторов, потому что будете потом использовать их в своем коде.

Таблица PropData это список макросов, которые определяют для каждого свойства его тип и связанные отображаемые строки. Эти макросы определены в файле Props.h находящемся в каталоге Inc EDK.

Определено множество макросов, по одному для каждой возможной конфигурации свойства. Например, макрос PropData_CheckBox будет отображать простую галочку для двоичного выбора (разрешено или запрещено, check box). Макрос PropData_ComboBox_Check отобразит checkbox (галочка), связанный с combobox (выпадающий список для выбора), и т. д. Для дополнительной информации см. раздел "Макросы PropData" в этой главе.

Каждому макросу нужно указать параметры:

- Первый параметр это идентификатор свойства, который Вы определили на шаге 1.
- Второй параметр это идентификатор строки ресурсов для свойства текста, отображаемого в окне редактора свойств.
- Третий параметр это идентификатор строки ресурсов для быстрого описания, отображаемого в Information box окна редактора свойств.
- У некоторых макросов есть четвертый параметр: этот параметр передается в функцию инициализации свойства, например элемент из списка свойства ComboBox.
- Некоторые макросы могут также иметь другие параметры перед четвертым параметром, подробнее см. раздел "Макросы PropData".

Эта таблица должна заканчиваться макросом PropData_End.

Пример массива PropData:

// Определение дерева свойств.
PropData Properties[] =
{
   PropData_Group (PROPID_TEXTTITLE, IDS_PROP_TEXTTITLE, IDS_PROP_TEXTTITLE),
   PropData_EditString (PROPID_TEXT, IDS_PROP_TEXT, IDS_PROP_TEXT_INFO),
   PropData_CheckBox (PROPID_CHECK, IDS_PROP_CHECK, IDS_PROP_CHECK_INFO),
   PropData_ComboBox (PROPID_COMBO, IDS_PROP_COMBO, IDS_PROP_COMBO, ComboList),
   PropData_Color (PROPID_COLOR, IDS_PROP_COLOR, IDS_PROP_COLOR_INFO),
   PropData_End()
};

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

Второй элемент показывает редактируемую строку. Здесь также 2 параметра: заголовок и информационная строка.

Третий элемент показывает простой check box, со строкой заголовка и строкой информации.

Четвертый элемент представляет combo box, с заголовком и строкой информации, плюс дополнительный параметр, который указывает на таблицу, содержащую строки для этого combo box:

// Список вариантов выбора для combo box:
LPCSTR ComboList[] =
{
   0,    // зарезервировано
   MAKEINTRESOURCE(IDS_FIRSTOPTION),
   MAKEINTRESOURCE(IDS_SECONDOPTION),
   MAKEINTRESOURCE(IDS_THIRDOPTION),
   NULL
};

Как Вы можете видеть, это список содержит простой макрос MAKEINTRESOURCE для каждого идентификатора строки. Эта таблица завершается NULL (и начинается с 0).

Пятый элемент определяет свойство цвета, здесь также есть текст заголовка и строка информации.

Таблица заканчивается макросом PropData_End().

PropData_Button( id, name, info, text )
PropData_Button_Check( id, name, info, text )
PropData_Button_Opt( id, name, info, options, text )

Отображает кликабельную кнопку. Когда пользователь кликает на ней, CF вызывает функцию EditProp, реализованную в Вашем расширении. Для получения подробностей обратитесь к документации по этой функции в главе "Список необходимых функций / Edit time".

Даже если это свойство не отображает реальное свое содержимое, в зависимости от содержимого этого свойства Вы должны реализовать функции GetPropValue и SetPropValue, так что когда пользователь выбирает несколько объектов, и кликает на кнопку Edit, это свойство копировалось во все другие выделенные объекты. CPropValue, возвращенное GetPropValue, и переданное в SetPropValue не определено, Вы можете использовать то, что хотите.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
text идентификатор или указатель на текст, отображаемый на кнопке.
options см. раздел "Макросы PropData".

PropData_CheckBox( id, name, info )
PropData_CheckBox_Opt( id, name, info, options )

Отобразит чекбокс. Система CF вызовет функцию GetPropCheck в Вашем расширении, чтобы получить состояние чекбокса, и вызовет функцию SetpropCheck, когда пользователь кликает на чекбоксе. Вызов GetPropValue или SetPropValue не осуществляется.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".

Примечание: здесь нет макроса PropData_CheckBox_Check, так как свойство CheckBox в основном "пустое" свойство для чекбокса.

PropData_Color( id, name, info )
PropData_Color_Check( id, name, info )
PropData_Color_Opt( id, name, info, options )

Отображает свойство цвета: цвет и селектор цвета.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое из GetPropValue, и передаваемое в SetPropValue, это CPropDWordValue, которое содержит значение COLORREF.

PropData_ComboBox( id, name, info, list )
PropData_ComboBox_Check( id, name, info, list )
PropData_ComboBox_Opt( id, name, info, options, list )

Отображает список выбора, содержащий строки.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
list указатель на массив строк, или массив макросов MAKEINTRESOURCE с идентификаторами строк. Первая запись в этом массиве должна быть 0 (зарезервировано для использования в будущем), и массив должен заканчиваться значением NULL.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое из GetPropValue, и передаваемое в SetPropValue, является значением CPropDWordValue, которое содержит индекс выбранного элемента в combo box (-1 = ничего не выбрано, 0 = выбран первый элемент, и т. д.).

Замечания:

Параметр list может быть равен NULL. В этом случае система CF вызовет функцию GetPropCreateParam, когда создается свойство combo box (или когда оно обновляется функцией mvRefreshProp с параметром ReInit, установленным в TRUE). Функция GetPropCreateParam должна возвратить ненулевой указатель (не равный null) на массив строк (наподобие статического параметра). Когда свойство combo box инициализировано, CF вызовет функцию ReleasePropCreateParam, так что Вы можете освободить память, если Вы её динамически выделили для указателя на массив строк. Для дополнительной информации см. описание функций GetPropCreateParam и ReleasePropCreateParam в главе "Список необходимых функций / Edit time".

Пример:

LPCTSTR ComboList[] =
{
   0,    // зарезервировано
   MAKEINTRESOURCE(IDS_FIRSTOPTION),
   MAKEINTRESOURCE(IDS_SECONDOPTION),
   MAKEINTRESOURCE(IDS_THIRDOPTION),
   NULL
}; 

PropData_ComboBox (PROPID_COMBO, IDS_PROP_COMBO, IDS_PROP_COMBO, ComboList);

PropData_ComboBoxBtn( id, name, info, list )
PropData_ComboBoxBtn_Check( id, name, info, list )
PropData_ComboBoxBtn_Opt( id, name, info, options, list )

Отображает кнопку "+/-" и список выбора, содержащий строки.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
list указатель на массив строк, или массив макросов MAKEINTRESOURCE с идентификаторами строк. Первая запись в этом массиве должна быть 0 (зарезервировано для использования в будущем), и массив должен заканчиваться значением NULL.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое из GetPropValue, и передаваемое в SetPropValue, является значением CPropDWordValue, которое содержит индекс выбранного элемента в combo box (-1 = ничего не выбрано, 0 = выбран первый элемент, и т. д.).

Замечания:

Параметр list может быть равен NULL. В этом случае система CF вызовет функцию GetPropCreateParam, когда создается свойство combo box (или когда оно обновляется функцией mvRefreshProp с параметром ReInit, установленным в TRUE). Функция GetPropCreateParam должна возвратить ненулевой указатель (не равный null) на массив строк (наподобие статического параметра). Когда свойство combo box инициализировано, CF вызовет функцию ReleasePropCreateParam, так что Вы можете освободить память, если Вы её динамически выделили для указателя на массив строк. Для дополнительной информации см. описание функций GetPropCreateParam и ReleasePropCreateParam в главе "Список необходимых функций / Edit time".

Пример:

LPCTSTR ComboList[] =
{
   0,    // зарезервировано
   MAKEINTRESOURCE(IDS_FIRSTOPTION),
   MAKEINTRESOURCE(IDS_SECONDOPTION),
   MAKEINTRESOURCE(IDS_THIRDOPTION),
   NULL
}; 

PropData_ComboBoxBtn (PROPID_COMBO, IDS_PROP_COMBO, IDS_PROP_COMBO, ComboList);

PropData_Custom( id, name, info, param )
PropData_Custom_Check( id, name, info, param )
PropData_Custom_Opt( id, name, info, options, param )

Это свойство позволяет Вам создавать свои собственные свойства.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
param указатель на структуру CustomPropCreateStruct structure, см. ниже.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое из GetPropValue, и передаваемое в SetPropValue, должно быть таким же, как и значение, используемое в функциях GetPropValue и SetPropValue Вашего объекта CCustomProp (см. описание ниже).

Пример:

CustomPropCreateStruct initStruct = { CreateMyCustomPropProc, 0 };
PropData_Custom( PROPID_MYPROP, IDS_MYPROP, IDS_MYPROP_INFO, &initStruct );

Структура CustomPropCreateStruct. Эта структура содержит значения для создания элемента свойства в новом окне, и инициализирует его.

typedef struct CustomPropCreateStruct
{
   CP_CREATEINSTANCE    m_pCreateCustomPropFnc;
   LPARAM               m_lCreateParam;
} CustomPropCreateStruct;

m_lCreateParam это параметр инициализации, который соответствует lParam, обычно передаваемые в свойства наподобие ComboBox. Поместите в этот член структуры значение, специфичное для Вашего идентификатора свойства.

m_pCreateCustomPropFnc это callback-функция, которую CF вызовет для создания свойства, она имеет следующий формат:

CCustomProp* CALLBACK CreateMyCustomPropProc()
{
    // Эта функция должна возвратить объектCCustomProp:
    return new CMyCustomProp;
}

Класс CCustomProp. Базовый класс CCustomProp, определенный в Props.h, представляет Ваш элемент свойства в окне редактора свойств (property window). Вы должны создать на его основе свой новый класс, например CMyCustomProp, производный от CCustomProp. Базовый класс CCustomProp имеет следующие функции:

void Initialize(HINSTANCE hInst, LPARAM lCreateParam, BOOL bReInit);

Вызывается системой CF для инициализации элемента свойства. hInst это указатель HINSTANCE на программу, lCreateParam это член m_lCreateParam структуры CustomPropCreateStruct (в PropData) и bReInit будет TRUE, когда эта функция вызывается для повторной инициализации свойства, если оно уже было создано (когда запрашивается обновление с параметром reinit, равным TRUE).

void Delete();

Вы не должны изменять эту функцию.

void Draw(HDC hDC, LPRECT pRc, HFONT hFont, COLORREF textColor);

Позволяет Вам нарисовать элемент свойства в окне редактора свойств. hDC это контекст устройства (windows device context) окна свойств, pRc это прямоугольник, в котором Вам нужно нарисовать элемент свойства, hFont и textColor должны использоваться для отображения некоторого текста.

CPropValue* GetPropValue();

Вы должны вернуть значение свойства, которое отображается в настоящий момент окном редактора свойств (property window).

void SetPropValue(CPropValue* pValue);

Эта функция вызывается CF для установки значения элемента свойства.

void Activate(HWND hParent, LPRECT pRc, HFONT hFont);

Эта функция вызывается, когда пользователь делает клик на элементе свойства в редакторе свойств. Например, в этой функции Вы можете создать или показать окно combo box, кнопку, и т. п. hParent это хендл окна редактора свойств, pRc это координаты прямоугольника элемента свойства относительно родительского окна.

void Deactivate();

Эта функция вызывается для деактивации элемента свойств. Например, в этой функции Вы можете скрыть элемент управления (control), который был создан функцией Activate.

void Refresh();

Эта функция вызывается системой CF после изменения значения.

void Move(LPRECT pRc);

Эта функция вызывается, если элемент свойства был перемещен или у него был изменен размер. Например, Вы можете обновить позицию элементов управления пользовательского интерфейса, созданные при активации окна (Activate). pRc это новый прямоугольник области элемента свойств.

BOOL UpdateData();

В этой функции Вы должны получить редактируемое значение для любого открытого элемента управления пользовательского интерфейса (control), если оно есть, и сохранить его в данные объекта CCustomProp. Эта функция обычно вызывается непосредственно перед вызовом функции Deactivate.

PropData_DirCtrl( id, name, info, param )
PropData_DirCtrl_Check( id, name, info, param )
PropData_DirCtrl_Opt( id, name, info, options, param )

Отобразит селектор для 32 возможных направлений, наподобие используемого в свойствах перемещения (movement properties).

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".
param указатель на структуру DirCtrlCreateParam:

typedef struct
{
   BOOL  bMultiSel;  // TRUE для множественного выбора, FALSE для одиночного выбора
   int   numDirs;    // количество направлений 4, 8, 16 или 32
   DWORD style;      // стиль
} DirCtrlCreateParam;

Поле style может содержать один или большее количество флагов:

DCS_FLAT плоское отображение (Flat).
DCS_3D трехмерное отображение (3D).
DCS_SLIDER слайдер для изменения количества направлений.
DCS_EMPTY непонятно, что это должно означать... вроде должно как-то влиять на точки направлений.
DCS_SETALL_BTNS добавляет кнопки "Select All" (выбрать все) и "Reset" (сброс).

Пример:

DirCtrlCreateParam initDirParam32 = { TRUE, 32, DST_3D | DST_SETALL_BTNS };
PropData_DirCtrl(PROPID_INITDIR, IDS_INITDIR, IDS_INITDIR_INFO, &initDirParam32);

CPropValue: значение, возвращаемое GetPropValue, и передаваемое в SetPropValue, должно быть CPropDataValue, которое содержит структуру PropDirValue.

typedef struct
{
   int   selDir;     // выбранное направление (индекс одиночного выбора направления)
   DWORD selDir32;   // выбранные направления (32-битная маска направлений,
                     // для множественного выбора)
   int   numDirs;    // количество направлений
   int   reserved;   // не используется
} PropDirValue;

Пример:

PropDirValue pv;
memset(&pv, 0, sizeof(PropDirValue));
pv.selDir32 = m_pMvtData->mvDirAtStart;
pv.numDirs = 32;

return new CPropDataValue(sizeof(PropDirValue), (LPBYTE)&pv);

PropData_EditButton( id, name, info )
PropData_EditButton_Check( id, name, info )
PropData_EditButton_Opt( id, name, info, options )

Отображает кнопку, на которой имеется текст "Edit". Это тот же PropData_Button, к которого нельзя поменять текст на кнопке.

Когда пользователь кликает на этой кнопке, CF вызовет функцию EditProp, реализованную в Вашем расширении. Для получения подробностей обратитесь к документации по этой функции в главе "Список необходимых функций / Edit time".

Даже если это свойство не отображает реальное свое содержимое, в зависимости от содержимого этого свойства Вы должны реализовать функции GetPropValue и SetPropValue, так что когда пользователь выбирает несколько объектов, и кликает на кнопку Edit, это свойство копировалось во все другие выделенные объекты. CPropValue, возвращенное GetPropValue, и переданное в SetPropValue не определено, Вы можете использовать то, что хотите.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".

PropData_EditFloat ( id, name, info )
PropData_EditFloat_Check ( id, name, info )
PropData_EditFloat_Opt ( id, name, info, options )

Отображает окошко редактирования для ввода числа с плавающей запятой.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое GetPropValue, и передаваемое в SetPropValue, то тип CPropFloatValue.

PropData_EditMultiLine ( id, name, info )
PropData_EditMultiLine_Check ( id, name, info )
PropData_EditMultiLine_Opt ( id, name, info, options )

Отображает окошко редактирования с кнопкой Edit, которая открывает окно диалога с многострочным вводом (multi-line edit box).

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropStringValue, оно содержит многострочный текст: каждая строка заканчивается на последовательность символов CR/LF (0x0D, 0x0A), и весь многострочный текст заканчивается нулевым символом (символ с кодом 0).

PropData_EditNumber ( id, name, info )
PropData_EditNumber_Check ( id, name, info )
PropData_EditNumber_Opt ( id, name, info, options )

Отображает бокс ввода для редактирования числа.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropDWordValue.

PropData_EditString ( id, name, info )
PropData_EditString_Check ( id, name, info )
PropData_EditString_Opt ( id, name, info, options )

Отображает бокс для ввода и редактирования строки.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropStringValue, это значение содержит строку.

Пример:

return new CPropDataValue(pStr);
LPCTSTR pStr = ((CPropStringValue*)lParam)->GetString();

PropData_End( )

Показывает конец списка PropData.

PropData_Filename ( id, name, info, param )
PropData_Filename_Check ( id, name, info, param )
PropData_Filename_Opt ( id, name, info, options, param )

Отображает свойство имени файла: имя файла в строке редактирования пути, и кнопка browse, которая открывает браузер/селектор файла.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".
param указатель на структуру FilenameCreateParam:

typedef struct
{
   // Строка фильтра для диалога GetOpenFilename
   // (например "All Files (*.*)|*.*|"):
   LPCTSTR extFilter;
   // Опции для диалога GetOpenFilename (OFN_FILEMUSTEXIST,
   // OFN_PATHMUSTEXIST, OFN_HIDEREADONLY, и т. д.):
   DWORD   options;
} FilenameCreateParam;

Пример:

FilenameCreateParam fcp = { MAKEINTRESOURCE(IDS_TXTFILTER),
                            OFN_FILEMUSTEXIST | OFN_HIDEREADONLY };
PropData_Filename(PROPID_FILENAME,
                  IDS_PROP_FILENAME,
                  IDS_PROP_FILENAME_INFO,
                  &fcp);

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropStringValue, это значение содержит имя файла.

PropData_Folder( id, name, info )

Инициализирует папку, содержащую другие свойства.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.

Замечания: все свойства, которые перечислены после этого макроса, будут содержаться в закрываемой папке. Вы должны показать конец этой папки макросом PropData_Folder_End.

PropData_Folder_End()

Показывает окончание папки для свойств.

Замечания: этот макрос нужно использовать в паре с макросом PropData_Folder, чтобы показать границы свойств, содержащихся в отдельной папке редактора свойств.

PropData_Font ( id, name, info, param )
PropData_Font_Check ( id, name, info, param )
PropData_Font_Opt ( id, name, info, options, param )

Отображает свойство шрифта: имя шрифта и кнопку его выбора (Choose Font), которая открывает селектор шрифта.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".
param опции для Windows-диалога (CF_EFFECTS, CF_SCREENFONTS, etc.).

Пример:

PropData_Font(PROPID_TEXT_FONT, IDS_TEXTPROP_FONT,
              IDS_TEXTPROP_FONT_INFO, (CF_EFFECTS | CF_SCREENFONTS));

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropDataValue, это значение содержит структуру LOGFONT. Пример:

return new CPropDataValue(sizeof(LOGFONT), (LPBYTE)&lf);
LOGFONT* plf = (LOGFONT*)((CPropDataValue*)lParam)->m_pData;

PropData_Group( id, name, info)

Отображает заголовок группы.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.

Замечания: группу используются в подавляющем большинстве объектов: они упрощают список и позволяют составить его в организованном порядке.

PropData_IconComboBox( id, name, info, list )
PropData_IconComboBox_Check( id, name, info, list )
PropData_IconComboBox_Opt( id, name, info, options, list )

Отображает окно списка (list box), содержащее строки, в начале которых содержаться иконки.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".
list указатель на массив LPCTSTR, который содержит:

- Значение NULL, зарезервированное для будущего использования.
- Значение, которое содержит размер иконки, например (LPCTSTR)24.
- Каждая строка массива либо указывает на строку LPCTSTR, либо в строке будет MAKEINTRESOURCE(string identifier) и ресурс HICON.
- Значение NULL, показывающее конец таблицы.

Пример:

LPCTSTR iconComboList[] =
{
   (LPCTSTR)0,    // зарезервировано
   (LPCTSTR)24,   // размер иконки
   MAKEINTRESOURCE(IDS_LINE1), hIcon1,
   MAKEINTRESOURCE(IDS_LINE2), hIcon2,
   MAKEINTRESOURCE(IDS_LINE3), hIcon3,
   MAKEINTRESOURCE(IDS_LINE4), hIcon3,
   NULL           // показывает конец списка
}; 

PropData_IconComboBox (PROPID_COMBO, IDS_PROP_COMBO,
                       IDS_PROP_COMBO, iconComboList);

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropDWordValue, это значение содержит индекс выбранного элемента в combo box (-1 = ничего не выбрано, 0 = первый элемент).

Замечания: Вы можете установить параметр list в значение NULL, когда используете макрос в PropData, создайте его в функции GetPropCreateParam function и освободите в функции ReleasePropCreateParam. Это самый простой способ загрузить иконки. Внимание: не уничтожайте иконки созданного списка, они будут уничтожены, когда завершится программа (CF).

PropData_ImageList ( id, name, info )
PropData_ImageList_Check ( id, name, info )
PropData_ImageList_Opt ( id, name, info, options )

Отображает список картинок с кнопкой редактирования (Edit).

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropDataValue, это значение содержит количество изображений (WORD), за которым идет список значений WORD, содержащий идентификаторы изображений.

Замечания: когда пользователь делает клик на кнопке Edit, CF вызывает функцию EditProp, реализованную в Вашем расширении. Например, в функции EditProp Вы можете открыть редактор списка картинок CF (image list editor) вызовом mvEditAnimation (или редактор картинки, picture editor, с помощью вызова mvEditImage, если это только одна картинка). Пример:

GetPropValue:

   CPropDataValue* pv = new CPropDataValue((nImages + 1) * sizeof(WORD), NULL);
   if ( pv != NULL )
   {
      if ( pv->m_pData != NULL )
      {
         LPWORD pw = (LPWORD)pv->m_pData;
         *pw++ = nImages;
         for (WORD w=0; w < nImages; w++)
             *pw++ = edPtr->images[w];
         return pv;
      }
      pv->Delete();
   }

SetPropValue:

   if ( ((CPropDataValue*)pValue)->m_pData != NULL )
   {
      LPWORD pw = (LPWORD)((CPropDataValue*)pValue)->m_pData;
      nImages = *pw++;
      // и т. д.
   }

EditProp:

BOOL WINAPI DLLExport EditProp(LPMV mV, LPEDATA edPtr, UINT nPropID)
{
   if ( nPropID == PROPID_IMAGES )
   {
      EditAnimationParams    eap;
      eap.m_dwSize = sizeof(EditAnimationParams);
      eap.m_pWindowTitle = NULL;
      eap.m_nImages = edPtr->nImages;
      eap.m_nMaxImages = edPtr->nImages;
      eap.m_nStartIndex = 0;
      eap.m_pImages = edPtr->images;
      eap.m_pImageTitles = NULL;
      eap.m_dwOptions = PICTEDOPT_FIXEDNFRAMES;
      eap.m_dwFixedWidth = 100;
      eap.m_dwFixedHeight = 100; 

      if ( mV->mvEditAnimation(edPtr, &eap, NULL) )
      {
         mvRefreshProp(mV, edPtr, PROPID_IMAGES, FALSE);
         mvInvalidateObject(mV, edPtr);
         return TRUE;
      }
   } 

   return FALSE;
}

PropData_PictureFilename ( id, name, info, param )
PropData_PictureFilename_Check ( id, name, info, param )
PropData_PictureFilename_Opt ( id, name, info, options, param )

Отображает свойство имени файла картинки: имя файла к строке редактирования (edit box), и кнопка browse, которая открывает селектор файла картинки.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".
param TRUE, если Вы хотите также использовать и файлы анимации (FLI, AVI, и т. п.).

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropStringValue, это значение содержит имя файла.

Пример:

PropData_PictureFilename(PROPID_FILENAME,
                         IDS_PROP_FILENAME,
                         IDS_PROP_FILENAME_INFO);

PropData_Size ( id, name, info, tab )
PropData_Size_Check ( id, name, info, tab )
PropData_Size_Options ( id, name, info, options, tab )

Отображает свойство размера (size): две поля ввода (edit box), одна для горизонтального размера, другая для вертикального.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".
tab указатель на таблицу размеров.

Пример:

int tabPredefinedSizes[] =
{
   320, 200,
   320, 240,
   640, 480,
   800, 600,
   1024, 768,
   1280, 1024,
   1400, 1050,
   1600, 1200,
   0, 0
};
PropData_Size(PROPID_WINDOWSIZE, IDS_WINDOWSIZE,
              IDS_WINDOWSIZE_INFO, (LPARAM)tabPredefinedSizes);

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropSizeValue.

PropData_SpinEdit ( id, name, info, minmax)
PropData_SpinEdit_Check ( id, name, info, minmax)
PropData_SpinEdit_Opt ( id, name, info, options, minmax)

Отображает spinbox (регулятор), связанный с полем редактирования (edit box), чтобы проще редактировать целые числа.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".
minmax указатель на таблицу, которая содержит минимальное и максимальное значения. Внимание: минимальное значение не может быть меньше -32768, максимальное значение не может быть больше 32767, и разница между обоими этими значениями не может быть больше 32767.

Пример:

int MinMaxAngle[] = { 0, 359 };
PropData_SpinEdit(PROPID_FII_ANGLE, IDS_FIIPROP_ANGLE,
                  IDS_FIIPROP_ANGLE_INFO, &MinMaxAngle);

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropDWordValue.

PropData_SliderEdit ( id, name, info, minmax)
PropData_SliderEdit_Check ( id, name, info, minmax)
PropData_SliderEdit_Opt ( id, name, info, options, minmax)

Отображает слайдер, связанный с полем редактирования (edit box), чтобы проще редактировать целые числа.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".
minmax указатель на таблицу, которая содержит минимальное и максимальное значения.

Пример:

int MinMaxAngle[] = { 0, 359 };
PropData_SliderEdit(PROPID_FII_ANGLE, IDS_FIIPROP_ANGLE,
                    IDS_FIIPROP_ANGLE_INFO, &MinMaxAngle);

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropDWordValue.

PropData_StaticString ( id, name, info )
PropData_StaticString_Check ( id, name, info )
PropData_StaticString_Options ( id, name, info, options )

Отображает простую статическую строку текста.

Параметры:

id идентификатор свойства.
name идентификатор строки или указатель на строку, где содержится имя свойства.
info идентификатор или указатель на строку информации.
options см. раздел "Макросы PropData".

CPropValue: значение, возвращаемое GetPropValue, и передаваемое SetPropValue, имеет тип CPropStringValue, здесь содержится строка.

Определена в CNCR.H, часть основных структур CF. Используется только во время работы приложения runtime.

Назначение: содержит всю нужную информацию о текущем приложении.

Замечание: как и все runtime-структуры, возможно разработчики будут вынуждены поменять её содержимое в будущих обновлениях CF. Если так, то придется обновить SDK. Вы должны избегать прямого использования этих структур, конечно за исключением случаев, когда нет другого способа получить доступ к нужной информации.

Полезные поля:

m_hdr

   - gaNewFlags: содержит флаги GANF_xxx, в которых находятся настройки.
   - gaFlags: содержит флаги GA_xxx с другими настройками.
   - gaNbFrames: количество фреймов в приложении.
   - gaFrameRate: текущая скорость обновления кадров в приложении (frame rate, влияет на плавность анимации).

m_name: имя приложения.

m_appFileName: имя файла приложения (оно может находиться во временной директории, см. структуру mV, если Вам требуется имя исполняемого файла EXE).

m_copyright: сообщение копирайта.

m_aboutText: текст для отображения в окошке About.

m_doc: файл подсказки (help).

m_nbKpx: количество расширений, используемых в приложении.

m_kpxTab и m_kpxDataTable: информация о расширениях (HINSTANCE и функции).

m_nbMvx: количество расширений перемещения (movement extensions).

m_mvxTable: информация о расширениях перемещения (HINSTANCE и функции).

m_oiMaxIndex: количество объектов.

m_ois: таблица объектов.

m_pParentApp: родительское приложение (если текущее приложение работает как дочернее, sub-application).

m_Frame: текущий фрейм (см. структуру CRunFrame для дополнительной информации).

m_nCurrentFrame: индекс текущего фрейма.

m_pGlobalValues: глобальные значения (предупреждение: если m_bShareGlobalValues == TRUE, используйте m_pGlobalValues из родительского приложения, или выше).

m_pGlobalStrings: глобальные строки (предупреждение: если m_bShareGlobalStrings == TRUE, используйте m_pGlobalStrings из родительского приложения, или выше).

Определена в CNCR.H, часть основных структур CF.

Назначение: содержит всю необходимую информацию по текущему фрейму во время выполнения приложения (runtime).

Замечание: как и все runtime-структуры, возможно разработчики будут вынуждены поменять её содержимое в будущих обновлениях CF. Если так, то придется обновить SDK. Вы должны избегать прямого использования этих структур, конечно за исключением случаев, когда нет другого способа получить доступ к нужной информации.

Полезные поля:

m_hdr

   - leWidth: ширина игрового поля.
   - leHeight: высота игрового поля.
   - leBackground: цвет фона.
   - leFlags: некоторые опции.

m_name: имя фрейма.

m_loMaxIndex: количество экземпляров объекта.

m_los: экземпляры объекта во фрейме.

m_rhPtr: указатель на структуру RunHeader.

Определена в MAIN.H, часть кода расширения.

Назначение: хранит настройки времени редактирования (edit-time) объекта, определенные в диалоге настройки и свойствах объекта. Эта структура должна быть полностью определена Вами! EDITDATA должен начинаться с дочерней структуры extheader, которая содержит информацию для CF.

Замечания: здесь показан минимум для структуры EDITDATA:

typedef struct
{
   extHeader eHeader;
} EDITDATA;

Структура extheader:

typedef struct tagEditExtension
{
   DWORD extSize;          // размер структуры EDITDATA
   DWORD extMaxSize;       // максимальный размер
   DWORD extVersion;       // номер версии
   LPVOID extID;           // идентификатор объекта
   LPVOID extPrivateData;  // приватные данные
} extHeader;

Замечание: Вы не должны менять эту структуру. Если Вам нужно повторно выделить структуру EDITDATA, используйте callback-функцию mvReAllocEditData в структуре mv.

Определена в CNCF.H, часть основных структур CF.

Назначение: хранит run-time информацию, не зависящую от объекта. Структура HeaderObject должна всегда быть в начале структуры RUNDATA. Предупреждение: обращайтесь только к "полезным полям", изменения в любых других областях могут полностью нарушить работу приложения!

Полезные поля:

short hoNumber;      // Номер объекта в списке объектов CF
LPRH hoAdRunHeader;  // Адрес структуры RunHeader

short hoX;           // Координата X объекта

short hoY;           // Координата Y объекта

int hoImgXSpot;      // Позиция X активной области (hot spot) текущей картинки

int hoImgYSpot;      // Позиция Y активной области (hot spot) текущей картинки

int hoImgWidth;      // Текущая ширина объекта

int hoImgHeight;     // Текущая высота объекта

short hoOEFlags;     // Флаги OEFLAGS объекта

Определена в CNPY.H, часть основного кода CF.

Назначение: хранит информацию о каждом отдельном объекте во фрейме. Имеется один экземпляр структуры LO на каждый объект во фрейме. Дублированные объекты имеют одну и ту же структуру OI.

Замечание: как и все runtime-структуры, возможно разработчики будут вынуждены поменять её содержимое в будущих обновлениях CF. Если так, то придется обновить SDK. Вы должны избегать прямого использования этих структур, конечно за исключением случаев, когда нет другого способа получить доступ к нужной информации.

Полезные поля:

loX: координата X объекта на игровом поле
loY: координата Y объекта на игровом поле
loLayer: индекс слоя объекта
loType: тип объекта

Обратите внимание, что поля этой структуры действительны только во время работы приложения (run time).

Структура mv служит для коммуникации между CF и Вашим расширением. Она содержит глобальные данные наподобие хендлов окна, callback-функции, которые Ваше расширение может использовать. Для получения списка callback-функций см. раздел "Callback-функции" этой документации.

Важные поля в структуре mv:

mvHInst: HINSTANCE программы (CF или runtime-приложения).
mvIdAppli: хендл приложения в mmfs2.dll.
mvIdMainWin: хендл главного окна в mmfs2.dll.
mvIdEditWin: хендл дочернего окна в mmfs2.dll.
mvHMainWin: хендл Windows основного окна.
mvHEditWin: хендл Windows дочернего окна.
mvHPal256: 256-цветная палитра.
mvScrMode: текущий режим экрана SM_8=256, SM_15=32768, SM_16=65536, SM_32=16 миллионов цветов.
mvEditDXDocToClient: координата X окна редактора фрейма относительно игрового поля (только для времени редактирования, edit time).
mvEditDYDocToClient: координата Y окна редактора фрейма относительно игрового поля (только для времени редактирования, edit time).
mvRunApp: только для времени выполнения приложения (run time), указатель на структуру CRunApp.
mvRunFrame: только для времени выполнения приложения (run time), указатель на структуру CRunFrame.
mvPrefs: свойства (звук включить/выключить) - только для времени выполнения приложения (run time).
mvImgFilterMgr: менеджер фильтра изображения (image filter manager).
mvSndFilterMgr: менеджер звукового фильтра (sound filter manager).
mvSndMgr: менеджер звука (sound manager).
mvMainAppFileName: файловый путь приложения (pathname). Оригинальный путь может отличаться от имени, сохраненном в CRunApp, которое может содержать путь во временной директории.

Другие поля структуры это callback-функции, подробнее о них см. раздел "Callback-функции" этой документации.

Примечание: во время работы программы (runtime) Вы можете обращаться к структуре mv из структуры RunHeader: rhPtr->rh4.rh4Mv.

Определена в CNCY.H, часть основного кода CF.

Назначение: хранит информацию об объекте. Структура OI сохраняется в приложении. Экземпляры объекта имеют структуры LO, сохраненные в каждом фрейме.

Замечание: как и все runtime-структуры, возможно разработчики будут вынуждены поменять её содержимое в будущих обновлениях CF. Если так, то придется обновить SDK. Вы должны избегать прямого использования этих структур, конечно за исключением случаев, когда нет другого способа получить доступ к нужной информации.

Полезные поля:

oiHdr

   - oiType: тип объекта.
   - oiInkEffect: эффект чернил + прозрачность (transparency) и флаг антиалиасинга.
   - oiInkEffectParam: параметр эффекта чернил.

oiName: имя объекта.

oiOC: указатель на структуру, которая содержит информацию времени редактирования (анимации, перемещения, данные расширения, и т. д.).

Примечание: только поля эффекта чернил в этой структуры достоверны во время редактирования (edit time).

Определена в MAIN.H, часть кода расширения.

Назначение: хранит информацию об объекте во время выполнения приложения (run-time). Структура RUNDATA должна всегда начинаться с headerObject, за которым идут структуры movement, animation, common и value, в зависимости от флагов OEFLAG. Для получения дополнительной информации обратитесь к секции "Определение флагов объекта / важные структуры" этой документации.

Как устроена структура RUNDATA. Во простейшая структура RUNDATA:

typedef struct
{
   headerObject rHo;
} RUNDATA;

Определена в CNCF.H, часть основного исходного кода CF.

Назначение: хранит информацию приложения во время его выполнения (run-time). Обычно Вам нужно обращаться к этой структуре для получения хендла окон.

Предупреждение: обращайтесь только к "полезным полям", изменения в любых других полях могут полностью нарушить работу приложения!

Полезные поля:

npWin rhIdEditWin;   // идентификатор MMFS окна приложения
npWin rhIdMainWin;   // идентификатор MMFS окна фрейма приложения
npAppli rhIdAppli;   // идентификатор MMFS приложения
HWND rhHEditWin;     // хендл Windows для окна приложения
HWND rhHMainWin;     // хендл Windows для окна фрейма
CRunApp* rhApp;      // указатель на информационную структуру приложения
CRunFrame* rhFrame;  // указатель на информационную структуру фрейма

int rhLoopCount;     // количество циклов от момента запуска фрейма
UINT rhTimer;        // таймер в единицах 1/1000 секунды от начала фрейма

BOOL WINAPI DllMain(HINSTANCE hDLL, DWORD dwReason, LPVOID lpReserved)

Эта подпрограмма основной реализации DLL. Обратитесь к документации Microsoft для получения полной информации об этой подпрограмме.

Замечания: Вы не должны использовать эту подпрограмму для инициализации ресурсов или загрузки данных. Всю необходимую для Вас инициализацию делайте в подпрограмме Initialize.

int WINAPI DLLExport Initialize(mv _far *mV, int quiet)

Подпрограмма Initialize выполняет инициализации холодного старта.

Параметры:

mv _far *mV указатель на информационную структуру mv.
int quiet флаг, показывающий, нужно или нет сообщать об ошибках.

Возвращаемое значение: 0 если выполнение было успешным, -1 в случае ошибки (расширение не было загружено).

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

Установленный флаг quiet показывает, что не нужно сообщать об ошибках соответствующими сообщениями.

int WINAPI DLLExport Free(mv _far *mV)

Подпрограмма Free освобождает все ресурсы, которые были выделены в подпрограмме Initialize.

Параметры:

mv _far *mV указатель на информационную структуру mv.

Возвращаемое значение: всегда должна возвращать 0.

Замечание: подпрограмма Free является комплементарной подпрограмме Initialize, т. е. они работают в паре. Эта подпрограмма вызывается только 1 раз для каждого объекта и каждого приложения, независимо от количества дубликатов объектов, размещенных в любом количестве фреймов. В этой подпрограмме Вы должны освободить все, что было выделено процессом холодного старта.

DWORD WINAPI DLLExport GetInfos(int info)

GetInfos выдает номер версии расширения и другую полезную информацию для runtime.

Параметры:

info: запрашиваемое значение.

Возвращаемое значение: зависит от запрашиваемого.

Если параметр info равен константе KGI_PRODUCT, то Вы должны вернуть минимальную версию CF, с которой совместимо Ваше расширение:

PRODUCT_VERSION_HOME = TGF или выше.
PRODUCT_VERSION_STANDARD = CF Standard или выше.
PRODUCT_VERSION_PRO = CF Developer или выше.

Если info равен KGI_BUILD, то Вы должны вернуть минимальный номер сборки CF, с которой совместимо Ваше расширение:

Не меняйте другие части этой подпрограммы.

short WINAPI DLLExport GetRunObjectInfos(mv _far *mV, fpKpxRunInfos infoPtr)

GetRunObjectInfos возвращает информацию о run-time флагах объекта, размере edit-time структур, условия и действия.

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpKpxRunInfos infoPtr указатель на структуру KpxRunInfos.

Возвращает TRUE, если все в порядке, или FALSE в случае ошибки.

Замечания: использование этой подпрограммы хорошо показано в проекте шаблона объекта (Template): можете копировать оттуда код, он работает корректно, и хорошо самодокументирован.

LPCTSTR* WINAPI DLLExport GetDependencies()

Подпрограмма GetDependencies возвращает список специфичных DLL, которые требуются для запуска расширения. Здесь нужно просто вернуть дополнительные DLL, не возвращайте стандартные Windows DLL. Необходимые для расширения DLL должны быть скопированы в папку Data\Runtime системы CF, чтобы CF могла подключить их в независимые приложения. Они будут распакованы в ту же самую временную папку, как и расширение, когда запускается код runtime.

Возвращает: список значений LPCTSTR и значение NULL, обозначающее конец этого списка.

int WINAPI DLLExport EnumElts (mv __far *mV, LPEDATA edPtr, ENUMELTPROC enumProc,
                               ENUMELTPROC undoProc, LPARAM lp1, LPARAM lp2)

Подпрограмма EnumElts вызывается системой CF для перечисления картинок и шрифтов, используемых в объекте расширения. Она вызывается и системой CF, и кодом runtime.

Параметры:

mv _far *mV указатель на информационную структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA.
ENUMELTPROC enumProc указатель на перечисляемую функцию.
ENUMELTPROC undoProc указатель на функцию отмены (undo function).
LPARAM lp1 параметр для передачи в функции enumProc и undoProc.
LPARAM lp2 параметр для передачи в функции enumProc и undoProc.

Возвращаемое значение: код ошибки или 0, если все в порядке. Не нулевое значение останавливает перечисление.

Замечание: эта подпрограмма должна выполнять энумерацию (перечисление по списку) только картинок и шрифтов, которые были сохранены в приложении. Она не должна перечислять временные картинки и шрифты. Эта подпрограмма обычно вызывается, когда объект загружается или сохраняется, и показывает для CF, какие картинки и шрифты сохранять в файл приложения.

Для каждой картинки и шрифта эта подпрограмма должна вызвать функцию enumProc со следующими параметрами:

LPWORD eltPtr указатель на картинку или шрифт (созданную одной из следующих функций MMFS2: DibToImage, WinCreateFont, или функцией mvEditImage).
int eltType тип: IMAGE_TAB если картинка, FONT_TAB если шрифт.
LPARAM lp1 параметр, переданный в EnumElts.
LPARAM lp2 параметр, переданный в EnumElts.

Если enumProc вернет ошибку (не 0), то Вы должны вызвать функцию undoProc для каждой картинки и шрифта, уже переданных в enumProc.

enumProc может менять номер картинки или шрифта, указанного через eltPtr.

Пример: здесь показана энумерация 8 картинок и 4 шрифтов объекта.

int WINAPI DLLExport EnumElts (mv __far *mV, fpedata edPtr, ENUMELTPROC enumProc,
                               ENUMELTPROC undoProc, LPARAM lp1, LPARAM lp2)
{
   int i, j, error = FALSE;

   // Перечисление шрифтов:
   for (i=0; i < 4; i++)
   {
      error = enumProc (&edPtr->nFont[i], FONT_TAB, lp1, lp2);
      if ( error )
      {
         // Отмена перечисленных шрифтов:
         for (j=i-1; j>=0; j--)
            undoProc (&edPtr->nFont[j], FONT_TAB, lp1, lp2);
         break;
      }
   }

   // Перечисление картинок:
   if ( !error )
   {
      for (i=0; i < 8; i++)
      {
         error = enumProc(&edPtr->nImg[i], IMG_TAB, lp1, lp2);
         if ( error )
         {
            // Отмена перечисленных картинок:
            for (j=i-1; j>=0; j--)
               undoProc (&edPtr->nImg[j], IMG_TAB, lp1, lp2);
            // Отмена перечисленных шрифтов:
            for (j=3; j>=0; j--)
               undoProc (&edPtr->nFont, FONT_TAB, lp1, lp2);
            break;
         }
      }
   }
   return error;
}

int WINAPI DLLExport LoadObject(mv _far *mV, LPCTSTR fileName, LPEDATA edPtr, int reserved)

Подпрограмма LoadObject вызывается, когда объект загружается в память, либо когда приложение загружается системой CF, или когда объект загружается кодом runtime.

Параметры:

mv _far *mV указатель на информационную структуру mv.
LPCTSTR fileName указатель на текущее имя файла приложения (application pathname).
LPEDATA edPtr указатель на структуру EDITDATA.
int reserved зарезервировано для будущего использования.

Возвращаемое значение: 0 если все в порядке, -1 в случае обнаруженной ошибки.

Замечания: LoadObject вызывается один раз для каждого отличающегося объекта в каждом фрейме. Например, если Вы дублировали один объект путем вставки копии (paste) в фрейм, то эта функция будет вызвана только один раз. Указатель edPtr покажет на общую структуру EDITDATA для всех дублированных объектов. В этой подпрограмме Вы можете загрузить некоторые данные в зависимости от содержимого структуры EDITDATA, или сохранить указатели.

void WINAPI DLLExport UnloadObject(mv _far *mV, LPEDATA edPtr, int reserved)

Подпрограмма UnloadObject вызывается, когда последний объект определенного вида удаляется из памяти, либо в режиме edit-time, либо в режиме run-time.

Параметры:

mv _far *mV указатель на информационную структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA.
int reserved зарезервировано для будущего использования.

Замечания: UnloadObject вызывается только один раз для каждого отличающегося объекта в каждом фрейме. Например, если Вы сделали дубликат объекта копированием/вставкой его во фрейм, то эта функция будет вызвана все равно только 1 раз. Указатель edPtr покажет на общую структуру EDITDATA для всех дублированных объектов.

Эта подпрограмма освободит все ресурсы, которые были выделены подпрограммой LoadObject.

HGLOBAL WINAPI DLLExport UpdateEditStructure(mv __far *mV, void __far * OldEdPtr)

UpdateEditStructure позволяет Вам преобразовать предыдущую версию (версии) структуры EDITDATA. Она вызывается и в режиме edit-time, и в режиме run-time (поскольку файл подчиненного приложения, созданный в предыдущей версии, может быть загружен более новой версией кода runtime).

Параметры:

mv _far *mV указатель на информационную структуру mv.
void __far * OldEdPtr указатель на структуру редактирования со старой версией.

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

Замечания: структура EDITDATA каждого объекта сохраняется в файлах .MFA / .CCN. Вы можете захотеть добавить в них новые записи с сохранением совместимости с приложениями, сохраненными ранее, тогда нужно обновить эту структуру. Когда номер версии структуры EDITDATA не совпадает с текущим номером версии объекта, то система CF вызовет эту подпрограмму, чтобы Вы могли осуществить процесс обновления. Из старой структуры Вы можете заново создать новую структуру, совместимую с Вашей новой версией.

Если Вы определили больше 2 версий, то не забудьте сделать инкрементальным процесс обновления, поскольку более новая версия ничего не знает о том, какая структура может находится в приложении. Таким образом, для трех разных версий сначала делается обновление от V0 к V1, затем от V1 к V2, и затем от V2 к V3. Если поступать таким образом, то независимо от версий конечная структура будет корректной.

Пример:

HGLOBAL WINAPI DLLExport UpdateEditStructure(mv __far *mV, void __far * OldEdPtr)
{
   HGLOBAL hgNew = NULL;

   if (((fpedata)OldEdPtr)->eHeader.extVersion < KCX_VERSION_1)
   {
      fpedata_v1 newEdPtr;
      if ((hgNew = GlobalAlloc(GPTR, sizeof(editData_v1))) != NULL)
      {
         newEdPtr = (fpedata_v1)GlobalLock(hgNew);
         memcpy(&newEdPtr->eHeader, &((fpedata_v0)OldEdPtr)->eHeader, sizeof(extHeader));
         // Обновление номера версии:
         newEdPtr->eHeader.extVersion = KCX_VERSION_1; 
         // Обновление размера структуры EDITDATA:
         newEdPtr->eHeader.extSize = sizeof(editData_v1);
         newEdPtr->eaviIdApp = ((fpedata_v0)OldEdPtr)->eaviIdApp;
         newEdPtr->eaviImage = ((fpedata_v0)OldEdPtr)->eaviImage;
         newEdPtr->eaviSx = ((fpedata_v0)OldEdPtr)->eaviSx;
         newEdPtr->eaviSy = ((fpedata_v0)OldEdPtr)->eaviSy;
         newEdPtr->eaviFlags = ((fpedata_v0)OldEdPtr)->eaviFlags;
         _tcscpy(newEdPtr->eaviName, ((fpedata_v0)OldEdPtr)->eaviName);
         memcpy(newEdPtr->eaviSecu, ((fpedata_v0)OldEdPtr)->eaviSecu, 16);

         GlobalUnlock(hgNew);
      }
   }
   return hgNew;
}

void WINAPI DLLExport UpdateFileNames(mv _far *mV,
                                      LPTSTR appName,
                                      LPEDATA edPtr,
                                      void (WINAPI * lpfnUpdate)(LPTSTR, LPTSTR))

Подпрограмма UpdateFileNames позволяет именам файла, содержащимся в структуре EDITDATA, быть перемещенными системой CF. Эта функция вызывается системой CF во время выполнения приложения (runtime).

Параметры:

mv _far *mV указатель на информационную структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA.
void (WINAPI * lpfnUpdate)(LPTSTR appName, LPTSTR pathname) указатель на функцию, которая локализует путь до файла.

Замечания: подпрограмма UpdateFileNames вызывается, когда каждый отличающийся объект загружается из каждого фрейма. Эта подпрограмма должна вызвать подпрограмму перемещения для для каждого пути до файла, содержащего в структуре EDITDATA. Подпрограмма UpdateFileNames гарантирует, что путь корректен для места расположения приложения. Буфер, содержащий путь, должен быть размером как минимум _MAX_PATH символов.

Пример:

   // Обновление имени файла:
   if (edPtr->eaviName[0] != 0)
      lpfnUpdate(appName, edPtr->eaviName);

int WINAPI DLLExport CreateObject(mv _far *mV, fpLevObj loPtr, LPEDATA edPtr)

Подпрограмма CreateObject вызывается, когда Вы создаете новый объект в редакторе фрейма. Эта функция может открыть окно диалога настройки объекта (Setup dialog), если оно предусмотрено, и инициализировать структуру редактирования.

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpLevObj loPtr указатель на структуру LO для этой копии объекта.
LPEDATA edPtr указатель на структуру EDITDATA.

Возвращаемое значение: ненулевое, если создание было неудачным, например если пользователь нажал "Отмена" (cancel) в окне диалога, и 0, если объект был создан.

Замечания: некоторые объекты не нуждаются в окне диалога настройки, когда создается объект. В этих случаях подпрограмма CreateObject просто устанавливает инициализационные значения в структуре редактирования.

Пример: здесь показан простой вызов окна настройки (setup dialog box), после чего в структуре EDITDATA инициализируются поля размера.

int WINAPI DLLExport CreateObject(mv _far *mV, fpLevObj loPtr, LPEDATA edPtr)
{
   // Установка для объекта значений по умолчанию:
   edPtr->swidth = 32;
   edPtr->sheight = 32; 

   // Отображения диалога настройки:
   setupParams    spa;
   spa.edpt = edPtr;
   spa.kv = mV;
   if ( DialogBoxParam(hInstLib, MAKEINTRESOURCE(DB_SETUP),
                       mV->mvHEditWin, setupProc,
                       (LPARAM)(LPBYTE)&spa) == IDOK )
   {
      return 0;      // нет ошибки
   } 

   // Ошибка:
   return -1;
}

void WINAPI DLLExport CreateFromFile (mv _far *mV, LPCTSTR fileName, LPEDATA edPtr)

Подпрограмма CreateFromFile вызывается, если UsesFile возвращает TRUE, когда пользователь бросает файл в окно редактора фрейма. Эта функция должна инициализировать структуру EDITDATA.

Параметры:

mv _far *mV указатель на информационную структуру mv.
LPCTSTR fileName имя файла, брошенного в окно редактора фрейма.
LPEDATA edPtr указатель на структуру EDITDATA.

Возвращаемое значение: отсутствует.

Замечания: для дополнительной информации обратитесь к описанию функции UsesFile.

Пример:

void WINAPI    DLLExport CreateFromFile (LPMV mV, LPCTSTR fileName, LPEDATA edPtr)
{
   _tcscpy(edPtr->myFileName, fileName);
}

void WINAPI DLLExport DuplicateObject(mv _far *mV, fpObjInfo oiPtr, LPEDATA edPtr)

Подпрограмма DuplicateObject вызывается, когда объект клонируется в редакторе фрейма, например когда дублируется структура EDITDATA.

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpObjInfo oiPtr указатель на структуру OI.
LPEDATA edPtr указатель на структуру EDITDATA.

Возвращаемое значение: отсутствует.

Замечания: эта подпрограмма позволяет Вам дублировать любую память, выделенную в структуре EDITDATA.

BOOL WINAPI DLLExport EditObject(mv _far *mV, fpObjInfo oiPtr, fpLevObj loPtr, LPEDATA edPtr)

Подпрограмма EditObject вызывается системой CF, когда пользователь выбрал пункт Edit контекстного меню редактора фрейма, или сделал двойной клик на объекте. Вам не нужна эта функция, если Ваш объект использует только свойства (окно диалога настройки не предусмотрено). Однако в некоторых случаях хорошей идеей будет использовать и свойства, и окно диалога настройки.

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpObjInfo oiPtr указатель на структуру OI.
fpLevObj loPtr указатель на структуру LO для этой копии объекта.
LPEDATA edPtr указатель на структуру EDITDATA.

Возвращаемое значение: FALSE, если не сделано никаких модификаций, TRUE для проверки изменений.

Пример:

BOOL WINAPI EditObject (mv _far *mV, fpObjInfo oiPtr, fpLevObj loPtr, LPEDATA edPtr)
{
   // Удалите это, если Ваш объект не имеет диалога настройки:
   setupParams  spa;
   spa.edpt = edPtr;
   spa.kv = mV;
   if ( DialogBoxParam(hInstLib, MAKEINTRESOURCE(DB_SETUP),
        mV->mvHEditWin, setupProc, (LPARAM)(LPBYTE)&spa) == IDOK )
   {
      return TRUE;
   } 
   return FALSE;
}

void WINAPI DLLExport EditorDisplay(mv _far *mV, fpObjInfo oiPtr,
                                    fpLevObj loPtr, LPEDATA edPtr,
                                    RECT FAR *rc)

Подпрограмма EditorDisplay отображает объект в окне редактора фрейма (Frame Editor).

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpObjInfo oiPtr указатель на структуру OI.
fpLevObj loPtr указатель на структуру LO для этой копии объекта.
LPEDATA edPtr указатель на структуру EDITDATA.
RECT FAR *rc указатель на структуру RECT, содержащую размер объекта во фрейме.

Возвращаемое значение: отсутствует.

Замечания: эта подпрограмма в действительности рисует объект в окне редактора фрейма. Вы не должны ничего рисовать вне пределов, ограниченных прямоугольником структуры rc. Вы не должны использовать GetDC и ReleaseDC для получения хендла окна фрейма.

Чтобы нарисовать свой объект, Вы должны получить поверхность CF (surface), присоединенную к окну редактора фрейма для этого объекта, и рисовать по этой поверхности функциями cSurface.

Пример:

void WINAPI DLLExport EditorDisplay(mv _far *mV, fpObjInfo oiPtr,
                                    fpLevObj loPtr, LPEDATA edPtr, RECT FAR *rc)
{
   // Это простой случай рисования картинки во окне редактора фрейма CF.
   // Сначала мы должны получить указатель на поверхность (surface),
   // используемую редактором фрейма:
   LPSURFACE ps = WinGetSurface((int)mV->mvIdEditWin);
   if ( ps != NULL )    // Если поверхность существует, ...
   {
      // ... то выполняем следующие действия:
      int x = rc->left;             // получение наших границ
      int y = rc->top;
      int w = rc->right-rc->left;
      int h = rc->bottom-rc->top; 

      cSurface is;                  // новая переменная поверхности, которую
                                    // мы будем использовать
      // Создание реализации поверхности из прототипа (выиграл редактор фрейма):
      is.Create(4, 4, ps);
      // Загрузка нашей растровой картинки (bitmap) из ресурсов,
      // и переназначение палитры, если это необходимо:
      is.LoadImage(hInstLib, EXO_IMAGE, LI_REMAP);
      // Копирование битового массива картинки (Blit) в поверхность редактора фрейма:
      is.Blit(*ps, x, y, BMODE_TRANSP, BOP_COPY, 0); 

      // Это действительно копирует всю нашу поверхность в поверхность редактора
      // фрейма на указанное место. Мы могли использовать разные эффекты
      // для изображения при копировании, например инверсия, операции AND, OR, XOR,
      // blend (полупрозрачность, 6-й параметр задает величину прозрачности).
      // Вы можете выполнить антиалиасинг с помощью 7-го параметра (по умолчанию = 0,
      // или выключено).
   }
}

void WINAPI EditParameter(mv* mV, short code, paramExt* pExt)

Редактирует пользовательский параметр.

Параметры:

mv* mV указатель на структуру mv, содержащую данные о приложении.
short code код параметра.
paramExt* pExt указатель на структуру paramExt, содержащую Ваш параметр.

Возвращаемое значение: отсутствует.

Замечания: эта функция вызывается, когда пользователь редактирует параметры своего параметра. Это должно открыть окно диалога, или сделать необходимые действия для редактирования параметра, изменения структуры paramExt (особенно поля pExt->pextData), и записи нового размера этого параметра в поле pExt->pextSize. Общий размер, который Вы можете использовать, равен PARAM_EXTMAXSIZE. Система CF выдаст ошибку, если размер превысит это значение (и произойдет сбой, если Вы ДЕЙСТВИТЕЛЬНО превысите этот лимит).

BOOL WINAPI DLLExport EditProp(LPMV mV, LPEDATA edPtr, UINT nPropID)

Эта функция вызывается, когда пользователь кликнет на кнопку свойств (например на кнопке в свойстве Button, или на кнопке в свойстве ComboBoxBtn, или на кнопке в свойстве ImageList).

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

Возвращаемое значение: TRUE, если свойства обновлены, иначе FALSE.

Замечания: если эта подпрограмма возвращает TRUE, то система CF вызовет GetPropertyValue, чтобы получить текущее значение свойства, и вызовет SetPropertyValue для других свойств выбранных объектов.

short WINAPI DLLExport GetActionCodeFromMenu(mv _far *mV, short menuId)

Подпрограмма GetActionCodeFromMenu преобразует идентификатор меню из всплывающих меню действий (action pop-up menu) в код действия (action code).

Параметры:

mv _far *mV указатель на информационную структуру mv.
short menuId идентификатор выбранного элемента меню.

Возвращаемое значение: код действия.

Замечания: в предоставленном шаблоне идентификатор меню определен так, чтобы непосредственно отразить коды условий (condition codes).

LPINFOEVENTSV2 WINAPI DLLExport GetActionInfos(mv _far *mV, short code)

Подпрограмма GetActionInfos возвратит указатель для на структуру infoEventsV2 из кода действия. Указатель является относительным к этому коду.

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код действия.

Возвращаемое значение: указатель на структуру infoEventsV2.

Замечания: в предоставленном шаблоне функция ищет в массиве actionInfo код, и возвращает указатель на эту структуру.

HMENU WINAPI DLLExport GetActionMenu(mv _far *mV, fpObjInfo oiPtr, LPEDATA edPtr)

Подпрограмма GetActionMenu возвратит всплывающее меню действий (action pop-up menu).

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpObjInfo oiPtr указатель на структуру OI.
LPEDATA edPtr указатель на структуру EDITDATA.

Возвращаемое значение: меню для использования.

Замечания: Вы можете скрыть или показать определенные опции, в зависимости от содержимого редактируемой структуры.

void WINAPI DLLExport GetActionString(mv _far *mV, short code,
                                      LPTSTR strPtr, short maxLen)

Подпрограмма GetActionString возвращает строку отображения из кода действия, для использования в редакторе событий (Event Editor).

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код действия.
LPTSTR strPtr буфер для сохранения строки, завершающейся нулем.
short maxLen длина буфера.

Возвращаемое значение: отсутствует.

void WINAPI DLLExport GetActionTitle(mv _far *mV, short code, short param,
                                     LPTSTR strBuf, short maxLen)

Подпрограмма GetActionTitle возвращает строку для отображения, когда вводятся параметры действия.

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код выбранного действия.
short param номер параметра.
LPTSTR strBuf буфер для сохранения строки, завершающейся нулем.
short maxLen длина буфера.

Возвращаемое значение: отсутствует.

Замечания: подпрограмма GetActionTitle, предоставленная в шаблоне, автоматически загружает строку из ресурса, если Вы определили её в массиве.

short WINAPI DLLExport GetConditionCodeFromMenu(mv _far *mV, short menuId)

Подпрограмма GetConditionCodeFromMenu преобразует идентификатор меню из всплывающего меню условия (condition pop-up menu) в код условия (condition code).

Параметры:

mv _far *mV указатель на информационную структуру mv.
short menuId идентификатор выбранного элемента меню.

Возвращаемое значение: код условия.

Замечания: в предоставленном шаблоне идентификатор меню определен так, чтобы непосредственно отражать коды условий.

LPINFOEVENTSV2 WINAPI DLLExport GetConditionInfos(mv _far *mV, short code)

Подпрограмма GetConditionInfos возвращает указатель на структуру InfoEventsV2 из кода условия (condition code). Этот указатель является относительным к этому коду.

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код условия.

Возвращаемое значение: указатель на структуру infoEvents.

Замечания: в предоставленном шаблоне эта функция ищет по массиву условий код, и возвращает часть информации.

HMENU WINAPI DLLExport GetConditionMenu(mv _far *mV, fpObjInfo oiPtr, LPEDATA edPtr)

Подпрограмма GetConditionMenu возвращает всплывающее меню условия (condition pop-up menu).

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpObjInfo oiPtr указатель на структуру OI.
LPEDATA edPtr указатель на структуру EDITDATA.

Возвращаемое значение: меню для использования.

Замечания: Вы можете скрыть или показать определенные опции в зависимости от содержания редактируемой структуры.

void WINAPI DLLExport GetConditionString(mv _far *mV, short code, LPTSTR strPtr, short maxLen)

Подпрограмма GetConditionString возвратит строку отображения из кода условия (condition code), для использования в редакторе событий (Event Editor).

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код условия.
LPTSTR strPtr буфер для сохранения строки, завершающейся нулем.
short maxLen длина буфера.

Возвращаемое значение: отсутствует.

void WINAPI DLLExport GetConditionTitle(mv _far *mV, short code, short param,
                                        LPTSTR strBuf, short maxLen)

Подпрограмма GetConditionTitle возвратит строку для отображения, когда вводятся параметры условия.

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код выбранного параметра.
short param номер параметра.
LPTSTR strBuf буфер для сохранения строки, завершающейся нулем.
short maxLen длина буфера.

Возвращаемое значение: отсутствует.

Замечания: подпрограмма GetConditionTitle, предоставленная в шаблоне, автоматически загружает строку из ресурса, если Вы определите это в массиве.

short WINAPI DLLExport GetExpressionCodeFromMenu(mv _far *mV, short menuId)

Подпрограмма GetExpressionCodeFromMenu преобразует идентификатор меню из всплывающего меню выражения (expression pop-up menu) в код выражения (expression code).

Параметры:

mv _far *mV указатель на информационную структуру mv.
short menuId идентификатор выбранного элемента меню.

Возвращаемое значение: код выражения.

Замечания: в предоставленном шаблоне идентификатор меню определен таким образом, чтобы непосредственно отражать коды выражений (expression codes).

LPINFOEVENTSV2 WINAPI DLLExport GetExpressionInfos(mv _far *mV, short code)

Подпрограмма GetExpressionInfos возвратит указатель на структуру infoEventsV2 из кода выражения (expression code). Этот указатель относителен к этому коду.

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код выражения.

Возвращаемое значение: указатель на структуру infoEventsV2.

Замечания: в предоставленном шаблоне функция ищет код в массиве expressionInfo, и возвращает указатель.

void WINAPI DLLExport GetExpressionParam(mv _far *mV, short code,
                                         short param, LPTSTR strBuf,
                                         short maxLen)

Подпрограмма GetExpressionParam возвратит текст параметра выражения, полученный из кода выражения, для использования в редакторе событий (Event Editor).

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код выражения.
short param индекс параметра.
LPTSTR strBuf буфер для сохранения строки, заканчивающейся нулем.
short maxLen длина буфера.

Возвращаемое значение: отсутствует.

void WINAPI DLLExport GetExpressionString(mv _far *mV, short code,
                                          LPTSTR strPtr, short maxLen)

Подпрограмма GetExpressionString вернет строку отображения, полученную из кода выражения (expression code), для использования в редакторе событий (Event Editor).

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код выражения.
LPTSTR strPtr буфер для сохранения строки, завершающейся нулем.
short maxLen длина буфера.

Возвращаемое значение: отсутствует.

void WINAPI DLLExport GetExpressionTitle(mv _far *mV, short code,
                                         short param, LPTSTR strBuf,
                                         short maxLen)

Подпрограмма GetExpressionTitle возвратит строку для отображения, когда вводятся параметры выражения.

Параметры:

mv _far *mV указатель на информационную структуру mv.
short code код выбранного выражения.
short param номер параметра (0 или 1).
LPTSTR strBuf буфер для сохранения строки, завершающейся нулем.
short maxLen длина буфера.

Возвращаемое значение: отсутствует.

Замечания: подпрограмма GetExpressionTitle, предоставленная в шаблоне, автоматически загружает строку из ресурса, если Вы определили её в массиве.

LPCTSTR WINAPI DLLExport GetHelpFileName()

Подпрограмма GetHelpFileName возвращает имя файла подсказки расширения.

Возвращаемое значение: имя Help-файла.

Замечания: возвращается имя файла без пути до него, если к Вашему help-файлу происходит обращение в главном файле подсказки CF, например _T("MyExt.chm"), или будет возвращен путь до Вашего help-файла относительно директории системы CF, например _T("Help\\MyExt.chm").

Вы должны установить свои help-файлы в каталог Help системы CF.

void WINAPI DLLExport GetObjectRect(mv _far *mV, RECT FAR *rc,
                                    fpLevObj loPtr, LPEDATA edPtr)

Подпрограмма GetObjectRect вызывается системой CF, чтобы определить размеры объекта.

Параметры:

mv _far *mV указатель на информационную структуру mv.
RECT FAR *rc указатель на структуру прямоугольной области, где Вы должны сохранить данные.
fpLevObj loPtr указатель на структуру LO для этой копии объекта.
LPEDATA edPtr указатель на структуру EDITDATA.

Возвращаемое значение: отсутствует.

Замечания: на входе поля left и top структуры RECT устанавливаются в действительные координаты объекта. Вы должны добавить к ним размер Вашего объекта.

void WINAPI  DLLExport GetObjInfos (mv _far *mV, LPEDATA edPtr,
                                    LPTSTR ObjName, LPTSTR ObjAuthor,
                                    LPTSTR ObjCopyright, LPTSTR ObjComment,
                                    LPTSTR ObjHttp)

Подпрограмма GetDesc возвратит строку, описывающую объект.

Параметры:

mv _far *mV указатель на информационную структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA.
LPTSTR objName буфер назначения для имени расширения, максимальное количество символов = 256.
LPTSTR objAuthor буфер назначения для автора расширения, максимальное количество символов = 256.
LPTSTR objCopyright буфер назначения для сообщения о копирайте расширения, максимальное количество символов = 256.
LPTSTR objComment буфер назначения для быстрого описания расширения, максимальное количество символов = 1024.
LPTSTR objHttp буфер назначения для веб-сайта расширения, максимальное количество символов = 256.

Возвращаемое значение: отсутствует.

Замечания: эти строки текста отображаются в свойствах About объекта. Текст ObjComment отображается также в диалоге создания нового объекта (Create New Object).

Пример:

void WINAPI  DLLExport GetObjInfos (mv _far *mV, LPEDATA edPtr,
                                    LPTSTR ObjName, LPTSTR ObjAuthor,
                                    LPTSTR ObjCopyright, LPTSTR ObjComment,
                                    LPTSTR ObjHttp)
{
   // Имя:
   LoadString(hInstLib, IDST_OBJNAME, ObjName, 255); 
   // Автор:
   LoadString(hInstLib, IDST_AUTHOR, ObjAuthor, 255);
   // Копирайт:
   LoadString(hInstLib, IDST_COPYRIGHT, ObjCopyright, 255);
   // Комментарий:
   LoadString(hInstLib, IDST_COMMENT, ObjComment, 1024);
   // Адрес в Интернете:
   LoadString(hInstLib, IDST_HTTP, ObjHttp, 255);
}

void WINAPI GetParameterString(mv* mV, short code, paramExt* pExt,
                               LPTSTR pDest, short size)

Возвратит строку, описывающую пользовательский параметр.

Параметры:

mv* mV указатель на структуру mv, содержащую данные о приложении.
short code код параметра.
paramExt* pExt указатель на структуру paramExt, содержащую Ваш параметр.
LPTSTR pDest указатель на символьный буфер, куда Вы должны скопировать строку, описывающую Ваш параметр.
short size размер буфера pDest.

Возвращаемое значение: отсутствует.

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

BOOL WINAPI DLLExport GetPropCheck(LPMV mV, LPEDATA edPtr, UINT nPropID)

Эта функция вызывается системой CF, чтобы узнать состояние галочки (checkmark) свойства.

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
UINT nPropID запрашиваемый идентификатор свойства.

Возвращаемое значение: TRUE (галочка стоит, checked), или FALSE (галочка снята, unchecked).

Замечания: эта функция вызывается только для опций-галочек, так что если в списке Ваших свойств есть и галочки, и значения, то должны реализовать и GetPropValue и GetPropCheck.

Пример:

BOOL WINAPI DLLExport GetPropCheck(LPMV mV, LPEDATA edPtr, UINT nPropID)
{
   switch (nPropID)
   {
   case PROPID_MYCHECKBOX:
      // Будет возвращено 0 (галочка снята, unchecked)
      // или 1 (галочка стоит, checked):
      return edPtr->nCheck;
   }
   return 0;      // галочка снята, unchecked
}

LPARAM WINAPI DLLExport GetPropCreateParam(LPMV mV, LPEDATA edPtr, UINT nPropID)

Эта функция вызывается системой CF, чтобы получить параметр, связанный со свойством, если параметр NULL в определении свойства.

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

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

Замечания: есть 2 способа передать инициализационные данные в свойство. Либо Вы вводите их непосредственно в макрос PropData таблицы свойств, либо Вы используете параметр NULL в макросе PropData и возвратить параметр в функции GetPropCreateParam. Второе решение позволяет Вам динамически менять содержимое свойства (например элемент списка свойства списка выбора, combo box property).

Если Вы выделяете память в этой функции, то должны освободить её в функции ReleasePropCreateParam.

Пример:

LPARAM WINAPI DLLExport GetPropCreateParam(LPMV mV, LPEDATA edPtr, UINT nPropID)
{
   if ( nPropID == PROPID_COMBO )
   {
      switch (edPtr->sType)
      {
      case TYPE1:
         return (LPARAM)ComboList1;
      case TYPE2:
         return (LPARAM)ComboList2;
      }
   }
   return NULL;
}

BOOL WINAPI DLLExport GetProperties(LPMV mV, LPEDATA edPtr, BOOL bMasterItem)

Вызывается системой CF для получения определений свойств объекта.

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
BOOL bMasterItem TRUE, если объект является основным объектом во множественном выборе.

Возвращаемое значение: TRUE, если все прошло хорошо.

Замечания: эта подпрограмма должна сказать CF вставить список свойств путем использования следующей функции обратного вызова (callback):

mvInsertProps(mV, edPtr, Properties, PROPID_TAB_GENERAL, TRUE);

Здесь Properties указывает на массив PropData, определяющий свойства. Обратите внимание, что Ваш объект может иметь несколько массивов PropData, и GetProperties может выбрать правильный массив, определяющий состояние объекта.

Вы можете также удалить предопределенные свойства макросом mvRemoveProperty, если это необходимо.

Пример этой подпрограммы можно найти в проекте объекта Template (шаблон, где показана реализация объекта).

LPVOID WINAPI DLLExport GetPropValue(LPMV mV, LPEDATA edPtr, UINT nPropID)

Эта функция вызывается системой CF, чтобы получить значение свойства объекта.

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор нужного свойства.

Возвращаемое значение: должно быть объектом CPropValue (объектом, являющимся производным от объекта CPropValue). Тип CPropValue зависит от типа свойства. Например, свойство EditNumber нуждается в CPropDWordValue, свойство EditString нуждается в CPropDataValue, инициализированном строкой, и т. д.

Замечания: для возврата значения просто напишите следующую строку кода:

return new CPropDWordValue( myValue);

   или

return new CPropDataValue(buffer, size);

   или

return new CPropStringValue(myString);

   или

return new CPropSizeValue(width, height);

... и т. д.

Примечание: GetPropValue не вызывается для простых чекбоксов (PropData_CheckBox), Вы должны реализовать функцию GetPropCheck для таких свойств.

Пример:

LPVOID WINAPI DLLExport GetPropValue(LPMV mV, LPEDATA edPtr, UINT nPropID)
{
   switch (nPropID)
   {
   case PROPID_COLOR:
      // Возврат цвета:
      return new CPropDWordValue(edPtr->dwColor);
   case PROPID_TEXT:
      // Возврат строки:
      return new CPropStringValue(edPtr->szText);
   case PROPID_COMBO:
      // Возврат значения из выпадающего списка (combo box):
      return new CPropDWordValue(edPtr->nComboIndex);
   }
   return NULL;
}

DWORD WINAPI DLLExport GetTextAlignment(mv _far *mV, LPEDATA edPtr)

Функция GetTextAlignement вызывается системой CF для получения текущего выравнивания текста text.

Параметры:

mv _far *mV указатель на структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA объекта.

Возвращаемое значение: DWORD, содержащее текущие флаги выравнивания. Эти флаги должны быть следующими масками (одна или несколько масок, объединенных операцией ИЛИ):

TEXT_ALIGN_LEFT
TEXT_ALIGN_HCENTER
TEXT_ALIGN_RIGHT
TEXT_ALIGN_TOP
TEXT_ALIGN_VCENTER
TEXT_ALIGN_BOTTOM

Замечания: Вы должны сохранить эти флаги в своей структуре EDITDATA, и возвратить их в этой подпрограмме.

Вы должны возвратить флаги выравнивания, поддерживаемые Вашим объектом, в функции GetTextCaps, когда эта функция была вызвана.

DWORD WINAPI DLLExport GetTextCaps(mv _far *mV, LPEDATA edPtr)

Эта подпрограмма вызывается системой CF, чтобы узнать свойства шрифта, который ей нужно обработать.

Параметры:

mv _far *mV указатель на структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA объекта.

Возвращаемое значение: DWORD, содержащее флаги, показывающие обрабатываемые свойства. Эти флаги могут быть одним или несколькими из следующих значений (объединенными операцией ИЛИ):

TEXT_FONT показывает, что возможен выбор шрифта. Вы должны будете реализовать функции GetTextFont и SetTextFont.

TEXT_COLOR поддерживается цвет текста. Вы должны будете реализовать функции GetTextClr и SetTextClr.

TEXT_ALIGN_LEFT
TEXT_ALIGN_HCENTER
TEXT_ALIGN_RIGHT
TEXT_ALIGN_TOP
TEXT_ALIGN_VCENTER
TEXT_ALIGN_BOTTOM

Все вышеперечисленные флаги показывают поддержку выравнивания шрифта. Из значения понятны из названия флага. Вы должны будете реализовать в своем коде объекта функции GetTextAlignement и SetTextAlignement.

Пример: проект Template содержит пример для такой функции.

COLORREF WINAPI DLLExport GetTextClr(mv _far *mV, LPEDATA edPtr)

Эта функция вызывается системой CF, чтобы получить текущий цвет текста объекта.

Параметры:

mv _far *mV указатель на структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA объекта.

Возвращаемое значение: COLORREF, содержащее текущий цвет текста объекта.

Пример: проект Template содержит пример для такой функции.

Вы должны вернуть TEXT_COLOR в функции GetTextCaps, чтобы вызывалась функция GetTextClr.

BOOL WINAPI DLLExport GetTextFont(mv _far *mV, LPEDATA edPtr,
                                  LPLOGFONT plf, LPTSTR pStyle,
                                  UINT cbSize)

Эта функция вызывается системой CF, чтобы получить текущий шрифт объекта.

Параметры:

mv _far *mV указатель на структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
LPLOGFONT plf указатель на структуру LOGFONT (место расположения получаемых данных).
LPTSTR pStyle указатель на место назначения для строки стиля (больше не используется в CF, игнорируйте этот параметр).
UINT cbSize размер в байтах строки стиля (больше не используется в CF, игнорируйте этот параметр).

Возвращаемое значение: TRUE если все хорошо, иначе FALSE в случае ошибки.

Замечание: Вы должны сохранить LOGFONT в своей структуре EDITDATA. Эта функция должна всего лишь копировать эту структуру из EDITDATA.

Пример: проект шаблона содержит пример такой функции.

Вы должны возвратить TEXT_FONT в функции GetTextCaps, чтобы вызывалась функция GetTextFont.

void WINAPI InitParameter(mv* mV, short code, paramExt* pExt)

Инициализирует новый параметр.

Параметры:

mv* mV указатель на структуру mv, содержащую данные о приложении.
short code код параметра.
paramExt* pExt указатель на зону памяти, в которой Вы можете редактировать свой параметр.

Возвращаемое значение: отсутствует.

Замечания: эта функция вызывается, когда пользователь выбирает действие (action), содержащее Ваш новый параметр. Параметр pExt указывает на структуру paramExt, которая содержит Ваш новый параметр. Вы должны записать свои данные в поля pExt->pextData. И вы должны записать новый размер структуры в поле pExt->pextSize. Общий размер, который Вы можете использовать, равен PARAM_EXTMAXSIZE. Система CF выдаст ошибку, если Вы превысите это значение.

BOOL WINAPI DLLExport IsPropEnabled(LPMV mV, LPEDATA edPtr, UINT nPropID)

Эта функция вызывается системой CF, чтобы узнать, разрешено свойство или нет.

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

Возвращаемое значение: TRUE, если свойство разрешено, иначе FALSE.

Замечания: если Вы не реализуете эту функцию, то все свойства будут разрешены.

BOOL WINAPI DLLExport IsTransparent(mv _far *mV, fpLevObj loPtr,
                                    LPEDATA edPtr, int dx, int dy)

Подпрограмма IsTransparent вызывается системой CF, когда указатель мыши перемещается через одну из копий объекта расширения в редакторе фрейма. Эта подпрограмма показывает, является ли эта точка прозрачной. Если объект прозрачный, то клик мыши выберет объект, который лежит ниже прозрачного объекта.

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpLevObj loPtr указатель на структуру LO для этой копии объекта.
LPEDATA edPtr указатель на структуру EDITDATA.
int dx X смещение точки для проверки относительно левой границы объекта.
int dx Y смещение точки для проверки относительно верхней границы объекта.

Возвращаемое значение: TRUE, если точка прозрачна, FALSE если непрозрачна.

Замечания: используйте эту подпрограмму, если хотите создать очень точный объект.

int WINAPI DLLExport MakeIconEx (mv _far *mV, cSurface* pIconSf,
                                 LPTSTR lpName, fpObjInfo oiPtr,
                                 LPEDATA edPtr)

Подпрограмма MakeIconEx рисует на поверхности (surface) иконку, когда отображается объект в заголовочной полосе редактора событий.

Параметры:

mv _far *mV указатель на информационную структуру mv.
cSurface* pIconSf поверхность, куда загружается иконка.
LPTSTR lpName имя объекта.
fpObjInfo oiPtr указатель на структуру OI.
LPEDATA edPtr указатель на структуру EDITDATA.

Возвращаемое значение: 0 если все в порядке, и любое не нулевое значение, показывающее, что произошла ошибка.

Замечания: эта функция должна загрузить или нарисовать иконку объекта в поверхность pIconSf. Вы можете поменять размер поверхности, система CF уменьшит её до правильного размера, если это необходимо. CF использует иконки размером 32 x 32 точек.

Старые версии этой функции могли поменять имя через параметр lpName. В этой версии такое не рекомендуется.

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

void WINAPI DLLExport PrepareToWriteObject(mv _far *mV,
                                           LPEDATA edPtr,
                                           fpObjInfo oiPtr)

Подпрограмма PrepareToWriteObject вызывается системой CF перед записью структуры редактирования (EDITDATA) на диск, когда сохраняется приложение.

Параметры:

mv _far *mV указатель на информационную структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA.
fpObjInfo oiPtr указатель на структуру OI.

Возвращаемое значение: отсутствует.

Замечания: Вы можете захотеть очистить структуру перед её записью!

Структура EDITDATA, которая передается в PrepareToWriteObject, является временной копией структуры EDITDATA объекта, так что Вы можете её очистить без сохранения изменений.

void WINAPI DLLExport PutObject(mv _far *mV, fpLevObj loPtr,
                                LPEDATA edPtr, WORD cpt)

Подпрограмма PutObject вызывается каждый раз, когда объект бросается на игровое поле фрейма.

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpLevObj loPtr указатель на структуру LO.
LPEDATA edPtr указатель на структуру EDITDATA.
WORD cpt количество одинаковых объектов на игровом поле.

Возвращаемое значение: отсутствует.

Замечания: каждый раз, когда один объект бросается на игровое поле, система CF вызывает подпрограмму PutObject. Параметр cpt отражает количество одинаковых объектов на фрейме (одинаковые объекты все указывают на одну и ту же структуру времени редактирования, edit-time structure, и одну и ту же структуру OI). Вам может потребоваться загрузить некоторые данные для первого объекта.

Пример: в действительности разработчики CF нигде не использует эту подпрограмму!

void WINAPI DLLExport ReleasePropCreateParam(LPMV mV, LPEDATA edPtr,
                                             UINT nPropID, LPARAM lCreateParam);

Эта функция вызывается системой CF после завершения использования пользовательского параметра. Вы должны использовать эту функцию для освобождения памяти, если Вы выделили её в функции GetPropCreateParam.

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.
LPARAM lCreateParam параметр, который Вы возвратили в GetPropCreateParam.

Возвращаемое значение: отсутствует.

Замечания: реализуйте эту функцию только если Вы выделяете память в функции GetPropCreateParam. Эта функция позволяет Вам безопасно освободить память, когда она больше не используется.

void WINAPI DLLExport ReleaseProperties(LPMV mV,
                                        LPEDATA edPtr,
                                        BOOL bMasterItem)

Система CF вызывает эту подпрограмму, когда свойства объекта удаляются из окна свойств (Property window).

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
BOOL bMasterItem TRUE, если объект главный элемент в множественном выборе.

Возвращаемое значение: отсутствует.

Замечания: Вы можете использовать эту подпрограмму для освобождения любой памяти или чего-нибудь, что было выделено Вами в GetProperties.

void WINAPI DLLExport RemoveObject(mv _far *mV, fpLevObj loPtr,
                                   LPEDATA edPtr, ushort cpt)

Подпрограмма RemoveObject вызывается каждый раз, когда объект удаляется из фрейма.

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpLevObj loPtr указатель на структуру LO.
LPEDATA edPtr указатель на структуру EDITDATA.
ushort cpt количество одинаковых объектов в игровом поле.

Возвращаемое значение: отсутствует.

Замечания: подпрограмма RemoveObject является антиподом PutObject. Каждый раз, когда объект удаляется из фрейма, CF вызывает подпрограмму RemoveObject. Параметр cpt отражает количество одинаковых объектов, оставшихся на фрейме (все одинаковые объекты указывают на одну и ту же структуру времени редактирования, edit-time structure, и одну и ту же структуру OI). Значение параметра cpt=1 означает, что Вы удаляете последний объект, так что может понадобиться освободить некоторые данные.

Пример: в действительности разработчики CF никогда не используют эту подпрограмму!

BOOL WINAPI DLLExport SetEditSize(LPMV mv, LPEDATA edPtr, int cx, int cy)

Эта функция вызывается системой CF, когда модифицируется размер объекта в редакторе фрейма.

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
int cx новая ширина.
int cy новая высота.

Возвращаемое значение: TRUE, если размер был изменен.

Замечание: эта функция заменяет старое значение MODIF_SIZE в подпрограмме ModifyObject предыдущих версий SDK.

Если эта функция присутствует, то система CF подразумевает, что Ваш объект может менять размеры. Если этой функции нет, то соответственно CF подразумевает, что Ваш размер не может менять размеры.

void WINAPI DLLExport SetPropCheck(LPMV mV, LPEDATA edPtr,
                                   UINT nPropID, BOOL nCheck)

Эта функция вызывается системой CF, когда пользователь поменял галочку в свойствах объекта.

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.
BOOL nCheck текущее состояние свойства.

Возвращаемое значение: отсутствует.

Замечания: эта функция является антиподом GetPropCheck. Вам нужно сохранить состояние свойства в своей структуре EDITDATA.

Пример: пример этой функции можно найти в проекте Template.

void WINAPI DLLExport SetPropValue(LPMV mV, LPEDATA edPtr,
                                   UINT nPropID, LPVOID lParam)

Эта функция вызывается системой CF для изменения значения свойства, когда пользователь изменил свойства на экране.

Параметры:

LPMV mV указатель на структуру mV.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства для модификации.
LPVOID lParam содержит указатель на объект CPropValue, содержащий новое значение свойства.

Возвращаемое значение: отсутствует.

Замечания: тип CPropValue, сохраняемый в lParam, зависит от типа свойства. Чтобы получить эти данные, Вам нужно сделать приведение типа (cast) параметра lParam в один из классов CPropValue. Пример:

DWORD myDWordValue = ((CPropDWordValue*)lParam)->m_dwValue;

float myFloatValue = ((CPropFloatValue*)lParam)->m_fValue;
LPCTSTR myStringPointer = ((CPropStringValue*)pValue)->GetString();

Пример:

void WINAPI DLLExport SetPropValue(LPMV mV, LPEDATA edPtr,
                                   UINT nPropID, LPVOID lParam)
{
   // Получение указателя на структуру CPropValue:
   CPropValue* pValue = (CPropValue*)lParam;
   LPEDATA pNewPtr;

   switch (nPropID)
   {
   case PROPID_COMBO:
      // Простая выборка значения:
      edPtr->nComboIndex = ((CPropDWordValue*)pValue)->m_dwValue;
      break;
   case PROPID_COLOR:
      // Здесь также просто берется значение:
      edPtr->dwColor = ((CPropDWordValue*)pValue)->m_dwValue;
      break;
   case PROPID_TEXT:
      // Получение строки:
      LPCTSTR pStr = ((CPropStringValue*)pValue)->GetString();
      // Вы можете просто записать строку, если Ваша структура EDITDATA
      // имеет фиксированный размер, или Вам нужно использовать подстраиваемый
      // размер структуры, примерно как показано ниже.
      if (_tcslen(pStr)!=_tcslen(edPtr->text))
      {
         // Если длина отличается, то у CF запрашивается переразмещение
         // (reallocate) структуры на новый размер:
         pNewPtr=(LPEDATA)mvReAllocEditData(mV,
                                            edPtr,
                                            sizeof(EDITDATA)+_tcslen(pStr)*sizeof(TCHAR));
         if (pNewPtr!=NULL)
         {
            // Если переразмещение сработало, копируем строку:
            edPtr=pNewPtr;
            _tcscpy(edPtr->text, pStr);
         }
      }
      else
      {
         // Одинаковый размер: простое копирование:
         _tcscpy(edPtr->text, pStr);
      }
      break;
   }
   // Вы можете захотеть иметь перерисовку своего объекта в редакторе фрейма
   // после изменений. В нашем случае просто вызовем эту функцию:
   mvInvalidateObject(mV, edPtr);
}

void WINAPI DLLExport SetTextAlignment(mv _far *mV, LPEDATA edPtr, DWORD dwAlignFlags)

CF вызывает эту функцию, когда у объекта изменяются флаги выравнивания текста.

Параметры:

mv _far *mV указатель на структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
DWORD dwAlignFlags новые флаги выравнивания. Это значение может быть создано одним или большим (операцией ИЛИ) количеством масок:

TEXT_ALIGN_LEFT
TEXT_ALIGN_HCENTER
TEXT_ALIGN_RIGHT
TEXT_ALIGN_TOP
TEXT_ALIGN_VCENTER
TEXT_ALIGN_BOTTOM

Возвращаемое значение: отсутствует.

Замечание: эта функция должна сохранить флаги в структуру EDITDATA объекта.

Вы должны возвратить флаги выравнивания, поддерживаемые Вашим объектом, в функции GetTextCaps, чтобы функция SetTextAlignment могла быть вызвана.

void WINAPI DLLExport SetTextClr(mv _far *mV, LPEDATA edPtr, COLORREF color)

Эта функция вызывается системой CF, когда пользователь завершает модификацию цвета шрифта объекта.

Параметры:

mv _far *mV указатель на структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
COLORREF color новый цвет.

Возвращаемое значение: отсутствует.

Замечание: эта функция должна просто сохранять цвет в структуре EDITDATA объекта.

Пример: пример этой функции можно найти в проекте Template.

Вы должны вернуть TEXT_COLOR в функции GetTextCaps, чтобы могла быть вызвана функция SetTextClr.

BOOL WINAPI DLLExport SetTextFont(mv _far *mV, LPEDATA edPtr,
                                  LPLOGFONT plf, LPCTSTR pStyle)

Эта функция вызывается системой CF, чтобы изменить шрифт объекта.

Параметры:

mv _far *mV указатель на структуру mv.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
LPLOGFONT plf указатель на источник структуры LOGFONT.
LPCTSTR pStyle указатель на источник строки стиля (больше не используется в CF, игнорируйте это).

Возвращаемое значение: эта функция должна вернуть TRUE, если шрифт был корректно скопирован.

Замечания: эта подпрограмма должна просто скопировать LOGFONT в структуру EDITDATA объекта.

Пример: проект Template содержит пример для такой функции.

Вы должны возвратить TEXT_FONT в функции GetTextCaps, чтобы могла быть вызвана функция SetTextFont.

BOOL WINAPI DLLExport UsesFile(mv _far *mV, LPCTSTR fileName)

Система CF вызывает подпрограмму UsesFile, когда пользователь бросает файл в редактор фрейма, чтобы узнать, поддерживает ли расширение этот файл.

Параметры:

mv _far *mV указатель на информационную структуру mv.
LPCTSTR fileName путь до файла, брошенного в редактор фрейма.

Возвращаемое значение: TRUE, если расширение поддерживает этот файл.

Замечания: если UsesFile вернет TRUE, то CF добавляет расширение в список объектов, которые можно создать из этого файла. Если пользователь выбирает это расширение, то CF вызывает функцию CreateFromFile для создания расширения. Функция CreateObject не вызывается, так что Вы должны дублировать любую инициализацию из CreateObject, если это необходимо.

Пример:

BOOL WINAPI DLLExport UsesFile (LPMV mV, LPCTSTR fileName)
{
   BOOL r = FALSE; 

   // Пример возвращает TRUE, если расширение файла ".txt".
   TCHAR ext[_MAX_EXT];
   if ( fileName != NULL )
   {
      _tsplitpath(fileName, NULL, NULL, NULL, ext);
      if ( _tcsicmp(ext, ".txt") == 0 )
         r = TRUE;
   }
   return r;
}

short WINAPI DLLExport ContinueRunObject(LPRDATA rdPtr)

Подпрограмма ContinueRunObject перезапускает объект после паузы.

Параметры:

LPRDATA rdPtr указатель на структуру run-time.

Возвращаемое значение: функция должна вернуть 0.

Замечания: подпрограмма ContinueRunObject вызывается, когда пользователь завершает режим паузы. Это должно перезапустить любой эффект, остановленный функцией PauseRunObject.

short WINAPI DLLExport CreateRunObject(LPRDATA rdPtr, LPEDATA edPtr, fpcob cobPtr)

Подпрограмма CreateRunObject создает объект во время работы приложения (run-time).

Параметры:

LPRDATA rdPtr указатель на run-time структуру объекта, резервированную системой CF. Эта структура всегда обнуляется.
LPEDATA edPtr указатель на структуру EDITDATA объекта.
fpcob cobPtr указатель на структуру CreateObject.

Возвращаемое значение: 0, если объект создан успешно, !=0 если создание было неудачным.

Замечания: эта подпрограмма вызывается только 1 раз для каждого объекта. Могут быть безопасно проведены выделения памяти, которые будут уничтожены в функции DestroyRunObject.

CreateRunObject формирует связь между структурой редактирования EDITDATA и структурой кода реального времени (run-time structure) RUNDATA. В этой функции Вы должны скопировать все необходимые элементы из структуры редактирования в структуру run-time. У Вас не будет доступа к структуре редактирования, когда работает приложение (run-time).

По большей части Вы свободны делать в этой функции все, что захотите. Однако Вы здесь не можете записывать в экран. Любые графические операции должны быть реализованы в подпрограмме DisplayRunObject.

Если CreateRunObject терпит сбой, то все равно будет вызвана функция DestroyRunObject.

Если Вы не определили подпрограмму GetZoneInfo, то должны установить поля rdPtr->rHo.hoImgWidth, rdPtr->rHo.hoImgHeight, rdPtr->rHo.hoImgXSpot и rdPtr->rHo.hoImgYSpot своего объекта, чтобы получить корректное отображение.

short WINAPI DLLExport DestroyRunObject(LPRDATA rdPtr, long fast)

Подпрограмма DestroyRunObject удаляет объект во время работы приложения (run-time).

Параметры:

LPRDATA rdPtr указатель на run-time структуру объекта.
long fast флаг, показывающий режим удаления. Медленный режим (Slow, когда fast==0) используется внутри приложения. Объект будет полностью удален после 2 тактов, чтобы объект был правильно стерт с экрана. Быстрый режим (Fast, когда fast==1) используется для критических моментов, когда Вы можете не волноваться о качестве очистки экрана.

Возвращаемое значение: эта функция всегда должна возвращать 0.

Замечания: не беспокойтесь по поводу флага fast, это автоматически обрабатывается системой CF. Эта подпрограмма должна удалить любые выделения памяти, произошедшие за время жизни объекта, и оставить место чистым, как все было в перед созданием объекта.

Эта подпрограмма вызывается только 1 раз для каждого объекта. Она также вызывается, если CreateRunObject не может создать объект.

short WINAPI DLLExport DisplayRunObject(LPRDATA rdPtr)

Подпрограмма DisplayRunObject рисует объект на экране.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.

Возвращаемое значение: эта функция должна возвратить 0.

Замечания: только подпрограмма DisplayRunObject рисует объекты на экране.

В этой статье Вы найдете больше информации о том, как рисовать на экране CF с помощью функций MMFS2.DLL. Для этой цели Вы не можете использовать API-функции Windows GetDC и ReleaseDC, Вы должны использовать функции cSurface.

Если Ваш объект в действительности не отрисовывается на экране, но является окном, например, то Вы должны использовать функцию DisplayRunObject для изменения размера и позиции окна. Эти параметры не должны быть изменены посередине подпрограмм действия (action routines), за исключением случаев, когда Вам реально требуется непосредственное перемещение.

void WINAPI DLLExport EditDebugItem(LPRDATA rdPtr, int id)

Эта функция вызывается во время работы программы (runtime), когда пользователь выбрал редактирование отлаживаемого элемента в окне отладки (debugging screen).

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта.
int id идентификатор отлаживаемого элемента.

Возвращаемое значение: отсутствует.

Замечание: эта функция может решить открыть окно диалога для редактирования параметра, или сделать то, что хочет. Приложение ставится на паузу, когда вызывается эта функция, так что Вы можете не торопиться.

Вы также можете использовать две callback-функции, которые будут редактировать это для Вас. Для текста:

callRunTimeFunction(rdPtr, RFUNCTION_EDITTEXT, 0, (LPARAM)&dbi);

И для числа:

long ret=callRunTimeFunction(rdPtr, RFUNCTION_EDITINT, 0, (LPARAM)&dbi);

Пример: Вы найдете пример реализации в проекте Template.

void WINAPI DLLExport EndApp(mv *mV, CRunApp* pApp)

Эта функция вызывается только 1 раз для каждого расширения, когда приложение закрывается.

Параметры:

mv *mV указатель на информационную структуру mv.
CRunApp* pApp приложение, которое завершается.

Возвращаемое значение: отсутствует.

Замечания: EndApp не вызывается, когда приложение перезапускается (действием Restart Application).

Если Ваш объект использует глобальные данные, сохраненные в пользовательских данных расширения, то здесь Вы должны их освободить. Пример:

   CMyData* pData = (CMyData*)mV->mvGetExtUserData(pApp, hInstLib);
   if ( pData != NULL )
   {
      delete pData;
      mV->mvSetExtUserData(pApp, hInstLib, NULL);
   }

Здесь hInstLib это HINSTANCE расширения.

void WINAPI DLLExport EndFrame(mv *mV, CRunApp* pApp, int nFrame)

Эта функция вызывается только один раз для каждого расширения, когда завершается фрейм.

Параметры:

mv *mV указатель на информационную структуру mv.
CRunApp* pApp текущее приложение.
int nFrame индекс фрейма, который завершается.

Возвращаемое значение: отсутствует.

Замечания: EndFrame не вызывается, когда перезапускается фрейм (через действие Restart Frame).

void WINAPI DLLExport GetDebugItem(LPTSTR pBuffer, LPRDATA rdPtr, int id)

Эта функция вызывается во время работы приложения (runtime) чтобы узнать значение одного из отлаживаемых элементов.

Параметры:

LPTSTR pBuffer указатель на текстовый буфер длиной DB_BUFFERSIZE, в который Вам нужно поместить текст для отображения на экране отладчика (debugger screen).
LPRDATA rdPtr указатель на структуру RUNDATA объекта.
int id идентификатор отлаживаемого элемента.

Замечания: просто вставьте строку для отображения, это может быть все что угодно от числа (в виде ASCII) до текста. Учитывайте размер буфера.

LPWORD WINAPI DLLExport GetDebugTree(LPRDATA rdPtr)

Эта подпрограмма вызывается во время работы приложения (runtime), чтобы получить список отлаживаемых элементов (debugger items).

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта.

Возвращаемое значение: указатель на массив, содержащий определение дерева отладчика (debugger tree).

short WINAPI DLLExport GetZoneInfo(LPRDATA rdPtr)

Подпрограмма GetZoneInfo вычисляет текущий размер объекта для сохранения фона.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.

Возвращаемое значение: должно быть возвращено TRUE.

Замечания: нужно использовать эту подпрограмму только если меняются размер и горячие точки (hot spots) Вашего объекта. Если эта функция определена, то она вызывается непосредственно перед процессом сохранения фона, и Вы должны обновить поля rdPtr->rHo.hoImgWidth, rdPtr->rHo.hoImgHeight, rdPtr->rHo.hoImgXSpot и rdPtr->rHo.hoImgYSpot в зоне данных run-time объекта в текущий размер. Эти значения используются немедленно (как и rdPtr->rHo.hoX, rdPtr->rHo.hoY) для вычисления размера экрана для сохранения в буфер.

WORD WINAPI DLLExport GetRunObjectDataSize(LPRH rhPtr, LPEDATA edPtr)

Подпрограмма GetRunObjectDataSize возвращает размер run-time структуры.

Параметры:

LPRH rhPtr указатель главную run-time структуру CF.
LPEDATA edPtr указатель на структуру EDITDATA.

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

Замечания: эта подпрограмма вызывается непосредственно перед тем, как объект будет создан. Обычно каждый возвращает размер run-time структуры RUNDATA, но Вам может понадобится другой размер для сохранения строк или массивов значений.

void WINAPI GetRunObjectFont(LPRDATA rdPtr, LOGFONT* pLf)

Функция GetRunObjectFont возвратит LOGFONT, содержащий текущий шрифт, используемый объектом.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.
LOGFONT* pLf указатель на структуру LOGFONT, в которой Вы должны копировать данные.

Возвращаемое значение: отсутствует.

Замечания: эта подпрограмма вызывается только в том случае, когда установлен флаг OEFLAG_TEXT. Она должна скопировать LOGFONT текущего шрифта, используемого объектом, по указателю LOGFONT, который передан на входе через параметр. Если в Вашей структуре RUNDATA нет LOGFONT, то Вы можете использовать функцию GetObject из Windows API, чтобы преобразовать HFONT в LOGFONT.

short WINAPI DLLExport GetRunObjectInfos(mv _far *mV, fpKpxRunInfos infoPtr)

Подпрограмма GetRunOjbectInfos возвращает информацию о run-time флагах объекта, размер структур времени редактирования (edit-time structures), условия (conditions) и действия (actions).

Параметры:

mv _far *mV указатель на информационную структуру mv.
fpKpxRunInfos infoPtr указатель на структуру KpxRunInfos.

Возвращаемое значение: TRUE если все хорошо, FALSE если обнаружена ошибка.

Замечания: как использовать эту подпрограмму показано в проекте Template, Вы можете скопировать её целиком, она работает нормально, и код интуитивно понятен.

COLORREF WINAPI GetRunObjectTextColor( LPRDATA rdPtr)

Функция GetRunObjectTextColor возвращает текущий цвет шрифта, используемого в объекте.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.

Возвращаемое значение: значение RGB, содержащее текущий цвет текста.

Замечания: эта подпрограмма вызывается только тогда, когда установлен флаг OEFLAG_TEXT.

Просто возвратите текущий цвет текста, используемого в Вашем объекте, как значение COLORREF.

short WINAPI DLLExport HandleRunObject(LPRDATA rdPtr)

Подпрограмма HandleRunObject вызывается каждые 1/50 секунды, когда работает приложение (если в Вашем приложении есть скорость обновления фреймов 50 fps). Эта подпрограмма обрабатывает каждую задачу, которую выполняет объект.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.

Возвращаемое значение: может быть возвращено значение, состоящее из одного или большего количества следующих флагов (объединенных операцией ИЛИ):

REFLAG_ONESHOT показывает, что подпрограмма больше не может быть вызвана.
REFLAG_DISPLAY показывает, что должна быть вызвана подпрограмма DisplayRunObject.

Замечания: флаг REFLAG_ONESHOT обычно используется для объектов, где HandleRunObject ничего не делает, и это экономит процессорное время приложения. Вы не должны использовать этот флаг с объектом, определенным с флагом OEFLAG_MOVEMENT (т. е. с объектом, у которого есть перемещение). Будучи удаленной из списка вызовов, подпрограмма HandleRunObject может быть вставлена туда повторно (например, действием, которое модифицирует объект) с использованием последовательности:

callRunTimeFunction(rdPtr, RFUNCTION_REHANDLE, 0, 0);

HandleRunObject не должна ничего рисовать на экране. Чтобы записать что-либо в экран, Вы должны использовать подпрограмму DisplayRunObject. Используйте HandleRunObject, чтобы показать для CF, что подпрограмма Display должна быть вызвана с использованием флага REFLAG_DISPLAY. Если Вы не используете этот флаг, и если объект не перемещается, то подпрограмма отображения никогда не будет вызвана. Вы можете захотеть использовать эту возможность для объектов, которые ничего не отображают, наподобие объекта INI. Другой способ для принудительной перерисовки из подпрограммы действия, это вызов:

callRunTimeFunction(rdPtr, RFUNCTION_REDRAW, 0, 0);

short WINAPI DLLExport KillBackground ( LPRDATA rdPtr )

Подпрограмма KillBackground уничтожает буфер памяти, используемый для сохранения области экрана, находящейся за объектом.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.

Возвращаемое значение: должен быть возвращен 0.

Замечания: эта подпрограмма должна вызываться только если установлены флаги OEFLAG_BACKSAVE и OEFLAG_INTERNALBACKSAVE. Эта подпрограмма должна проверять, что область памяти действительно была зарезервирована, и только в этом случае область памяти должна быть уничтожена.

BOOL WINAPI DLLExport LoadRunObject(LPRDATA rdPtr, HANDLE hf)

Подпрограмма LoadRunObject вызывается системой CF из действия Load Frame Position или Load Application Position ("загрузить позицию фрейма" или "загрузить позицию приложения"). Загружаемые данные сохранены в SaveRunObject, чтобы восстановить состояние объекта.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.
HANDLE hf хендл файла.

Возвращаемое значение: возвратит TRUE, если функция успешно загрузила данные, или FALSE, если произошла ошибка.

Ниже показан пример простых подпрограмм загрузки и сохранения (Load & Save routines):

// -----------------

// SaveRunObject

// -----------------

// Сохраняет объект на диск

//

// Это номер версии, он должен быть изменен, если содержимое структуры поменялось:

#define SAVEVERSION_CURRENT 1

// Структура для сохранения на диск:

typedef struct tagSaveCB
{
   DWORD dwVersion;
   DWORD dwFlags;
}SaveCB;

BOOL WINAPI SaveRunObject(LPRDATA rdPtr, HANDLE hf)

{
   BOOL bOK = FALSE;

#ifndef VITALIZE
   SaveCB save;
   DWORD written;
   while(TRUE)
   {
      save.dwVersion = SAVEVERSION_CURRENT;
      save.dwFlags = rdPtr->dwFlags;
      if ( WriteFile(hf, &save, sizeof(SaveCB), &written, NULL) == 0 )
         break;
      bOK = TRUE;
      break;
   }

#endif // VITALIZE

   return bOK;
}

// -----------------

// LoadRunObject

// -----------------

// Загружает объект с диска

//
BOOL WINAPI LoadRunObject(LPRDATA rdPtr, HANDLE hf)
{
   BOOL bOK = FALSE;
   SaveCB save;
   DWORD read;

   while(TRUE)
   {
      if (ReadFile(hf,
                   &save,
                   sizeof(SaveCB),
                   &read,
                   NULL) == 0 || read < sizeof(SaveCB))
         break;
      if (save.dwVersion != SAVEVERSION_CURRENT)
         break;
      rdPtr->dwFlags = save.dwFlags;
      bOK = TRUE;
      break;
   }

   return bOK; 
}

short WINAPI DLLExport PauseRunObject(LPRDATA rdPtr)

Подпрограмма PauseRunObject временно останавливает объект, когда приложение входит в режим паузы (pause mode).

Параметры:

LPRDATA rdPtr указатель на run-time структуру.

Возвращаемое значение: должен быть возвращен 0.

Замечания: если Ваш объект выполняет задачу, основанную на таймере, или выводит какой-то звук, то Вы должны приостановить это действие в подпрограмме PauseRunObject.

Есть несколько способов войти в pause mode:

• Пользователь нажал CONTROL + P.
• Приложение было запущено кнопкой Play, и затем остановлено кнопкой PAUSE.

short WINAPI DLLExport RestoreBackground ( LPRDATA rdPtr )

Подпрограмма RestoreBackground восстанавливает экран, который был заблокирован наподобие ситуации перед отрисовкой объекта.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.

Возвращаемое значение: должен быть возвращен 0.

Замечания: эта подпрограмма вызывается только если были установлены флаги OEFLAG_BACKSAVE и OEFLAG_INTERNALBACKSAVE. Она должна проверять, что буфер памяти был зарезервирован в предыдущем цикле. Если это произошло, то сохраненная на предыдущем цикле часть экрана должна быть восстановлена.

Предупреждение: не используйте hoX и hoY для восстановления области экрана, hoX и hoY содержат новые координаты объекта. Поэтому Вы должны сохранить эти координаты (в SaveBackground), как и порцию экрана, и использовать эти сохраненные координаты, когда восстанавливаете фон.

short WINAPI DLLExport SaveBackground ( LPRDATA rdPtr )

Подпрограмма SaveBackground сохраняет область экрана объекта в буфер памяти.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.

Возвращаемое значение: должен быть сохранен 0.

Замечания: эта подпрограмм вызывается только если установлены флаги OEFLAG_BACKSAVE и OEFLAG_INTERNALBACKSAVE. Если установлены эти 2 флага, то перед любым вызовом DisplayRunObject система CF вызывает подпрограмму SaveBackground. В этой подпрограмме Вы должны зарезервировать буфер памяти достаточного размера, чтобы он мог содержать порцию экрана, покрываемую объектом, и копировать содержимое этой области в эту подпрограмму.

BOOL WINAPI DLLExport SaveRunObject(LPRDATA rdPtr, HANDLE hf)

Подпрограмм SaveRunObject вызывается системой CF из действия Save Frame Position (сохранение позиции фрейма). Сохраните данные объекта, чтобы его состояние могло быть восстановлено из действия Load Frame/Application Position.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.
HANDLE hf хендл файла.

Возвращаемое значение: TRUE, если функция успешно сохранила данные, или FALSE, если произошла ошибка.

Ниже показан простой пример подпрограмм загрузки и сохранения (Load & Save):

// -----------------

// SaveRunObject

// -----------------

// Сохраняет объект на диск

//

// Это номер версии, он должен быть изменен, если содержимое структуры поменялось:

#define SAVEVERSION_CURRENT 1

// Структура для сохранения на диск:

typedef struct tagSaveCB
{
   DWORD dwVersion;
   DWORD dwFlags;
}SaveCB;

BOOL WINAPI SaveRunObject(LPRDATA rdPtr, HANDLE hf)
{
   BOOL bOK = FALSE;

#ifndef VITALIZE
   SaveCB save;
   DWORD written;

   while(TRUE)
   {
      save.dwVersion = SAVEVERSION_CURRENT;
      save.dwFlags = rdPtr->dwFlags;
      if ( WriteFile(hf, &save, sizeof(SaveCB), &written, NULL) == 0 )
         break;
      bOK = TRUE;
      break;
   }

#endif // VITALIZE
   return bOK;
}

// -----------------

// LoadRunObject

// -----------------

// Загружает объект с диска

//
BOOL WINAPI LoadRunObject(LPRDATA rdPtr, HANDLE hf)
{
   BOOL bOK = FALSE;
   SaveCB save;
   DWORD read;

   while(TRUE)
   {
      if ( ReadFile(hf, &save, sizeof(SaveCB), &read, NULL) == 0 || read < sizeof(SaveCB))
         break;
      if ( save.dwVersion != SAVEVERSION_CURRENT )
         break;
      rdPtr->dwFlags = save.dwFlags;
      bOK = TRUE;
      break;
   }
   return bOK; 
}

void WINAPI SetRunObjectFont( LPRDATA rdPtr, LOGFONT* pLf, RECT* pRect)

Функция SetRunObjectFont вызывается, когда приложение хочет поменять шрифт объекта.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.
LOGFONT* pLf указатель на структуру LOGFONT, которая содержит описание нового шрифта.
RECT* pRect указатель на структуру RECT, содержащую новый размер объекта.

Возвращаемое значение: отсутствует.

Замечания: эта подпрограмма вызывается, только если установлен флаг OEFLAG_TEXT.

Эта подпрограмма вызывается, когда приложение хочет изменить аспект шрифта, используемого объектом. Эта функция должна использовать LOGFONT, переданный как параметр, для изменения шрифта, используемого объектом, принудительной перерисовки объекта.

Параметр pRect вызывается, когда визуальный элемент управления меняет размер, когда поменялся размер шрифта. Он может быть NULL, в таком случае не будет осуществляться изменение размера. Если он не NULL, то поля pRect->right и pRect->bottom содержат новый размер объекта. Ваш объект тогда должен поменять следующие поля в структуре headerObject: hoImgWidth, hoImgHeight, hoRect.right, hoRect.bottom, и конечно поменять размер окна, если объектом является элемент управления.

COLORREF WINAPI SetRunObjectTextColor( LPRDATA rdPtr, COLORREF rgb)

Функция GetRunObjectTextColor вызывается, когда пользователь хочет поменять цвет текста, отображаемого объектом.

Параметры:

LPRDATA rdPtr указатель на run-time структуру.
COLORREF rgb новый цвет для использования.

Возвращаемое значение: отсутствует.

Замечания: эта подпрограмма вызывается только если установлен флаг OEFLAG_TEXT.

Просто поменяйте цвет Вашего текста в соответствии со значением rgb.

void WINAPI DLLExport StartApp(mv *mV, CRunApp* pApp)

Функция StartApp вызывается только один раз для каждого расширения, когда приложение запускается и перезапускается.

Параметры:

mv* mV указатель на информационную структуру mv.
CRunApp* pApp приложение, которое запускается или перезапускается.

Возвращаемое значение: отсутствует.

Замечания: если Ваш объект использует глобальные данные, сохраненные в пользовательских данных расширения в приложении, то Вы должны здесь инициализировать их или освободить. Пример:

    CMyData* pData = (CMyData*)mV->mvGetExtUserData(pApp, hInstLib);
    if ( pData != NULL )
    {
        delete pData;
        mV->mvSetExtUserData(pApp, hInstLib, NULL);
    }

Здесь hInstLib это HINSTANCE расширения.

void WINAPI DLLExport StartFrame(mv *mV, CRunApp* pApp, int nFrame)

Эта функция вызывается только 1 раз для каждого расширения, когда фрейм запускается или перезапускается.

Параметры:

mv *mV указатель на информационную структуру mv.
CRunApp* pApp текущее приложение.
int nFrame индекс фрейма, который запускается или перезапускается.

Возвращаемое значение: отсутствует.

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

LRESULT CALLBACK DLLExport WindowProc(LPRH rhPtr, HWND hWnd, UINT msgType,
                                      WPARAM wParam, LPARAM lParam)

Когда флаг OEFLAG_WINDOWPROC установлен, и код runtime получает сообщение для основного окна или дочернего окна, система CF вызывает подпрограмму WindowProc перед вызовом оконной процедуры основного или дочернего окна.

Параметры:

LPRH rhPtr указатель главную run-time структуру RunHeader системы CF.
HWND hWnd хендл окна, может быть либо поле rhHMainWin структуры rhPtr (основное окно), или rhHEditWin (дочернее окно).
UINT msgType параметр по умолчанию Microsoft для процедуры окна.
WPARAM wParam параметр по умолчанию Microsoft для процедуры окна.
LPARAM lParam параметр по умолчанию Microsoft для процедуры окна.

Возвращаемое значение: если 0, то сообщение не было обработано, и должно быть передано оконной процедуре фрейма. Другие значения:

REFLAG_MSGHANDLED сообщение немедленно остановлено, и в Windows возвращено 0L.
REFLAG_MSGCATCHED сообщение не отправляется на любой объект расширения, однако все еще обрабатывается оконной процедурой фрейма.
REFLAG_MSGRETURNVALUE подпрограмма WindowProc сохраняет данные DWORD в поле rhPtr->rh4.rh4KpxReturn. Система CF возвращает это значение в Windows, с возвратом rhPtr->rh4.rh4KpxReturn.
REFLAG_MSGDEFPROC система CF вызывает по умолчанию оконную процедуру обработки (например, это игнорирует оконную процедуру CF и вызывает процедуру Windows по умолчанию).

Замечания: подпрограмма WindowProc вызывается, только когда установлен флаг OEFLAG_WINDOWPROC. Если Вы открываете окно управления как дочерний объект окна фрейма, и хотите обработать оповещающие сообщения в процедуре WindowProc, мы советуем установить хук (см. "How to control a window from an extension"), чтобы Вы могли проще восстановить адрес структуры RUNDATA, контролирующей это окно из хендла.

Эта функция должна проверить статус паузы и не должна отвечать на каждое сообщение, если приложение поставлено на паузу:

// Если пауза, то выход:

if (rhPtr->rh2.rh2PauseCompteur != 0)
    return 0;

Например, в режиме паузы расширение должно отвечать на сообщения палитры, если это необходимо, но не на сообщения WM_COMMAND или CLICK.

Примеры: Вы найдете много примеров подпрограммы WindowProc в исходных кодах EDIT и StaticText этого extension kit.

BOOL (CALLBACK * mvEditAnimation) (LPVOID edPtr, LPEDITANIMATIONPARAMS pParams,
                                   HWND hParent)

Эта функция откроет редактор изображения (CF picture editor), чтобы редактировать список изображений, содержащихся в банке картинок приложения.

Параметры:

LPVOID edPtr указатель на структуру EDITDATA.
HWND hParent хендл на родительское окно.
LPEDITANIMATIONPARAMS pParams указатель на следующую структуру:

typedef struct EditAnimationParams
{
   DWORD    m_dwSize;         // sizeof(EditImageParams)
   LPTSTR   m_pWindowTitle;   // заголовок Picture Editor (NULL заголовок по умолчанию)
   int      m_nImages;        // количество изображений в списке
   int      m_nMaxImages;     // максимальное количество изображений в списке
   int      m_nStartIndex;    // индекс первого изображения для изменения в редакторе
   LPWORD   m_pImages;        // список изображений (по одному слову WORD на изображение)
   LPTSTR*  m_pImageTitles;   // заголовки к изображениям (может быть NULL)
   DWORD    m_dwOptions;      // опции, см. PictEdDefs.h
   DWORD    m_dwFixedWidth;   // ширина по умолчанию или фиксированная ширина
                              // (если используется PICTEDOPT_FIXEDIMGSIZE)
   DWORD    m_dwFixedHeight;  // высота по умолчанию или фиксированная высота
                              // (если используется PICTEDOPT_FIXEDIMGSIZE)
} EditAnimationParams;

m_dwOptions могут быть одной или большим количеством одновременно указанных опций:

PICTEDOPT_FIXEDIMGSIZE        // пользователь не может поменять размер изображения
PICTEDOPT_HOTSPOT             // пользователь может редактировать горячую точку (hot spot)
PICTEDOPT_ACTIONPOINT         // пользователь может редактировать точку действия (action point)
PICTEDOPT_16COLORS            // 16-цветное изображения, палитра Windows
PICTEDOPT_FIXEDNFRAMES        // пользователь не может добавлять / удалять фреймы
PICTEDOPT_NOTRANSPARENCY      // нет цвета прозрачности
PICTEDOPT_NOALPHACHANNEL      // нет канала альфа
PICTEDOPT_CANBETRANSPARENT    // анимация может быть пуста (только прозрачные изображения).
                              // Если эта опция не указана, то CF отклоняет закрытие picture
                              // editor, если анимация пуста.

Возвращаемое значение: TRUE, если список изображений был изменен, иначе FALSE. Если список изображений изменен, то m_pImages содержит новые идентификаторы изображений и m_nImages содержит новое количество изображений.

Замечания: если Ваша структура EDITDATA содержит изображения, то Вы должны реализовать функцию EnumElts. Пожалуйста обратитесь к главе "Библиотека MMFS2" в этой документации для получения дополнительной информации про изображения.

Пример:

LPTSTR imageTitles[] =
{
    _T("Normal"),
    _T("Disabled")
    NULL
};

EditAnimationParams eip;

eip.m_dwSize = sizeof(EditAnimationParams);
eip.m_pWindowTitle = NULL;
eip.m_nImages = 2;
eip.m_nMaxImages = 2;
eip.m_nStartIndex = 0;
eip.m_pImages = &edPtr->wImage[0];
eip.m_pImageTitles = imageTitles;
eip.m_dwImage = edPtr->wImage;
eip.m_dwOptions = PICTEDOPT_FIXEDNFRAMES | PICTEDOPT_FIXEDIMGSIZE;
eip.m_dwFixedWidth = 24;
eip.m_dwFixedHeight = 20;if ( mV->mvEditImage(edPtr, &eip, mV->mvHEditWin) )
{
   ;
}

BOOL (CALLBACK * mvEditImage) (LPVOID edPtr, LPEDITIMAGEPARAMS pParams,
                               HWND hParent)

Эта функция открывает редактор изображений (CF picture editor) для редактирования картинки, содержащейся в банке изображений приложения.

Параметры:

LPVOID edPtr указатель на структуру EDITDATA.
HWND hParent хендл на родительское окно.
LPEDITIMAGEPARAMS pParams указатель на следующую структуру:

typedef struct EditImageParams
{
   DWORD    m_dwSize;         // sizeof(EditImageParams)
   LPTSTR   m_pWindowTitle;   // заголовок Picture Editor (NULL заголовок по умолчанию)
   DWORD    m_dwImage;        // картинка для редактирования. Замечание: в этой версии
                              // используется только LOWORD (младшее слово).
   DWORD    m_dwOptions;      // опции, см. PictEdDefs.h
   DWORD    m_dwFixedWidth;   // ширина по умолчанию или фиксированная ширина
                              // (если используется PICTEDOPT_FIXEDIMGSIZE)
   DWORD    m_dwFixedHeight;  // высота по умолчанию или фиксированная высота
                              // (если используется PICTEDOPT_FIXEDIMGSIZE)
} EditImageParams;

m_dwOptions могут быть одной или большим количеством одновременно указанных опций:

PICTEDOPT_FIXEDIMGSIZE        // пользователь не может поменять размер изображения
PICTEDOPT_HOTSPOT             // у изображения есть горячая точка (hot spot)
PICTEDOPT_ACTIONPOINT         // у изображения есть точка действия (action point)
PICTEDOPT_16COLORS            // 16-цветное изображения, палитра Windows
PICTEDOPT_NOTRANSPARENCY      // нет цвета прозрачности
PICTEDOPT_NOALPHACHANNEL      // нет канала альфа
PICTEDOPT_CANBETRANSPARENT    // анимация может быть пуста. Если эта опция не указана,
                              // то CF отклоняет закрытие picture editor,
                              // если анимация пуста.

Возвращаемое значение: TRUE, если изображение было изменено, иначе FALSE. Если изображение было изменено, то m_dwImage содержит новый идентификатор изображения.

Замечания: если Ваша структура EDITDATA содержит картинки, то Вы должны реализовать функцию EnumElts.

Чтобы добавить картинку в банк изображений (CF image bank), Вы можете использовать функции DibToImage и DibToImageEx. Пожалуйста обратитесь к главе "Библиотека MMFS2" в этой документации для получения дополнительной информации по поводу картинок.

Пример:

EditImageParams eip;

eip.m_dwSize = sizeof(EditImageParams);
eip.m_pWindowTitle = NULL;
eip.m_dwImage = edPtr->wImage;
eip.m_dwOptions = 0;
eip.m_dwFixedWidth = 100;
eip.m_dwFixedHeight = 100;if ( mV->mvEditImage(edPtr, &eip, mV->mvHEditWin) )
{
   edPtr->wImage = LOWORD(eip.m_dwImage);
}

BOOL (CALLBACK * mvEditSurface) (LPVOID edPtr, LPEDITSURFACEPARAMS pParams,
                                 HWND hParent)

Эта функция открывает редактор изображений (CF picture editor) для редактирования поверхности (surface).

Параметры:

LPVOID edPtr указатель на структуру EDITDATA.
HWND hParent хендл на родительское окно.
LPEDITSURFACEPARAMS pParams указатель на следующую структуру:

typedef struct EditSurfaceParams
{
   DWORD       m_dwSize;         // sizeof(EditImageParams)
   LPTSTR      m_pWindowTitle;   // заголовок Picture Editor (NULL заголовок по умолчанию)
   cSurface*   m_pSf;            // поверхность для редактирования
   DWORD       m_dwOptions;      // опции, см. PictEdDefs.h
   DWORD       m_dwFixedWidth;   // ширина по умолчанию или фиксированная ширина
                                 // (если используется PICTEDOPT_FIXEDIMGSIZE)
   DWORD       m_dwFixedHeight;  // высота по умолчанию или фиксированная высота
                                 // (если используется PICTEDOPT_FIXEDIMGSIZE)
   POINT       m_hotSpot;        // координаты горячей точки
   POINT       m_actionPoint;    // координаты точки действия
} EditSurfaceParams;

m_dwOptions могут быть одной или большим количеством одновременно указанных опций:

PICTEDOPT_FIXEDIMGSIZE        // пользователь не может поменять размер изображения
PICTEDOPT_HOTSPOT             // у изображения есть горячая точка (hot spot)
PICTEDOPT_ACTIONPOINT         // у изображения есть точка действия (action point)
PICTEDOPT_16COLORS            // 16-цветная поверхность, палитра Windows
                              // (фактически 256-цветная поверхность с 16x16
                              // цветовой палитрой)
PICTEDOPT_NOTRANSPARENCY      // нет цвета прозрачности
PICTEDOPT_NOALPHACHANNEL      // нет канала альфа
PICTEDOPT_CANBETRANSPARENT    // поверхность может быть пуста (иначе CF будет отклонять
                              // закрытие picture editor)

Возвращаемое значение: TRUE, если изображение было изменено, иначе FALSE. Указатель m_pSf не поменяется (если функция возвратит TRUE, то только содержимое поверхности было изменено).

Пример:

EditSurfaceParams eip;

eip.m_dwSize = sizeof(EditSurfaceParams);
eip.m_pWindowTitle = NULL;
eip.m_pSf = pSf;
eip.m_dwOptions = 0;
eip.m_dwFixedWidth = 100;
eip.m_dwFixedHeight = 100;
eip.m_hotSpot.x = 0;
eip.m_hotspot.y = 0;
eip.m_actionPoint.x = 0;
eip.m_actionPoint.y = 0;if ( mV->mvEditSurface(edPtr, &eip, mV->mvHEditWin) )
{
   ;
}

BOOL (CALLBACK * mvGetDefaultFont) (LPLOGFONT pLogFont, LPTSTR pStyle, int size)

Эта функция возвращает информацию о шрифте по умолчанию, используемому в редакторе фрейма (frame editor).

Параметры:

LPLOGFONT pLogFont указатель на структуру LOGFONT, где будет скопирована информация.
LPTSTR pStyle больше не используется.
int size больше не используется.

Возвращаемое значение: эта функция вернет TRUE, если информация достоверна, иначе FALSE.

Замечание: эта функция должна использоваться для инициализации Вашего объекта в функции CreateObject, если Ваш объект содержит текст.

DWORD (CALLBACK * mvGetVersion) ()

Эта функция возвращает текущую версию системы CF.

Возвращаемое значение: DWORD, содержащее номер версии CF.

Пример:

DWORD dwVersion = mV->mvGetVersion();

if ( (dwVersion & MMFVERSION_MASK) == MMFVERSION_25 )
    ; // CF 2.5

if ( (dwVersion & MMFVERSION_PRO) != 0 )
    ; // CF 2.5 Developer

int nBuildNumber = (dwVersion & MMFBUILD_MASK);

void ( CALLBACK * mvHelp) (LPCTSTR hlpFileName, UINT contextId, LPARAM lParam);

Используйте эту функцию для открытия Вашего файла подсказки, например из диалога настройки (setup dialog box) Вашего объекта.

Параметры:

LPCTSTR hlpFileName имя фала подсказки расширения (extension help file).
UINT contextId идентификатор контекста подсказки.
LPARAM lParam обычно идентификатор или url странички подсказки.

Возвращаемое значение: отсутствует.

Замечание: если на Ваш help-файл ссылаются в основном файле справки CF, просто передайте заголовок файла в эту функцию. Пример:

mV->mvHelp("MyExt.chm", HH_DISPLAY_TOPIC, (LPARAM)"index.html");

Иначе передайте путь до help-файла относительно директории CF. Пример:

mV->mvHelp("Help\\MyExt.chm", HH_DISPLAY_TOPIC, (LPARAM)"index.html");

LRESULT (CALLBACK * mvCallFunction) (LPVOID edPtr, int nFnc,
                                     LPARAM lParam1=0, LPARAM lParam2=0,
                                     LPARAM lParam3=0)

Эта функция фактически набор подпрограмм. Вы можете вызывать эти подпрограммы передачей в подпрограмму mvCallFunction индекса нужной подпрограммы (nFnc) и её параметры (lParam1, и т. д.).

Для упрощения этой задачи и для того, чтобы сделать исходный код понятнее, разработчики CF определили по одному макросу на функцию.

Параметры:

LPVOID edPtr указатель на структуру EDITDATA объекта.
int nFnc индекс функции для вызова (определение EF_).
LPARAM lParam1=0 первый параметр.
LPARAM lParam2=0 второй параметр.
LPARAM lParam3=0 третий параметр.

Индексы функций:

   // Только редактор
   EF_INSERTPROPS,         // Вставка свойств в окно Property
   EF_REMOVEPROP,          // Удаление свойства
   EF_REMOVEPROPS,         // Удаление свойств
   EF_REFRESHPROP,         // Обновление свойства
   EF_REALLOCEDITDATA,     // Переразмещение edPtr
   EF_GETPROPVALUE,        // Получение значения свойства объекта
   EF_GETAPPPROPVALUE,     // Получение значения свойства приложения
   EF_GETFRAMEPROPVALUE,   // Получение значения свойства фрейма
   EF_SETPROPVALUE,        // Установка значения свойства объекта
   EF_SETAPPPROPVALUE,     // Установка значения свойства приложения
   EF_SETFRAMEPROPVALUE,   // Установка значения свойства фрейма
   EF_GETPROPCHECK,        // Получение состояния галочки свойства объекта
   EF_GETAPPPROPCHECK,     // Получение состояния галочки свойства приложения
   EF_GETFRAMEPROPCHECK,   // Получение состояния галочки свойства фрейма
   EF_SETPROPCHECK,        // Установка значения свойства галочки объекта
   EF_SETAPPPROPCHECK,     // Установка значения свойства галочки приложения
   EF_SETFRAMEPROPCHECK,   // Установка значения свойства галочки фрейма
   EF_INVALIDATEOBJECT,    // Обновление объекта в редакторе фрейма
   EF_RECALCLAYOUT,        // Перерасчет размещения окон во время работы программы
                           // (recalc runtime layout, докинг) 

   // Редактор и runtime
   EF_MALLOC,              // Выделение памяти
   EF_CALLOC,              // Выделение памяти и установка её в 0
   EF_REALLOC,             // Перераспределение памяти
   EF_FREE,                // Освобождение памяти

Макросы:

   // Только редактор
   mvInsertProps
   mvRemoveProp
   mvRemoveProps
   mvRefreshProp
   mvReAllocEditData
   mvGetPropValue
   mvGetAppPropValue
   mvGetFramePropValue
   mvSetPropValue
   mvSetAppPropValue
   mvSetFramePropValue
   mvGetPropCheck
   mvGetAppPropCheck
   mvGetFramePropCheck
   mvSetPropCheck
   mvSetAppPropCheck
   mvSetFramePropCheck
   mvInvalidateObject

   // Редактор и runtime
   mvMalloc
   mvCalloc
   mvReAlloc
   mvFree

Как использовать. Вы можете вызвать нужную функцию вот так:

mV->mvCallFunction(edPtr, EF_REFRESHPROP, PROPID_MYPROP, FALSE, 0);

или так (mv это указатель на структуру mv):

mvRefreshProp(mV, edPtr, PROPID_MYPROP, FALSE);

LPVOID mvCalloc(LPMV mV, int nSize)

Выделяет буфер в памяти и устанавливает его содержимое в 0.

Параметры:

LPMV mV указатель на информационную структуру mv.
int nSize размер блока памяти для выделения и очистки.

Возвращаемое значение: указатель на выделенный буфер, NULL если произошла ошибка.

Замечание: используйте эту подпрограмму, если нужно выделить буфер в памяти, который будет освобожден впоследствии системой CF runtime, например если Вы должны заново выделить буфер, выделенный системой CF, и сохраненный в одной из runtime-структур CF. Используйте обычную функцию calloc для других своих выделений памяти.

void mvFree(LPMV mV, LPVOID ptr)

Освобождает буфер памяти, выделенный mvMalloc, mvCalloc или mvReAlloc.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID ptr указатель на освобождаемый буфер в памяти.

Возвращаемое значение: отсутствует.

Замечание: используйте эту подпрограмму, если Вам нужно освободить буфер в памяти, выделенный системой CF runtime или через mvMalloc, mvCalloc или mvReAlloc. Используйте обычную функцию free для других своих выделений памяти.

mvGetAppPropCheck(LPMV mV, LPVOID edPtr, UINT nPropID)

Вернет состояние галочки (checked state) свойства приложения, TRUE или FALSE.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

Возвращаемое значение: TRUE или FALSE, в зависимости от того, стоит ли галочка на свойстве или нет.

Замечание: идентификаторы свойств приложения перечислены в Props.h. Например, если Вы хотите узнать, установлена ли опция "Hidden at start" приложения, выполните следующее:

mvGetAppPropCheck(mV, edPtr, PROPID_APP_HIDDENATSTART);

mvGetAppPropValue(LPMV mV, LPVOID edPtr, UINT nPropID)

Вернет значение свойства приложения.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

Возвращаемое значение: указатель на класс CPropValue, где содержится значение свойства.

Замечание: идентификаторы свойств приложения перечислены в Props.h. Например, если Вы хотите узнать размер окна приложения, выполните следующее:

CPropSizeValue* psv = (CPropSizeValue*)mvGetAppPropValue(mV,
                                                         edPtr,
                                                         PROPID_APP_WINDOWSIZE);

int nWidth = psv->m_cx;

int nHeight = psv->m_cy;

mvGetFramePropCheck(LPMV mV, LPVOID edPtr, UINT nPropID)

Вернет состояние галочки (checked state) свойства фрейма, TRUE или FALSE.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

Возвращаемое значение: TRUE или FALSE, в зависимости от того, стоит ли галочка на свойстве или нет.

Замечание: идентификаторы свойств фрейма перечислены в Props.h. Например, если Вы хотите узнать состояние галочки опции фрейма "Handle collisions out of window", то выполните следующее:

mvGetFramePropCheck(mV, edPtr, PROPID_FRAME_TOTALCOLMASK);

mvGetFramePropValue(LPMV mV, LPVOID edPtr, UINT nPropID)

Вернет значение свойства фрейма, который содержит этот объект.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

Возвращаемое значение: указатель на класс CPropValue, где содержится значение свойства.

Замечание: идентификаторы свойств фрейма содержатся в Props.h. Например, если Вы хотите узнать цвет фона фрейма, выполните следующее:

CPropDWordValue* pv = (CPropDWordValue*)mvGetFramePropValue(mV,
                                                            edPtr,
                                                            PROPID_FRAME_BACKGROUNDCOLOR);
COLORREF color = pv->m_dwValue;

mvGetPropCheck(LPMV mV, LPVOID edPtr, UINT nPropID)

Вернет состояние галочки (checked state) свойства объекта, TRUE или FALSE.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

Возвращаемое значение: TRUE или FALSE, в зависимости от того, стоит ли галочка на свойстве или нет.

Замечание: идентификаторы свойств перечислены в Props.h. Например, если хотите узнать состояние галочки опции "Create before fade-in transition", то выполните следующее:

mvGetPropCheck(mV, edPtr, PROPID_DYNITEM_CREATEBEFOREFADEIN);

mvGetPropValue(LPMV mV, LPVOID edPtr, UINT nPropID)

Вернет значение свойства объекта.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

Возвращаемое значение: указатель на класс CPropValue, где содержится значение свойства.

Замечание: идентификаторы свойств перечислены в файле Props.h. Например, если хотите узнать имя объекта, то выполните следующее:

CPropDataValue* pv = (CPropDataValue*)mvGetPropValue(mV, edPtr, PROPID_ITEM_NAME);
LPSTR pName = (LPSTR)pv->m_pData;

mvInsertProps(LPMV mV, LPVOID edPtr, PropData* pProperties,
              UINT nInsertPropID, BOOL bAfter)

Вставляет список свойств в главные свойства объекта.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
CPropData* pProperties указатель на массив PropData, содержащий определения свойств.
UINT nInsertPropID позиция вставки.
BOOL bAfter см. описание ниже.

Если nInsertPropID это идентификатор закладки: если bAfter == TRUE, то свойства добавляются в конец закладки, иначе они добавляются в начало. Если nInsertPropID обычный идентификатор: если bAfter == TRUE, то элемент будет вставлен после nInsertPropID, иначе перед nInsertPropID.

Возвращаемое значение: отсутствует.

Замечания: эта функция обычно вызывается в функции GetProperties объекта, но может быть также вызвана позже, если Вы хотите динамически менять содержимое окна свойств. Например, свойства перемещения (movement) изменяются, когда Вы меняете тип перемещения.

Пример:

PropData Properties[] =
{
   PropData_PictureFilename(PROPID_FILENAME, IDS_PROP_FILENAME,
                            IDS_PROP_FILENAME_INFO, FALSE),
   PropData_ComboBox(PROPID_RESIZE, IDS_PROP_RESIZE,
                     IDS_PROP_RESIZE_INFO, ResizeList),
   PropData_End()
};

PropData TranspProps[] =
{
   PropData_Group(PROPID_TRANSPCOLORGROUP,
                  IDS_PROP_TRANSPCOLORGROUP,
                  IDS_PROP_TRANSPCOLORGROUP_INFO),
   PropData_CheckBox(PROPID_TRANSPFIRSTPIXEL,
                    IDS_PROP_TRANSPFIRSTPIXEL,
                    IDS_PROP_TRANSPFIRSTPIXEL_INFO),
   PropData_Color_Check(PROPID_TRANSPCOLORCUSTOM,
                       IDS_PROP_TRANSPCOLORCUSTOM,
                       IDS_PROP_TRANSPCOLORCUSTOM_INFO),
   PropData_End()
};

BOOL WINAPI GetProperties(LPMV mV, LPEDATA edPtr, BOOL bMasterItem)
{
   mvInsertProps(mV, edPtr, Properties, PROPID_TAB_GENERAL, TRUE);
   mvInsertProps(mV, edPtr, TranspProps, PROPID_TAB_DISPLAY, TRUE);
   return TRUE;
}

mvInvalidateObject(LPMV mV, LPVOID edPtr)

Принуждает к перерисовке объект в редакторе фрейма и обновляет его иконку.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.

Возвращаемое значение: отсутствует.

Замечание: обычно Вы вызываете эту функцию, когда меняете свойство, влияющее на отображение объекта в редакторе фрейма.

LPVOID mvMalloc(LPMV mV, int nSize)

Выделяет буфер памяти.

Параметры:

LPMV mV указатель на информационную структуру mv.
int nSize размер блока памяти для выделения.

Возвращаемое значение: указатель на выделенный буфер, иначе NULL, если произошла ошибка.

Замечание: используйте эту подпрограмму, если Вам нужно выделить буфер в памяти, который будет освобожден системой CF runtime, например если Вы должны перераспределить буфер, выделенный системой CF, и сохраненный в одной из runtime структур CF. Используйте обычную функцию malloc для своих других выделений в памяти.

LPVOID mvReAlloc(LPMV mV, LPVOID ptr, int nNewSize)

Меняет размер буфера памяти, ранее выделенного mvMalloc, mvCalloc или mvReAlloc.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID ptr указатель на переразмещаемый буфер.
int nSize размер буфера для повторного выделения.

Возвращаемое значение: указатель на новый буфер. Если произошла ошибка, то эта функция вернет NULL, и оригинальный буфер не будет изменен. Работает наподобие стандартной библиотечной функции realloc языка C.

Замечание: используйте эту подпрограмму, если Вам нужно выделить буфер в памяти, который будет освобожден системой CF runtime, например если Вы должны перераспределить буфер, выделенный системой CF, и сохраненный в одной из runtime структур CF. Используйте обычную функцию realloc для своих других повторных выделений в памяти.

LPVOID mvReAllocEditData(LPMV mV, LPVOID edPtr, DWORD dwNewSize)

Заново размещает в памяти структуру EDITDATA.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA для повторного размещения в памяти.
DWORD dwNewSize новый размер для выделения.

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

Замечания: если размер Вашей структуры EDITDATA зависит от одного или большего количества свойств (к примеру, строк, которые могут менять размер), то Вы должны иметь возможность поменять размер структуры, когда модифицируется свойство. Для этой цели просто вызовите функцию mvReAllocEditData.

mvRefreshProp(LPMV mV, LPVOID edPtr, UINT nPropID, BOOL bReInit)

Обновляет отображение свойства.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.
BOOL bReInit TRUE, если содержимое свойства нуждается в повторной инициации, иначе FALSE. Имейте в виду, что если if bReInit == TRUE, и параметр property равен NULL в таблице PropData, то GetPropCreateParam вызывается для получения нового параметра инициализации.

Возвращаемое значение: отсутствует.

Замечания: иногда изменение значения свойства влияет на другие свойства. Вам нужен способ побудить повторное отображения других свойств с их новым значением. Как раз для этого и нужна функция mvRefreshProp. Вы обычно используете её в функциях SetPropValue или SetPropCheck своего объекта.

mvRemoveProp(LPMV mV, LPVOID edPtr, UINT nPropID)

Удаляет одно свойство из отображаемого списка.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.

Возвращаемое значение: отсутствует.

Замечание: вызовите эту функцию, когда хотите удалить свойство из списка. Это позволит Вам изменять отображение свойств в зависимости от ввода пользователя. Вы можете сделать это либо в GetProperties, например когда инициализируется свойство окна, или позже в функциях SetPropValue или SetPropCheck.

mvRemoveProps(LPMV mV, LPVOID edPtr, PropData* pProperties)

Удаляет список свойств из отображения.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
PropData* pProperties указатель на массив PropData, содержащий свойства для удаления.

Возвращаемое значение: отсутствует.

Замечания: используйте эту функцию для удаления набора свойств за один вызов, чтобы сделать список свойств подстраиваемым под ввод пользователя.

mvSetAppPropCheck(LPMV mV, LPVOID edPtr, UINT nPropID, UINT nCheck)

Меняет статус (TRUE или FALSE) свойства галочки текущего приложения.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.
UINT nCheck TRUE (галочка стоит, checked) или FALSE (галочка снята, unchecked).

Возвращаемое значение: отсутствует.

Замечания: идентификаторы свойств приложения перечислены в Props.h. Например если хотите установить значение галочки опции "Hidden at start" в свойствах приложения, выполните следующее:

mvSetAppPropCheck(mV, edPtr, PROPID_APP_HIDDENATSTART, TRUE);

Внимание: изменение свойств приложения не рекомендуется. Вы должны предупредить пользователя, перед тем, как сделать это.

mvSetAppPropValue(LPMV mV, LPVOID edPtr, UINT nPropID, CPropValue* pValue)

Меняет значение одного их свойств приложения.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
INT nPropID идентификатор свойства.
CPropValue* pValue указатель на (производный) класс CPropValue, содержащий новое значение.

Возвращаемое значение: отсутствует.

Замечания: идентификаторы свойств приложения перечислены в Props.h. Например, если хотите поменять частоту смены фреймов (frame rate), то выполните следующее:

CPropDWordValue* pv = new CPropDWordValue(dwNewFrameRate);
mvSetAppPropValue(mV, edPtr, PROPID_APP_FRAMERATE, pv);
pv->Delete();

Примечание: изменение свойств приложения не рекомендуется. Вы должны предупредить пользователя, перед тем, как сделать это.

mvSetFramePropCheck(LPMV mV, LPVOID edPtr, UINT nPropID, UINT nCheck)

Меняет статус (TRUE или FALSE) свойства галочки текущего фрейма.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.
UINT nCheck TRUE (галочка стоит, checked) или FALSE (галочка снята, unchecked).

Возвращаемое значение: отсутствует.

Замечания: идентификаторы свойств фрейма перечислены в Props.h. Например, если Вы хотите установить опцию "Resize to screen size at start" в свойствах фрейма, выполните следующее:

mvSetFramePropCheck(mV, edPtr, PROPID_FRAME_RESIZETOSCREENSIZE, TRUE);

Примечание: изменение свойств фрейма не рекомендуется. Вы должны предупредить пользователя, перед тем как сделать это.

mvSetFramePropValue(LPMV mV, LPVOID edPtr, UINT nPropID, CPropValue* pValue)

Изменение значения одно из свойств текущего фрейма.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.
CPropValue* pValue указатель на (производный) класс CPropValue, содержащий новое значение.

Возвращаемое значение: отсутствует.

Замечания: идентификаторы свойств фрейма перечислены в Props.h. Например, если хотите поменять цвет фона фрейма, выполните следующее:

CPropDWordValue* pv = new CPropDWordValue(BLUE);
mvSetFramePropValue(mV, edPtr, PROPID_FRAME_BACKGROUNDCOLOR, pv);
pv->Delete();

Примечание: изменение свойств фрейма не рекомендуется. Вы должны предупредить пользователя, перед тем как сделать это.

mvSetPropCheck(LPMV mV, LPVOID edPtr, UINT nPropID, UINT nCheck)

Меняет статус (TRUE или FALSE) свойства галочки объекта.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.
UINT nCheck TRUE (галочка стоит, checked) или FALSE (галочка снята, unchecked).

Возвращаемое значение: отсутствует.

Замечания: идентификаторы свойств перечислены в Props.h. Например, если хотите установить опцию "Create before fade-in transition" в свойствах объекта, выполните следующее:

mvSetPropCheck(mV, edPtr, PROPID_DYNITEM_CREATEBEFOREFADEIN, TRUE);

После этого Вы должны принудительно обновить отображение свойств:

mvRefreshProp(mV, edPtr, PROPID_DYNITEM_CREATEBEFOREFADEIN);

mvSetPropValue(LPMV mV, LPVOID edPtr, UINT nPropID, CPropValue* pValue)

Меняет значение одного из свойств объекта.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID edPtr указатель на структуру EDITDATA объекта.
UINT nPropID идентификатор свойства.
CPropValue* pValue указатель на (производный) класс CPropValue, содержащий новое значение.

Возвращаемое значение: отсутствует.

Замечания: идентификаторы свойств перечислены в Props.h. Например, если хотите удалить эффект чернил (ink effect) в свойствах объекта, выполните следующее:

CPropDWordValue* pv = new CPropDWordValue(0);
mvSetPropValue(mV, edPtr, PROPID_FITEM_INKFX, pv);
pv->Delete();

После этого Вы должны обновить отображение свойства:

mvRefreshProp(mV, edPtr, PROPID_FITEM_INKFX);
mvRefreshProp(mV, edPtr, PROPID_FITEM_INKFXPARAM);

void (CALLBACK * mvAddBackdrop) (cSurface* pSf, int x,
                                 int y, DWORD dwInkEffect,
                                 DWORD dwInkEffectParam, int nObstacleType,
                                 int nLayer)

Создает новый объект backdrop из поверхности (surface).

Параметры:

cSurface* pSf поверхность, которая содержит картинку для добавления как задний фон (backdrop).
int x координата X нового объекта (относительно верхнего левого угла фрейма).
int y координата Y нового объекта (относительно верхнего левого угла фрейма).
DWORD dwInkEffect ink-эффект объекта (например BOP_BLEND).
DWORD dwInkEffectParam параметр ink-эффекта.
int nObstacleType тип препятствия.
int nLayer индекс слоя.

Параметр nObstacleType может быть одним из значений:

OBSTACLE_NONE,       // добавит "дырку" в маску коллизий слоя 1 (Layer 1).
                     // Идентично OBSTACLE_TRANSPARENT для слоев > 1
OBSTACLE_SOLID,      // препятствие
OBSTACLE_PLATFORM,   // платформа
OBSTACLE_LADDER,     // лестница
OBSTACLE_TRANSPARENT // нет эффекта при коллизиях

Возвращаемое значение: отсутствует.

void (CALLBACK * mvCloseHFile)(HANDLE hf)

Закрывает файл, открытый вызовом OpenHFile.

Параметры:

HANDLE hf хендл файла, возвращенный вызовом OpenHFile.

Возвращаемое значение: отсутствует.

LPVOID (CALLBACK * mvGetExtUserData) (CRunApp* pApp, HINSTANCE hInst)

Возвращает глобальные данные расширения, подсоединенные к приложению.

Параметры:

CRunApp* pApp приложение.
HINSTANCE hInst HINSTANCE Вашего объекта расширения.

Возвращаемое значение: то, что Вы сохранили с mvSetExtUserData. NULL, если mvSetExtUserData никогда не была вызвана этим расширением для этого приложения.

Замечания: функции mvGetExtUserData и mvSetExtUserData позволяют Вам сохранить глобальные данные в приложение. Например, Вы можете сохранить данные с mvSetExtUserData в функции DestroyRunObject (вместо удаления их), и получить их вызовом mvGetExtUserData в функции CreateRunObject. Вы должны освободить в функции EndApp любые данные, сохраненные вызовом mvSetExtUserData (и также в функции StartApp для переинициализации данных, когда приложение перезапускается).

BOOL (CALLBACK * mvGetFile)(LPCTSTR pPath, LPTSTR pFilePath, DWORD dwFlags)

Эта функция распаковывает файл из файлов, встроенных в файл EXE/CCN, во временную директорию и возвращает путь до этого временного файла.

Параметры:

LPCTSTR pPath путь до файла для открытия.
LPTSTR pFilePath буфер, который будет содержать путь до файла назначения (размер буфера должен быть как минимум _MAX_PATH символов).
DWORD dwFlags флаги, может иметь значение OHFF_LOCALFILE (больше не используется).

Возвращаемое значение: TRUE если все в порядке, иначе FALSE в случае возникновения ошибки (например, если временный файл не был создан).

Замечания: если файл встроен в файл EXE или CCN, то mvGetFile распаковывает файл во временную директорию, и копирует путь до этого временного файла в буфер pFilePath. Если файл уже был распакован предыдущим вызовом этой функции, то mvGetFile не будет его распаковывать повторно, она увеличит счетчик и вернет путь до уже распакованного временного файла.

Если файл не встроен в файл EXE/CCN, если у нас отдельное приложение, то копирует pPath в pFilePath, и вернет TRUE.

Вы должны использовать эту функцию, если Ваше расширение поддерживает встроенные библиотечные файлы, но может получить доступ к ним только если это независимый файл.

Вы должны вызвать mvReleaseFile для каждого вызова mvGetFile. mvReleaseFile удаляет временный файл с диска. Примечание: временные файлы будут удалены по завершению работы приложения, если по какой-то причине Вы не хотели удалять их, когда Ваш объект больше не нуждается в этих файлах.

Пример:

short WINAPI  CreateRunObject(LPRDATA rdPtr, LPEDATA edPtr, LPCOB cobPtr)
{
   LPRH rhPtr = rdPtr->rHo.hoAdRunHeader;
   rhPtr->rh4.rh4Mv->mvGetFile(rdPtr->szFileName, rdPtr->szTempFileName, 0);
   return 0;
}

short WINAPI  DestroyRunObject(LPRDATA rdPtr, long fast)
{
   LPRH rhPtr = rdPtr->rHo.hoAdRunHeader;
   rhPtr->rh4.rh4Mv->mvReleaseFile(rdPtr->szFileName);
   return 0;
}

DWORD (CALLBACK * mvGetVersion) ()

Эта функция возвращает текущую версию CF.

Возвращаемое значение: DWORD, содержащее номер версии CF.

Пример:

DWORD dwVersion = mV->mvGetVersion();

if ( (dwVersion & MMFVERSION_MASK) == MMFVERSION_25 )
   ; // CF 2.5

if ( (dwVersion & MMFVERSION_PRO) != 0 )
   ; // CF 2.5 Developer

int nBuildNumber = (dwVersion & MMFBUILD_MASK);

HANDLE (CALLBACK * mvOpenHFile)(LPCTSTR pPath, LPDWORD pDwSize, DWORD dwFlags)

Вернет хендл файла, встроенного в файл EXE, или обычного файла, если он не встроенный. Файл открывается на доступ только для чтения.

Параметры:

LPCTSTR pPath путь до файла для открытия.
LPDWORD pDwSize указатель на значение DWORD, устанавливаемое в размер файла, при выходе из функции.
DWORD dwFlags может быть значением OHFF_LOCALFILE (больше не используется).

Возвращаемое значение: хендл файла (который был возвращен Windows-функцией CreateFile).

Замечания: если файл встроен в файл EXE или CCN, то mvOpenHFile откроет файл EXE/CCN, установит его позицию на начало встроенного файла, поместит его размер в pDwSize, и вернет хендл файла (file handle).

Если файл не встроен в файл EXE/CCN, если код работает в отдельном приложении, то mvOpenHFile пытается открыть файл вызовом Windows-функции CreateFile, поместит его размер в pDwSize, и вернет хендл файла (это может быть значение INVALID_HANDLE_VALUE, если такой файл не существует).

Хендл файла должен быть закрыт вызовом mvCloseHFile.

Пример: см. действие LoadText в старой ANSI версии объекта Edit.

short WINAPI  LoadText(LPRDATA rdPtr, long param1, long param2)
{
   DWORD dwSize;
   LPRH rhPtr = rdPtr->rHo.hoAdRunHeader;
   HANDLE hFile = rhPtr->rh4.rh4Mv->mvOpenHFile((LPCSTR)param1, &dwSize, 0);
   if (hFile != INVALID_HANDLE_VALUE)
   {
      if ( dwSize != 0 )
      {
         LPSTR pBuf = (LPSTR)calloc(dwSize+1, 1);
         if ( pBuf != NULL )
         {
            DWORD dwRead;
            ReadFile(hFile, pBuf, dwSize, &dwRead, NULL);
            if ( dwRead == dwSize )
            {
               pBuf[dwSize] = 0;
               SetWindowText(rdPtr->hWnd, pBuf);
            }
            free(pBuf);
         }
      }
      rhPtr->rh4.rh4Mv->mvCloseHFile(hFile);
   }
   return 0;
}

void (CALLBACK * mvRegisterDialogBox)(HWND hDlg)

Регистрирует немодальное окно диалога, так что система CF вызывает IsDialogMessage для этого диалогового окна.

Параметры:

HWND hDlg хендл окна диалога для регистрации.

Возвращаемое значение: отсутствует.

Замечания: если Ваше расширение открывает немодальное окно диалога во время работы приложения (runtime), оно должно регистрировать его вызовом этой функции, иначе горячие клавиши (TAB, и т. д.) не будут работать.

Окно диалога, зарегистрированное вызовом mvRegisterDialogBox, должно быть дерегистрировано вызовом mvUnregisterDialogBox перед тем, как это окно уничтожается.

void (CALLBACK * mvReleaseFile)(LPCTSTR pPath)

Освобождает файл, запрошенный вызовом mvGetFile.

Параметры:

LPCTSTR pPath путь до освобождаемого файла (обратите внимание, что это тот же самый путь, который Вы передали в качестве первого параметра в функцию GetFile).

Возвращаемое значение: отсутствует.

Замечания: если этот файл находится как встроенный в двоичные файлы приложения, то эта функция декрементирует счетчик использования файла (file usage count), и удаляет связанный временный файл, если этот счетчик стал равным 0.

Если файл не встроен в двоичные файлы приложения, то эта функция ничего не делает.

Для дополнительной информации см. описание функции mvGetFile.

Пример:

short WINAPI CreateRunObject(LPRDATA rdPtr, LPEDATA edPtr, LPCOB cobPtr)
{
   LPRH rhPtr = rdPtr->rHo.hoAdRunHeader;
   rhPtr->rh4.rh4Mv->mvGetFile(rdPtr->szFileName, rdPtr->szTempFileName, 0);
   return 0;
}

short WINAPI DestroyRunObject(LPRDATA rdPtr, long fast)
{
   LPRH rhPtr = rdPtr->rHo.hoAdRunHeader;
   rhPtr->rh4.rh4Mv->mvReleaseFile(rdPtr->szFileName);
   return 0;
}

LPVOID (CALLBACK * mvSetExtUserData) (CRunApp* pApp,
                                      HINSTANCE hInst, LPVOID pData)

Сохраняет глобальные данные для этого расширения в приложение.

Параметры:

CRunApp* pApp приложение.
HINSTANCE hInst HINSTANCE Вашего объекта расширения.
LPVOID pData данные для сохранения.

Возвращаемое значение: предыдущее значение.

Замечания: функции mvGetExtUserData и mvSetExtUserData позволяют Вам сохранять данные, глобальные для приложения. Например, Вы можете сохранить данные вызовом mvSetExtUserData в функции DestroyRunObject (вместо удаления их) и получить их значение вызовом mvGetExtUserData в функции CreateRunObject. Вы должны освободить в функции EndApp любые данные, сохраненные вызовом mvSetExtUserData (и также в функции StartApp, для повторной инициализации данных, когда приложение перезапускается).

void (CALLBACK * mvUnregisterDialogBox)(HWND hDlg)

Отменяется регистрация немодального окна диалога, которая была ранее зарегистрирована вызовом mvRegisterDialogBox.

Параметры: HWND hDlg хендл окна диалогового окна для дерегистрации.

Возвращаемое значение: отсутствует.

LRESULT (CALLBACK * mvCallFunction) (LPVOID edPtr, int nFnc,
                                     LPARAM lParam1=0, LPARAM lParam2=0,
                                     LPARAM lParam3=0)

Эта функция фактически представляет набор подпрограмм. Вы можете вызвать эти подпрограммы передачей в функцию mvCallFunction индекса подпрограммы (nFnc) и параметров для неё (lParam1, и т. д.).

Чтобы упростить Вам задачу и сделать исходный код легко читаемым, разработчики CF определили по макросу на функцию.

Параметры:

LPVOID edPtr указатель на структуру EDITDATA объекта.
int nFnc индекс функции для вызова (определение EF_).
LPARAM lParam1=0 первый параметр.
LPARAM lParam2=0 второй параметр.
LPARAM lParam3=0 третий параметр.

Индексы функций:

   // Только редактор
   EF_INSERTPROPS,         // Вставка свойств в окно Property
   EF_REMOVEPROP,          // Удаление свойства
   EF_REMOVEPROPS,         // Удаление свойств
   EF_REFRESHPROP,         // Обновление свойства
   EF_REALLOCEDITDATA,     // Переразмещение edPtr
   EF_GETPROPVALUE,        // Получение значения свойства объекта
   EF_GETAPPPROPVALUE,     // Получение значения свойства приложения
   EF_GETFRAMEPROPVALUE,   // Получение значения свойства фрейма
   EF_SETPROPVALUE,        // Установка значения свойства объекта
   EF_SETAPPPROPVALUE,     // Установка значения свойства приложения
   EF_SETFRAMEPROPVALUE,   // Установка значения свойства фрейма
   EF_GETPROPCHECK,        // Получение состояния галочки свойства объекта
   EF_GETAPPPROPCHECK,     // Получение состояния галочки свойства приложения
   EF_GETFRAMEPROPCHECK,   // Получение состояния галочки свойства фрейма
   EF_SETPROPCHECK,        // Установка значения свойства галочки объекта
   EF_SETAPPPROPCHECK,     // Установка значения свойства галочки приложения
   EF_SETFRAMEPROPCHECK,   // Установка значения свойства галочки фрейма
   EF_INVALIDATEOBJECT,    // Обновление объекта в редакторе фрейма
   EF_RECALCLAYOUT,        // Перерасчет размещения окон во время работы программы
                           // (recalc runtime layout, докинг)

   // Редактор и runtime
   EF_MALLOC,              // Выделение памяти
   EF_CALLOC,              // Выделение памяти и установка её в 0
   EF_REALLOC,             // Перераспределение памяти
   EF_FREE,                // Освобождение памяти

Макросы:

   // Только редактор
   mvInsertProps
   mvRemoveProp
   mvRemoveProps
   mvRefreshProp
   mvReAllocEditData
   mvGetPropValue
   mvGetAppPropValue
   mvGetFramePropValue
   mvSetPropValue
   mvSetAppPropValue
   mvSetFramePropValue
   mvGetPropCheck
   mvGetAppPropCheck
   mvGetFramePropCheck
   mvSetPropCheck
   mvSetAppPropCheck
   mvSetFramePropCheck
   mvInvalidateObject
   // Редактор и runtime
   mvMalloc
   mvCalloc
   mvReAlloc
   mvFree

Пример, Вы можете использовать либо вызов:

mV->mvCallFunction(edPtr, EF_REFRESHPROP, PROPID_MYPROP, FALSE, 0);

или (mV это указатель на структуру mv):

mvRefreshProp(mV, edPtr, PROPID_MYPROP, FALSE);

LPVOID mvCalloc(LPMV mV, int nSize)

Выделяет буфер памяти и устанавливает его содержимое в 0.

Параметры:

LPMV mV указатель на информационную структуру mv.
int nSize размер буфера для выделения и очистки.

Возвращаемое значение: указатель на выделенный буфер, или NULL, если произошла ошибка.

Замечание: используйте эту подпрограмму, если Вам нужно выделить буфер в памяти, который будет освобожден кодом CF runtime, например, если Вы должны переразместить буфер, выделенный системой CF, и сохраненный в одной из runtime структур CF. Используйте обычную calloc для Ваших других выделений памяти.

void mvFree(LPMV mV, LPVOID ptr)

Освобождает буфер памяти, выделенный mvMalloc, mvCalloc или mvReAlloc.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID ptr указатель на освобождаемый буфер памяти.

Возвращаемое значение: отсутствует.

Замечание: используйте эту подпрограмму, если нужно освободить буфер памяти, выделенный кодом CF runtime или вызовами mvMalloc, mvCalloc или mvReAlloc. Используйте обычную функцию free для для своих других выделений памяти.

LPVOID mvMalloc(LPMV mV, int nSize)

Выделяет буфер памяти.

Параметры:

LPMV mV указатель на информационную структуру mv.
int nSize размер для выделения.

Возвращаемое значение: указатель на выделенный буфер, или NULL, если произошла ошибка.

Замечание: используйте эту подпрограмму, если Вам нужно выделить в памяти буфер, который будет освобожден кодом CF runtime, например если Вы должны перераспределить буфер, выделенный системой CF, и сохраненный в одну из структур CF. Используйте обычную функцию malloc для своих других выделений памяти.

LPVOID mvReAlloc(LPMV mV, LPVOID ptr, int nNewSize)

Меняет размер буфера памяти, ранее выделенный вызовами mvMalloc, mvCalloc или mvReAlloc.

Параметры:

LPMV mV указатель на информационную структуру mv.
LPVOID ptr указатель на буфер для повторного распределения.
int nSize новый размер выделяемого буфера.

Возвращаемое значение: указатель на новый буфер. Если произошла ошибка, то функция должна вернуть NULL, и оригинальный буфер не будет изменен. Эта функция работает наподобие функции realloc языка C.

Замечание: используйте эту подпрограмму, если нужно выделить буфер памяти, который будет освобожден кодом CF runtime, например если должны перераспределить буфер, выделенный системой CF, и сохраненный в runtime-структуры CF. Используйте обычную функцию realloc для своих собственных перераспределений памяти.

mvRecalcLayout(LPMV mV)

Эта функция повторно выравнивает прикрепляемые окна подчиненных приложений (re-arranges docked sub-applications).

Параметры:

LPMV mV указатель на информационную структуру mv.

Возвращаемое значение: отсутствует.

callRunTimeFunction(LPRDATA rdPtr, RFUNCTION_CALLMOVEMENT,
                    WPARAM wParam, LPARAM lParam)

Вызывает функцию перемещения (movement) расширения "ActionEntry".

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта для вызова.
WPARAM wParam идентификатор действия (action), переданный функции ActionEntry.
LPARAM lParam параметр, который будет передан, суммирует его функция ActionEntry.

Возвращаемое значение: отсутствует.

Замечание: эта функция позволяет Вам добавить новые действия к Вашему расширению перемещения. Для получения дополнительной информации прочитайте документацию по Movement developement kit.

callRunTimeFunction(LPRDATA rdPtr, RFUNCTION_CONTINUE, 
                    WPARAM wParam, LPARAM lParam)

Завершает режим паузы.

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта.
WPARAM wParam не используется.
LPARAM lParam не используется.

Возвращаемое значение: отсутствует.

Замечание: для использования, когда Вы завершили длинную задачу. Комплементарная часть к RFUNCTION_PAUSE.

callRunTimeFunction(LPRDATA rdPtr, RFUNCTION_DESTROY, WPARAM wParam, LPARAM lParam)

Удаляет объект.

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта.
WPARAM wParam не используется.
LPARAM lParam не используется.

Возвращаемое значение: отсутствует.

Замечание: после вызова этой функции объект уничтожается по окончанию текущего цикла.

callRunTimeFunction(LPRDATA rdPtr, RFUNCTION_EDITINT, WPARAM wParam, LPARAM lParam)

Открывает диалоговое окно для редактирования целочисленной величины.

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта.
WPARAM wParam не используется.
LPARAM lParam указатель на структуру EditDebugInfo, содержащую значение для редактирования.

Возвращаемое значение: для диалогового окна может быть IDOK, если пользователь нажал OK, или IDCANCEL, если пользователь нажал cancel (отменить). Редактируемое значение будет находиться в поле "value" структуры EditDebugInfo.

Эта функция предоставлен как быстрый способ редактирования значения, отображаемого в списке отладчика.

Обратите внимание, что эта функция не доступна, если только приложение не работает в режиме свободного запуска (run only mode).

Замечание: структура EditDebugInfo содержит 2 поля, которые Вы должны обслужить для работы функции:

LPSTR pTitle указатель на строку, которая будет использована как заголовок окна диалога. NULL используется для стандартного заголовка.
int value значение для редактирования.

callRunTimeFunction(LPRDATA rdPtr, RFUNCTION_EDITINT, WPARAM wParam, LPARAM lParam)

Открывает окно диалога для редактирования строки.

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта.
WPARAM wParam не используется.
LPARAM lParam указатель на структуру EditDebugInfo, содержащую строку для редактирования.

Возвращаемое значение: для окна это может быть IDOK, если пользователь нажал OK, или IDCANCEL если пользователь нажал cancel (отмена). Отредактированное значение можно найти в поле "value" структуры EditDebugInfo.

Эта функция предоставлена как быстрый способ редактирования строки, отображаемой в списке отладчика.

Обратите внимание, что эта функция недоступна, если только приложение не работает в режиме свободного запуска (run only mode).

Замечание: структура редактирования EditDebugInfo содержит три поля, которые Вы должны обслуживать, чтобы функция работала:

LPCTSTR pTitle указатель на строку, которая будет использоваться в качестве заголовка диалогового окна. NULL используется для стандартного заголовка.
LPTSTR pText строка для редактирования и буфер редактирования.
int lText длина буфера строки.

callRunTimeFunction(LPRDATA rdPtr, RFUNCTION_EXECPROGRAM, WPARAM wParam, LPARAM lParam)

Запускает внешнюю программу.

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта.
WPARAM wParam не используется.
LPARAM lParam указатель на структуру prgParam, содержащую ссылку на программу.

Возвращаемое значение: отсутствует.

Замечание: структура prgParam содержит 3 поля, которые Вы должны заполнить:

short prgFlags флаги для запуска программы. PRGFLAGS_WAIT ставит CF на паузу, пока приложение на завершит работу. PRGFLAGS_HIDE скрывает окно CF, пока работает программа.
TCHAR prgPath[_MAX_PATH] содержит путь до запускаемой программы.
TCHAR prgCommand[108] содержит командную строку (ограничено 108 символами).

callRunTimeFunction(LPRUNDATA rdPtr, RFUNCTION_GENERATEEVENT,
                    WPARAM wParam, LPARAM lParam)

Генерирует действительное событие расширения (extension true event).

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта.
WPARAM wParam код события (event code).
LPARAM lParam параметр события (eventual parameter), которое может требоваться Вашему условию (condition).

Возвращаемое значение: отсутствует.

Замечание: в системе CF имеется большое отличие между реальными условиями (TRUE conditions) и вычисленным условиями (evaluated conditions). Обратитесь к секции условий (conditions) и действий (actions) для дополнительной информации.

RFUNCTION_GENERATEEVENT посылает события в очередь обработки событий (event-processing queue). Код события (event code) должен быть кодом, определяемым в Вашем расширении. Вы также должны определить подпрограмму обработки для этого условия.

Если пользователь вставил условие как первую строку события, то будет вызвана Ваша подпрограмма.

callRunTimeFunction(LPRDATA rdPtr, RFUNCTION_GETFILEINFOS,
                    WPARAM wParam, LPARAM lParam)

Возвращает информацию по текущему приложению: диск (drive), путь до исполняемого файла (pathname), имя (name) и т. д.

Параметры:

LPRDATA rdPtr указатель на структуру RUNDATA объекта.
WPARAM wParam код информации, которая Вам нужна.
LPARAM lParam указатель на буфер назначения, должен быть как минимум длиной _MAX_PATH символов.

Возвращаемое значение: отсутствует (оно находится в буфере).

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

wParam может принимать следующие значения:

FILEINFO_DRIVE: будет возвращен диск приложения (application drive).
FILEINFO_DIR: будет возвращен каталог размещения приложения (application directory).
FILEINFO_PATH: будет возвращен полный путь до приложения (application complete path).
FILEINFO_APPNAME: будет возвращено имя приложения (application name).