Плагины

Введение

Этот документ даёт исчерпывающее описание механизма работы плагинов для Кветки и их взаимодействия с основной программой.
Плагин --- это внешний модуль, который подключается к основной программе, добавляя в неё дополнительную функциональность.

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

Каждый плагин организован в виде dll библиотеки. Для корректного взаимодействия плагина с программой необходимо, чтобы

  • он был сохранён в подкаталоге plugins каталога с программой;
  • содержал внешнюю функцию StartKvetkaProc.

    См. дальше:

  • принцип работы плагина
  • процедуры для взаимодействия с программой
  • cписок доступных хэндлеров
  • cписок доступных настроек
  • cписок доступных параметров


Принцип работы

Кветка производит запуск плагинов сразу же после инициализации всех окон и внутренних параметров. При этом производится поиск всех dll библиотек в подкаталоге plugins, и в них управление передаётся процедуре StartKvetkaProc. Таким образом, в коде плагина эта процедура должна быть объявлена внешней. В Delphi, например, в коде должно быть записано:
exports
StartKvetkaProc;

В параметрах процедуры StartKvetkaProc программа передаёт плагину указатель на другую процедуру GetFunc. С её помощью плагин будет получать адреса необходимых ему процедур для управления программой. Например, в прилагаемом модуле plugcommon.pas получение необходимых процедур реализовано в процедуре InitPlugin.

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

Перед закрытием Кветки для каждого плагина вызывается процедура StopKvetkaProc, если она у плагина есть. Это позволяет плагину подготовиться перед закрытием.

Список доступных процедур.


StartKvetkaProc и GetProc

StartKvetkaProc

StartKvetkaProc - это основная процедура плагина. Именно она вызывается при каждом его запуске. В ней должен быть рализован доступ ко всем возможностям плагина.

procedure StartKvetkaProc (
GetFunc : GetProc // адрес процедуры, с помощью которой программа предоставляет плагину свои процедуры
);

Параметры
GetFunc :
адрес процедуры типа GetProc, с помощью которой Кветка передаёт плагину необходимые ему процедуры. Список доступных процедур.

Дополнение
StartKvetkaProc Должна быть доступна из основной программы. Для этого она должна быть объявлена внешней. В Delphi это делается с помощью
exports
StartKvetkaProc;

GetProc

Процедура типа GetProc служит для получения из основной программы необходимых плагину процедур.

GetProc = function (
id : integer // идентификатор процедуры
) : pointer;

Параметры
id :
Идентификатор процедуры, которую требуется получить от программы. Список доступных процедур.

Возвращаемое значение
Указатель на запрашиваемую функцию. Если программе идентификатор id неизвестен, то возвращается nil.

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


StopKvetkaProc

StopKvetkaProc --- процедура, запускяемая перед самым закрытием плагина. Наличие её в плагине необязательно.

procedure StopKvetkaProc ( );

Примечание. Если в плагине присутствует StopKvetkaProc, то она должна быть объявлена внешней. В Delphi это делается с помощью
exports
StopKvetkaProc;


Работа с критическими секциями в Кветке

В Кветке одновременно работают два потока. Один обслуживает движок: подаёт ему команды, обрабатывает полученную информацию и отображает её в окне "Движок"; второй делает всё остальное. Так как в Windows работа потока может быть прервана в любое время, то при доступе к общему содержимому памяти может оказаться, что в начале процедуры оно одно, а в какой-то момент становится совсем другим. Это вызывает ошибки, которые невозможно зафиксировать и повторить, что крайне затрудняет отладку.

Чтобы такого не происходило, в Кветке используется механизм критических секций. Смысл критической секции в том, что выполнять код внутри неё одновременно может только один поток. Если другой поток подходит к началу критической секции, то он прерывает своё выполнение до тех пор, пока первый из неё не выйдет. Подробнее о работе с критическими секциями см. документацию WinAPI.

В Кветке используется одна критическая секция, описываемая параметром lcrits (IPCriticalSection). Весь код основного потока находится внутри неё. Это достигается за счёт следующего кода:
while GetMessagew (am, 0, 0, 0) do begin
EnterCriticalSection (lcrits); // Открываем критическую секцию
TranslateAccelerator (hw, hacc, am);
TranslateMessage (am);
DispatchMessagew (am); // обрабатываем поступившее сообщение
LeaveCriticalSection (lcrits); // Закрываем критическую секцию
end;

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


Список доступных процедур

Здесь приведены все процедуры, к которым можно получить доступ через GetProc. Большинство из них можно перегрузить с помощью SetProc. Если какую-то процедуру перегрузить нельзя, то об этом будет отдельно сказано.
    Выберите категорию:
  • Процедуры общего назначения
  • Процедуры-события главного окна
  • Процедуры рисования доски
  • Процедуры для работы со вспомогательными окнами
  • Процедуры для работы с окнами "Журнал" и "Партии"
  • Процедуры для работы с движком
  • Процедуры управления партией


Процедуры плагина общего назначения

процедура | идентификатор (для GetFunc)
GetHandle | IFGetHandle
GetOptions | IFGetOptions
SetProc* | IFSetFunction
GetParam* | IFGetParameter
RegHotKey* | IFRegisterHotKey

* - Эти процедуры нельзя перегрузить.


Gethandle

GetHandle возвращает хэндлеры, используемые в Кветке, по их идентификаторам.

function GetHandle (
id : integer // идентификатор запрашиваемого хэндлера
) : integer;

Параметры
id :
Идентификатор запрашиваемого хэндлера. Список доступных хэндлеров приведен ниже. Или смотрите графическое представление доступных хэндлеров.

Возвращаемое значение
Запрашиваемый хэндлер. Если идентификатор id Кветке неизвестен, то возвращается 0.

Список доступных идентификаторов.
Идентификатор | Тип | Описание
IHMainWindow | HWND | Главное окно
IHMainMenu | HMenu | Главное меню
IHWindowsSubMenu | HMenu | Подменю "Дополнительные окна" главного меню
IHEnginesSubMenu | HMenu | Подменю "Движок" главного меню
IHMovesMenu | HMenu | Контекстное меню окна "журнал"
IHNAGMenu | HMenu | Подменю "Метки !, ? и т.п." контекстного меню окна "Журнал"
IHGamesMenu | HMenu | Контекстное меню окна "Партии"
IHEngineMenu | HMenu | Меню окна "Движок"
IHChooseWindow | HWND | Окно выбора фигуры (при продвижении пешки)
IHMovesIButton | HWND | Кнопка "i" окна "Журнал"
IHMovesScrollBar | HWND | Область прокрутки окна "Журнал"
IHGamesScrollBar | HWND | Область прокрутки окна "Партии"
IHEngineCMDEdit | HWND | Поле ввода командной строки окна "Движок"
IHEngineOutEdit | HWND | Поле вывода всей информации от движка.
IHEngineMultipvEdit | HWND | Поле ввода числа выводимых вариантов в окне "Движок"
IHEngineOut2Edit | HWND | Поле вывода вариантов ходов в окне "Движок"
IHEngineGoButton | HWND | Кнопка "Остановить" / "Проджолжить" окна "Движок"
IHTagsNameEdit | HWND | Поле ввода названия тега PGN в окне "Информация о партии"
IHTagsValueEdit | HWND | Поле ввода значение тега PGN в окне "Информация о партии"
IHTagsNameListBox | HWND | Список имеющихся названий тегов PGN
IHTagValyeListBox | HWND | Список имеющихся Значений тегов PGN
IHFENPlyNumberEdit | HWND | Поле ввода для числа необратимых полуходов в окне "Настройки позиции"
IHFENNextMoveNumEdit | HWND | Поле ввода для номера следующего хода в окне "Настройки позиции"
IHBoardDC | HDC | Графический контекст доски с фигурами (используется для прорисовки доски в памяти)
IHBoardBitmap | HBitmap | Битовая карта доски с фигурами
IHCellDC | HDC | Графический контекст отдельной клетки
IHCellBitmap | HBitmap | Битовая карта для отдельной клетки

Примечание.
Не все хэндлеры в Кветке можно получить с помощью GetHandle. Доступ к хэндлерам большинства кнопок. Доступ к хэндлерам вспомогательных окон.


GetOptions

GetOptions возвращает указатель на настройку Кветки по её идентификатору. Настройки обычно остаются неизменными в течение всей работы программы и восстанавливаются при следующем её запуске.

function GetOptions (
id : integer // идентификатор запрашиваемой настройки
) : pointer;

Параметры
id :
Идентификатор запрашиваемой настройки. Список имеющихся настроек.

Возвращаемое значение
Указатель на запрашиваемую настройку. Если идентификатор id Кветке неизвестен, то возвращается nil.

Примечание.
Используя указатели, настройки можно изменять. Однако после этого программа может работать нестабильно. Настоятельно рекомендуется перезапускать Кветку после каждого изменения настроек.


GetParam

GetParam возвращает указатель на некоторый параметр Кветки по его идентификатору. Параметры обычно характеризуют состояние программы в каждый конкретный момент.

function GetOptions (
id : integer // идентификатор запрашиваемого параметра
) : pointer;

Параметры
id :
Идентификатор запрашиваемого параметра. Список имеющихся параметров.

Возвращаемое значение
Указатель на запрашиваемый параметр. Если идентификатор id Кветке неизвестен, то возвращается nil.

Примечание.
Используя указатели, параметры Кветки можно изменять. Однако использовать такую возможность следует с осторожностью. Необходимо чётко представлять, как на изменение параметра отреагирует программа.


RegHotKey

RegHotKey Регистрирует в программе новую горячую клавишу и производит подготовку к добавлению нового пункта меню.

function RegHotKey (
acc : ACCEL; // описание добавляемой горячей клавиши
p : pointer // указатель на процедуру-обработчик нажатия на горячую клавишу
) : integer;

Параметры
acc :
Описание горячей клавиши, которая будет зарегистрирована. В него входит: acc.fVirt - какие из функциональных клавиш должны быть нажаты; acc.key - виртуальный или ASCII код нажимаемой клавиши. Если acc.key=0, то горячая клавиша не регистрируется (может пригодиться для создания только пункта меню).

p :
Указатель на процедуру-обработчик нажатия на горячую клавишу. Процедура не должна передавать параметров и не должна возвращать никакое значение.

Возвращаемое значение
Уникальный идентификатор. При выборе пункта меню с таким идентификатором управление будет передаваться процедуре p.

Дополнения
При выполнении RegHotKey производится следующее:

  • Генерируется уникальный идентификатор для пункта меню, к нему привязывается процедура-обработчик p.
  • Если acc.key<>0 , то регистрируется горячая клавиша, по нажатию на которую будет выполняться p.
  • Уникальный идентификатор возвращается плагину.

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


SetProc

SetProc подменяет одну из процедур Кветки на процедуру плагина. За счёт этого можно существенно изменять функциональность основной программы.

procedure SetProc (
id : integer; // идентификатор заменяемой процедуры
proc : pointer // указатель на заменяющую процедуру
);

Параметры
id :
идентификатор заменяемой процедуры. Здесь используются те же идентификаторы, что и в процедуре GetProc. Однако не каждая процедура может быть заменена. Список доступных процедур.

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


Процедуры-события главного окна

процедура | идентификатор (для GetFunc)
IfPaint | IFMainonPaint
IfLButtonDown | IFMainonlButtonDown
IfMouseMove | IFMainonMouseMove
IfLButtonUp | IFMainOnlButtonUp
IfHotKey | IFMainonHotKey
IfResize | IFMainonResize
IfKeyDown | IFMainonKeyDown
IfDoubleClick | IFMainonDoubleClick
klclick | IFLeftClick
krclick | IFRighttClick
kuclick | IFGoUp
kdclick | IFGoDown
khclick | IFGoHome
keclick | IFGoEnd
kpuclick | IFPrevClick
kpdclick | IFNextClick
ktclick | IFonTopClick
kminclick | IFMinimizeClick
kmnclick | IFMenuClick
krotclick | IFRotateClick
kxclick | IFXClick
ifdropfl | IFMainDropFile


IfDoubleClick

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

procedure IfDoubleClick (
x, y : smallint // координаты курсора мыши
);

Параметры
x , y :
Координаты курсора мыши. В IfDoubleClick используются локальные координаты относительно главного окна. То есть, (0 , 0) - это координата верхнего левого угла главного окна. Координаты измеряются в пикселях.


ifdropfl

ifdropfl выполняется при получении главным окном события WM_DROPFILES. Это происходит при перетаскивании файла в Кветку. При этом производится попытка открыть перетащенного файла. Если он имеет расширение FEN, то он открывается как файл позиции. В противном случае он открывается как файл в формате PGN.

procedure ifdropfl (
drop : integer // хэндлер перетаскиваемого файла
);

Параметры
drop :
Хэндлер, идентифицирующий внутреннюю структуру, описывающую перетаскиваемый файл. Этот хэндлер используется такими процедурами WinAPI, как DragFinish, DragQueryFile и DragQueryPoint.

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


IfHotKey

IfHotKey выполняется при выборе большинства пунктов меню или нажатии большинства из горячих клавиш. Но не всех. Процедура не обрабатывает горячие клавиши и пункты меню, добавленные плагинами. Также не обрабатываются пункты подменю "Дополнительные окна" главного меню.

procedure IfHotKey (
id : integer // идентификатор горячей клавиши/пункта меню
);

Параметры
id :
Идентификатор горячей клавиши или пункта меню. Это тот же самый идентификатор, который передаётся вместе с сообщением WM_COMMAND.

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

Список обрабатываемых IfHotKey идентификаторов.
Идентификатор | горячая клавиша | Описание
1 | Ctrl + O | Открыть файл...
2 | Ctrl + S | Сохранить все партии
3 | Ctrl + Shift + S | Сохранить одну партию
4 | Ctrl + N | Новая партия
18 | Tab | Сделать следующее окно активным (нажатие Tab).
19 | --- | Вывод движка
20 | --- | Варианты ходов
22 | --- | Удалить движок...
23 | Ctrl + W | Показать/скрыть все вспомогательные окна
24 | Ctrl + C; Ctrl + Ins | Скопировать в буфер
25 | Del | Удалить часть партии
26 | --- | Добавить комментарий
28 | Ctrl + V; Shift + Ins | Вставить партию из буфера
29 | Ctrl + Shift + V | Добавить ходы из буфера
33 | --- | Сохранить партии как...
34 | --- | Добавить партию
35 | --- | Удалить партию
38 | Ctrl + H | Расставить фигуры
39 | Ctrl + Alt + S | Сохранить позицию
40 | Ctrl + Alt + C | Копировать позицию в буфер
41 | Ctrl + Alt + V | Вставить позицию из буфера
43 | --- | Тонкие настройки движка...
44 | Ctrl + Space | Сделать ход движка


IfKeyDown

IfKewDown

IfKeyDown выполняется при получении главным окном события WM_KEYDOWN. Список обрабатываемых клавиш приводится ниже.

procedure IfKeyDown (
key : integer // виртуальный код нажатой клавиши
);

Параметры
key :
Виртуальный код нажатой клавиши.

Дополнение
Перегружая эту процедуру, можно добавлять в программу реакцию на нажатие новых клавиш.

Список обрабатываемых клавиш.
Клавиша | Код | Действие
Стрелка влево | 37 | Перемещение позиции на один ход назад. (См. klclick).
Стрелка вправо | 39 | Перемещение позиции на один ход вперёд. (См. krclick).
Стрелка вверх | 38 | Перемещение позиции в окне "Журнал" на одну строчку вверх. (См. kuclick).
Стрелка вниз | 40 | Перемещение позиции в окне "Журнал" на одну строчку вниз. (См. kdclick).
Page Up | 33 | Переход к предыдущей партии. (См. kpuclick).
Page Down | 34 | Переход к следующей партии. (См. kpdclick).
Home | 36 | Перемещение позиции к началу партии. (См. khclick).
End | 35 | Перемещение позиции к концу партии. (См. keclick).
Del | 46 | Удаление части партии, начиная с текущего хода.


IfLButtonDown

IfLButtonDown выполняется при получении главным окном события WM_LBUTTONDOWN. При этом определяется, в каком месте окна находится мышь. В зависимости от этого производятся подготовительные действия для перемещения окна (см. IPIsWindowMoving), изменения его размеров (см. IPTipMainWindowStretch) либо для захвата мышью фигуры.

procedure IfLButtonDown (
x , y : integer // координаты курсора мыши
);

Параметры
x , y :
Координаты курсора мыши. В IfLButtonDown используются локальные координаты относительно главного окна. То есть, (0 , 0) - это координата верхнего левого угла главного окна. Координаты измеряются в пикселях.

Дополнения
Перегружая эту процедуру, можно изменять реакцию главного окна на нажатие кнопки мыши. При этом может потребоваться хэндлер главного окна (см. IHMainWindow), отступы слева, справа, сверху и снизу от доски до границы окна (см. INMainUpSpace, INMainDownSpace, INMainHorzSpace), ширина верхней части окна с кнопками (см. INMainButtonSpace) и ширина всей доски и одной её клетки (см. IPFieldWidth, IPCellWidth).

Пример кода, перегруженной процедуры IfLButtonDown:

procedure NewIfLButtonDown(x, y : integer);
var UpSpace, HorzSpace : ^integer;
ncx, ncy : ^integer;
CellWidth : ^integer;
nx, ny : integer; //Координаты верхнего левого угла доски
Cellx, Celly : byte; // Координаты нажатой клетки
begin
{Получаем от программы необходимые параметры}
UpSpace := GetOptions (INMainUpSpace);
HorzSpace := GetOptions (INMainHorzSpace);
ncx := GetOptions (INHorzFieldBorder);
ncy := GetOptions (INVertFieldBorder);
CellWidt := GetParam (IPCellWidth);
{Вычисляем координаты доски}
nx := HorzSpace^ + ncx^;
ny := UpSpace^ + ncy^;
if (x >= nx) and (x <= nx + 8 * CellWidt^ ) and (y >= ny) and (y <= ny + 8 * CellWidt^ ) then
begin
{Вычисляем координаты клетки, над которой находится курсор мыши}
Cellx := (x - nx) div CellWidt^;
Celly := (y - ny) div CellWidt^;
MessageBox ( 0, 'Вы кликнули по клетке ' + chr (ord('a') + Cellx) + InttoStr (Celly + 1), 'WM_LBUTTONDOWN', MB_OK);
end else
OldIfLButtonDown (x, y); //вызываем старую процедуру обработки.
end;


IfLButtonUp

IfLButtonUp выполняется при получении главным окном события WM_LBUTTONUP. При этом производятся действия по завершению перемещения окна, изменения его размеров либо перемещения по доске фигуры.

procedure IfLButtonUp (
x , y : integer // координаты курсора мыши
);

Параметры
x , y :
Координаты курсора мыши. В IfLButtonUp используются локальные координаты относительно главного окна. То есть, (0 , 0) - это координата верхнего левого угла главного окна. Координаты измеряются в пикселях.

Обычно перегрузка этой процедуры будет происходить совместно с перегрузкой IfLButtonDown и IfMouseMove. Таким образом можно изменять реакцию главного окна на действия мыши. При этом может потребоваться хэндлер главного окна (см. IHMainWindow), отступы слева, справа, сверху и снизу от доски до границы окна (см. INMainUpSpace, INMainDownSpace, INMainHorzSpace), ширина верхней части окна с кнопками (см. INMainButtonSpace) и ширина всей доски и одной её клетки (см. IPFieldWidth, IPCellWidth).


IfMouseMove

IfMouseMove выполняется при получении главным окном события WM_MOUSEMOVE. Если при этом нажата левая кнопка мыши, то IfMouseMove может выполнять одно из следующих действий:
1. Перемещение окна или изменение его размеров (см. IPIsWindowMoving, IPTipMainWindowStretch);
2. Перемещение по доске захваченной мышью фигурки (см. IPIsFigureMoving).

procedure IfMouseMove
x , y : smallint // координаты курсора мыши
);

Параметры
x , y :
Координаты курсора мыши. В IfMouseMove используются локальные координаты относительно главного окна. То есть, (0 , 0) - это координата верхнего левого угла главного окна. Координаты измеряются в пикселях.

Дополнение
Обычно перегрузка этой процедуры будет происходить совместно с перегрузкой IfLButtonDown и IfLButtonUp. Таким образом можно изменять реакцию главного окна на действия мыши. При этом может потребоваться хэндлер главного окна (см. IHMainWindow), отступы слева, справа, сверху и снизу от доски до границы окна (см. INMainUpSpace, INMainDownSpace, INMainHorzSpace), ширина верхней части окна с кнопками (см. INMainButtonSpace) и ширина всей доски и одной её клетки (см. IPFieldWidth, IPCellWidth).


IfPaint

IfPaint выполняется при получении главным окном события WM_PAINT. При этом главное окно полностью перерисовывается.

procedure IfPaint ( );

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

В IfPaint доска не перерисовывается. Она просто копируется из внутреннего графического контекста (см. IHBoardDc). Для перерисовки доски используется процедура DrawDoska.

Пример кода, перегруженной процедуры IfPaint:

procedure NewIfPaint();
var MainWnd : HWND;
pst : PaintStruct;
begin
MainWnd := GetHandle (IHMainWindow);
BeginPaint (MainWnd , pst);
......................................................................
// Рисуем на pst.hdc
......................................................................
Repaint (pst.hdc); // Перерисовываем доску
EndPaint (MainWnd, pst);
end;


IfResize

IfResize выполняется при получении главным окном события WM_SIZE. При этом изменяются положения кнопок, изменяется регион главного окна, перерисовываются на внутренних графических структурах границы окна и сама доска (см. IHBoardDC, IHBoardBitmap и DrawDoska).

procedure IfResize (
wind : HWND; // Хэндлер окна, меняющего размер
wid, hei : integer //новые ширина и высота окна
);

Параметры
wind :
Хэндлер окна, меняющего размер. Всегда будет равно хэндлеру главного окна (IHMainWindow).

wid, hei :
Новые ширина и высота окна.

Дополнение
Перегружая эту процедуру, можно изменить внешний вид главного окна. То, каким образом этот внешний вид будет изменяться при изменении размера окна.


kdclick

kdclick выполняется при нажатии на клавишу "стрелка вниз". При этом позиция перемещается на одну строчку вниз в окне "Журнал".

procedure kdclick ( );

Дополнение
Перегружая эту процедуру, можно изменять реакцию на нажатие соответствующей клавиши.


keclick

keclick выполняется при нажатии на клавишу End. При этом позиция переходит в конец партии.

procedure keclick ( );

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

Пример кода, перегруженной процедуры keclick. Сделаем, чтобы при нажатии на End позиция переходила не на самый последний ход в партии, а на самый последний ход в текущем ответвлении.

procedure Newkeclick ( );
begin
MoveTo ( NumSteps ); // Перемещаемся в конец ответвления
UpdWindows (true, false); // Обновляем изображение доски и окна "Журнал".
end


khclick

khclick выполняется при нажатии на клавишу Home. При этом позиция переходит в начало партии.

procedure khclick ( );

Дополнение
Перегружая эту процедуру, можно изменять реакцию на нажатие соответствующей клавиши.


klclick

klclick выполняется при нажатии на кнопку "Предыдущий ход" либо при нажатии на клавишу "стрелка влево". При этом позиция переходит на один ход назад.

procedure klclick ( );

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


kminclick

kminclick выполняется при нажатии на кнопку "Минимизировать". При этом главное окно сворачивается на панели инструментов, а все вспомогательные окна становятся невидимыми.

procedure kminclick ( );

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

При последующем восстановлении окна необходимо различать, какие из вспомогательных окон были невидимы до минимищации, а какие --- нет. Для этого используется поле vis в структуре TAuxWindowInfo, описывающей вспомогательные окна.


kmnclick

kmnclick выполняется при нажатии на кнопку "Меню". При этом рядом с кнопкой появляется главное меню программы.

procedure kmnclick ( );

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


kpdclick

kpdclick выполняется при нажатии на кнопку "Следующая партия" или при нажатии на клавишу Page Down. При этом происходит переход к следующей партии из списка партий. Если текущая партия идёт последней в списке, то произойдёт следующее: если в партии сделан уже хотя бы один ход, то в конце списка создастся новая партия, и она станет текущей. В противном случае ничего не произойдёт.

procedure kpdclick ( );

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


kpuclick

kpuclick выполняется при нажатии на кнопку "Предыдущая партия" или при нажатии на клавишу Page Up. При этом происходит переход к предыдущей партии из списка партий. Если текущая партия идёт первой в списке, то ничего не происходит.

procedure kpuclick ( );

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


krclick

krclick выполняется при нажатии на кнопку "Следующий ход" либо при нажатии на клавишу "стрелка вправо". При этом позиция переходит на один ход вперёд. Если же в партии имеется несколько вариантов следующего хода, то появляется диалоговое окно выбора одного из них.

procedure krclick ( );

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


krotclick

krotclick выполняется при нажатии на кнопку "Перевернуть доску". При этом переворачивается доска со всеми фигурами.

procedure kpuclick ( );

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

Чтобы узнать, перевёрнута ли доска, используется параметр IPIsBoardFieldRotated.


ktclick

ktclick выполняется при нажатии на кнопку "Поверх всех окон". При этом включается или выключается (в зависимости от состояния кнопки) режим "поверх всех окон". В этом режиме окна Кветки располагаются поверх других окон даже если программа сейчас неактивна.

procedure ktclick ( );

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


kuclick

kuclick выполняется при нажатии на клавишу "стрелка вверх". При этом позиция перемещается на одну стрчку вверх в окне "Журнал".

procedure kuclick ( );

Дополнение
Перегружая эту процедуру, можно изменять реакцию на нажатие соответствующей клавиши.


kxclick

kxclick выполняется при нажатии на кнопку "Выход". При этом программа закрывается.

procedure kxclick ( );

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


Процедуры рисования доски

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

процедура | идентификатор (для GetFunc)
DrawDoska | IFDrawBoard
DrawFig | IFDrawFigure
DrawCell | IFDrawCell


DrawCell

DrawCell рисует пустую клету с заданными координатами на внутреннем графическом контексте.

procedure DrawCell
sz : integer; // ширина и высота клетки доски
x, y : byte // координаты отображаемой клетки
);

Параметры
sz :
Ширина и высота клетки доски. Измеряется в пикселях.

x, y :
Координаты клетки. Изменяются от 0 до 7: клетка с координатами (0, 0) находится в верхнем левом углу, с координатами (0, 7) - в правом верхнем углу. Параметры x и y не должны выходить за указанные пределы, в противном случае это приведёт, скорее всего, к аварийному закрытию Кветки.

Дополнения
Перегружая DrawCell, можно изменять внешний вид клеток доски.

В Кветке DrawCell рисует одноцветный квадрат, цвет которого берётся из настроек INCellColors, а цвет границы --- из INFieldLineColor. Для рисования клетки успользуются следующие параметры: IPCellBits - массив пикселей клетки; IHCellDC - графический контекст клетки и IHCellBitmap - битовая карта клетки. При перегрузке DrawCell рекомендуется использовать именно их, чтобы корректно работала DrawDoska и некоторые другие процедуры, недоступные в плагине.


DrawDoska

DrawDoska Рисует доску с фигурами на ней на внутреннем графическом контексте.

procedure DrawDoska
sz : integer; // ширина и высота одной клетки доски
ds : pointer; // указатель на структуру доски
ifr : boolean = false // находится ли доска в режиме расстановки фигур
);

Параметры
sz :
Ширина и высота клетки доски. Измеряется в пикселях.

ds :
Указатель на структуру доски. Она содержит такую информацию, как расположение фигур на доске, возможность сделать рокировку и проч. На данный момент (Кветка 2.3) эта структура ещё не устоялась. Поэтому использовать её внутренние параметры настоятельно не рекомендуется. Вместо этого, для доступа к массиву клеток доски используется параметр IPFigures.

ifr :
Указывает, находится ли доска в состоянии расстановки фигур. Если да (ifr = true), то слева и справа от непосредственно самой доски рисуются фигуры, которые можно перемещать на доску.

Дополнения
Перегружая DrawDoska, можно изменять внешний вид доски.

Для рисования доски можно воспользоваться одним из следующих параметров: IPBoardBits - массив пикселей доски; IHBoardDC - графический контекст доски и IHBoardBitmap - битовая карта доски. Кроме того, могут понадобиться параметры:

  • IPWhitePawnBits, IPBlackPawnBits, ..., IPBlackKingBits - массивы пикселей для каждой из фигур. Они фромируются с помощью процедуры DrawFig.
  • IPCellBits, IHCellDC, IHCellBitmap - массив пикселей, графический контекст и битовая карта пустой клетки. Они формируются с помощью процедуры DrawCell.
  • IPFigures - массив клеток доски.
  • IPIsBoardFieldRotated - перервёрнута ли доска.
  • INHorzFieldBorder, INVertFieldBorder - отступ от начала графического контекста до начала доски по горизонтали и вертикали
  • INHorzPositionBorder, INVertPositionBorder - Ширина вертикальной линии при расстановке фигур и высота горизонтальной линии.

    При выполнении DrawDoska в программе гарантируется, что все необходимые массивы пикселей, битовые карты и графические контексты проинициализированы и имеют необходимый размер, соответствующий sz (Исключение - пустая клетка. Её внешний вид зависит от координат, поэтому каждая отдельная клетка должна инициализироваться в DrawCell непосредственно перед тем, как она понадобится). Все эти параметры инициадизируются при обработке сообщения WM_SIZE главного окна. Поэтому ручной вызов DrawDoska при обработке WM_SIZE может привести к нежелательным результатам.

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


DrawFig

DrawFig рисует фигуру на внутреннем графическом контексте.

procedure DrawFig
sz : integer; // ширина и высота клетки доски
fig : TFigur; // фигура
dc : HDC; // графический контекст, где рисуется фигура
pt : pointer // указатель на массив пикселей фигуры
);

Параметры
sz :
Ширина и высота клетки доски. Измеряется в пикселях.

fig :
описывает фигуру, которую следует отрисовать. См. описание TFigur. Если fig = empty, то поведение процедуры неопределено.

dc :
Графический контекст, где будет рисоваться фигура.

pt :
Указатель на массив пикселей фигуры. dc и pt должны быть взаимосвязаны. Иначе, возможно, часть фигуры отрисуется на dc, а часть - в pt. В фигуре пиксель цвета -1 имеет специальное значение: он будет прозрачным при отображении фигуры на доске. Чтобы сделать фон прозрачным, можно в самом начале DrawFig воспользоваться строкой
fillchar (pt^, 4 * sz * sz, 255);

Дополнения
Перегружая DrawFig, можно изменять внешний вид фигур.

Для рисования фигуры можно воспользоваться настройкой INFigureAspectRatio - отношение величины отступа фигуры к ширине клетки.

В следующей таблице приведены параметр, используемый в качестве pt в процедуре DrawFig, и файл, из которого загружается картинка для фигуры:
парамтер | фигура | Файл
IPWhitePawnBits | белая пешка | images/p_w1.emf
IPBlackPawnBits | чёрная пешка | images/p_b1.emf
IPWhiteKnightBits | белый конь | images/kon_w.emf
IPBlackKnightBits | чёрный конь | images/kon_b.emf
IPWhiteBishopBits | белый слон | images/s_w.emf
IPBlackBishopBits | чёрный слон | images/s_b.emf
IPWhiteRookBits | белая ладья | images/l_w1.emf
IPBlackRookBits | чёрная ладья | images/l_b1.emf
IPWhiteQueenBits | белый ферзь | images/f_w.emf
IPBlackQueenBits | чёрный ферзь | images/f_b.emf
IPWhiteKingBits | белый король | images/k_w.emf
IPBlackKingBits | чёрный король | images/k_b.emf
При вызове DrawFig вручную рекомендуется в качестве pt использовать те же парамтеры.

В Кветке DrawFig вызывается только при обработке главным окном сообщения WM_SIZE. В остальное время фигуры не перерисовываются.


Процедуры для работы со вспомогательными окнами

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

Список процедур для работы со вспомогательными окнами
процедура | идентификатор (для GetFunc)
SozDopWnd | IFCreateKvetWindow
CloseWnd | IFDeleteKvetWindow
ShowModal | IFShowModal
DopfProc | IFDopWindowProc
SozdCombo | IFCreateCombo
CheckCombo | IFCheckComboBox
AddKnop | IFAddButton
DelKnop | IFDeleteButton
WriteonBut | IFWriteonButton
SetWndRgn | IFSetWindowRgn
SetXKnop | IFSetXButton
IfPaintX | IFButXOnPaint
DrawCapt | IFDrawCaption
DrawDopFon | IFDrawBackGround


AddKnop

AddKnop Добавляет созданную кнопку к списку кнопок в Кветке (см. IPButtonList). Добавленная таким образом кнопка будет выглядеть и вести себя аналогично остальным кнопкам в программе. Окно кнопки должно быть создано с использованием оконного класса "knop" (подробности об оконных классах см. в описании функций CreateWindow и RegisterClass из WinAPI).

procedure AddKnop (
kn : TButInf; // описание добавляемой кнопки
);

Параметры
kn :
Описывает добавляемую кнопку. В описание входит изображение кнопки в различных состояниях, её хэндлер и реакция на нажатие кнопки.

Дополнение
Перед удалением кнопки необходимо удалить соответствующий элемент масива IPButtonList с помощью DelKnop.

При рисовании кнопки её состояние определяют параметры IPMouseWindow, IPDownWindow.

TButInf

Структура TButInf используется для описания кнопки, выполненной в стиле кнопок Кветки. Такие кнопки изменяют свой внешний вид при нажатии и наведении на них курсора мыши.

TButInf = record
wind : HWND; // хэндлер кнопки
pict : IPicture; // внешний вид кнопки в обычном состоянии
mpict : IPicture; // внешний вид кнопки при наведённом на неё курсоре мыши
dpict : IPicture; // внешний вид нажатой кнопки
clickproc : procedure; // процедура, которая должна выполняться при нажати на кнопку
end;

Поля
wind :
Хэндлер кнопки. Чтобы поведение кнопки было таким же, как и остальных кнопок Кветки, её окно должно быть созданно с помощью оконного класса "knop".

pict :
Внешний вид кнопки в обычном ненажатом состоянии.

mpict :
Внешний вид кнопки при наведённом на неё курсоре мыши.

dpict :
Внешний вид кнопки в нажатом состоянии.

clickproc :
процедура, которая должна выполняться при нажатии на кнопку.


CheckCombo

CheckCombo изменяет состояние группы из элементов Combobox. Все элементы, кроме текущего теряют пометку, если она у них была. Изменённые элементы автоматически перерисовываются. Эта процедура используется для того, чтобы только один элемент из группы ComboBox мог быть отмеченным.

procedure SozdCombo (
cbs : TComboGroup; // массив элементов ComboBox
wnd : HWND // хэндлер окна текущего элемента ComboBox
);

Параметры
cbs :
Массив элементов типа TCombo. В нём перечисляются все элементы из группы ComboBox.
TComboGroup = array of TCombo;

wnd :
Хэндлер текущего элемента ComboBox. Все элементы, кроме него, изменят своё состояние с отмеченного на обычное. Если среди элементов cbs нет ни одного с хэндлером wnd, неотмеченными станут все элементы.

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

CheckCombo не делает разницы между типом элемента управления. Она точно так же будет работать и для элементов CheckBox.

Пример работы с CheckCombo см. в описании SozdCombo.


CloseWnd

CloseWnd закрывает вспомогательное окно. При этом также удаляется соответствующий элемент массива IPAuxWindowList, описывающего все окна и пункт подменю "Вспомогательные окна".

procedure CloseWnd
wnd : HWND // хэндлер удаляемого окна
);

Параметры
wnd :
Хэндлер удаляемого окна. Если вспомогательного окна с таким хэндлером не обнаружено, то процедура ничего не делает.

Примечание. С помощью CloseWnd можно удалить даже стандартные вспомогательные окна Кветки, такие как "Журнал" или "Партии". Однако делать это настоятельно не рекомендуется, так как это приведёт к нестабильной работе программы.


DelKnop

DelKnop удаляет информацию о кнопке с хэндлером wnd из массива кнопок IPButtonList. При этом кнопка как окно не удаляется. То есть после выполнения DelKnop необходимо удалить саму кнопку с помощью DestroyWindow из WinAPI.

procedure DelKnop (
wnd : HWND; // хэндлер удаляемой кнопки
);

Параметры
wnd :
Хэндлер удаляемой кнопки. Если кнопки с таким хэндлером в списке IPButtonList нет, то ничего не произойдёт.


DopfProc

DopfProc - это функция обработки сообщений, используемая по умолчанию во вспомогательных окнах. Чтобы созданное в плагине окно было оформлено в том же стиле, что и остальные вспомогательные окна Кветки, надо все необрабатываемые сообщения передавать в DopfProc.

function DopfProc (
wind : HWND; // хэндлер окна, которому предназначено сообщение
msg : UINT; // тип сообщения
wpar : WPARAM; // старший параметр сообщения
lpar : LPARAM // младший параметр сообщения
): LRESULT; stdcall;

Параметры
wind :
Хэндлер окна, которому предназначено сообщение

msg :
Тип сообщения. Указывает, какое поступило сообщение.

wpar, lpar :
Старший и младший параметры собщения. Содержат дополнительную информацию о сообщении. Их содержимое зависит от значения msg.

Возвращаемое значение
Результат обработки сообщения. Зависит от значения msg.

Дополнение
Функция DopfProc активно использует массив IPAuxWindowList. Такм образом, эта функция должна использоваться только для окон, созданных с помощью SozDopWnd и ShowModal. В противном случае она передаст управление стандартной функции обработки сообщений DefWindowProcw из WinAPI.

Обрабатываемые сообщения:
Сообщение | Действие по умолчанию
WM_SHOWWINDOW | Подготавливает окно к работе: создаёт кнопку "X"; если окно модальное, то делает недоступными все остальные окна; если необходимо, добавляет пункт в подменю "Дополнительные окна". Важно передать DopfProc управление, когда окно показывается ( BOOL(wpar) = TRUE).
WM_ACTIVATE | Окрашивает рамку и кнопку в соответствующий цвет.
WM_NCHITTEST | Определяет, над какой частью окна расположен курсор мыши. Устанавливаются параметры IPWindowMoveType и IPMouseWindow. Первый необходим в случае растягивания окна мышью (само растягивание придётся реализовывать вручную). Второй используется для подсветки кнопок при наведении на них мыши.
WM_PAINT | Рисует рамку окна и передаёт управление процедуре draw.
WM_SIZE | Изменяет регион окна, положение кнопки"X".
WM_NCLBUTTONDOWN | Если курсор мыши расположен над заголовком (wpar = HTCAPTION), то инициализирует параметры IPIsWindowMoving (говорит, что сейчас перемещается окно), IPCurrentOffsetX, IPCurrentOffsetY (смещение курсора мыши относительно левого верхнего угла окна).
WM_MOUSEMOVE | Если перетаскивается окно (параметр IPIsWindowMoving равен true), то изменение его координат с учётом приклеиваний к границам окна и другим окнам.
WM_LBUTTONUP | Если перетаскивается окно (параметр IPIsWindowMoving равен true), то завершить перетаскивание (IPIsWindowMoving устанавливается в false).


DrawCapt

DrawCapt рисует рамку вспомогательного окна и пишет сверху его название.

procedure DrawCapt (
dc : HDC; // графический контекст окна
wnd : HWND; // хэндлер окна
m : boolean // активно ли окно
);

Параметры
dc :
Графический контекст окна. Именно на нём будет рисоваться рамка.

wnd :
Хэндлер вспомогательного окна, чья рамка сейчас рисуется.

m :
Указывает, активно ли окно (m = true). Если да, то рамка рисуется синей, если нет - серой.

Дополнение
Перегружая процедуру DrawCapt, можно изменять внешний вид вспомогательных окон. При этом могут потребоваться отступы сверху, снизу и слева и справа от границ окна до клиентской части (см. INUpSpace, INDownSpace, INLeftSpace, INRightSpace).


DrawDopFon

DrawDopFon рисует стандартный фон в клиентской области вспомогательного окна. В верхней и нижней части окна он имеет светло-серый цвет, который плавно переходит в белый к середине окна.

procedure DrawDopFon (
wnd : HWND; // хэндлер окна
dc : HDC // графический контекст окна
);

Параметры
wnd :
Хэндлер окна, фон которого будет перерисовываться.

dc :
Графический контекст окна.

Дополнение
Процедуру DrawDopFon можно использовать при рисовании вспомогательного окна, чтобы оно было оформлено в стиле других окон Кветки. По умолчанию фон у клиентской части окна не рисуется. С другой стороны, можно эту процедуру перегрузить. чтобы изменить внешний вид вспомогатльных окон. В этом случае изменится фон у окон "Информация о партии" и "Настройки позиции".


IfPaintX

IfPaintX рисует кнопку "X" вспомогательного окна. При этом она может выполняться как реакция на события WM_PAINT, так и сама по себе. Внешний вид кнопки зависит от того, актикно родительское окно или нет, а также от состояния самой кнопки (нажата ли она, проводится ли надо ней курсор мыши).

procedure IfPaintX (
wnd : HWND; // хэндлер кнопки "X"
m : boolean = true; // выполняется ли IfPaintX как реакция на WM_PAINT
act : boolean = true // активно ли родительское окно
);

Параметры
wnd :
Хэндлер кнопки "X", которая будет перерисовываться.

m :
Указывает, выполняется ли IfPaintX как реакция на WM_PAINT (m = true). В случае реакции на WM_PAINT рисовать необходимо в структуре PaintStruct, иначе достаточно получить хэндлер графического контекста с помощью GetDC.

act :
Указывает, активно ли родительское окно. Если да (act = true), то кнопка рисуется синей. В противном случае - серой.

Дополнение
Перегружая процедуру IfPaintX, можно изменять внешний вид кнопок "X" во вспомогательных окнах. При этом для получения информации о состоянии кнопки могут понадобиться параметры IPMouseWindow, IPDownWindow.


SetWndRgn

SetWndRgn устанавливает регион для вспомогательного окна в соостветствии с его новыми шириной и высотой.

procedure SetWndRgn (
wnd : HWND; // хэндлер вспомогательного окна
wid, hei : integer // новая ширина и высота окна
);

Параметры
wnd :
Хэндлер вспомогательного окна, для которого необходимо установить новый регион.

wid, hei :
Новая ширина и высота окна.

Дополнение
Перегружая процедуру SetWndRgn, можно изменять внешний вид вспомогательных окон. При этом могут потребоваться отступы сверху, снизу и слева и справа от границ окна до клиентской части (см. INUpSpace, INDownSpace, INLeftSpace, INRightSpace). Стандартная процедура создаёт окно, прямоугольное внизу и с округлыми углами сверху.


SetXKnop

SetXKnop перемещает кнопку "X" при изменении размеров родительского окна.

procedure SetXKnop (
wnd : HWND; // хэндлер кнопки "X"
wid : integer // новая ширина окна
);

Параметры
wnd :
Хэндлер кнопки "X", которая будет перемещаться.

wid :
Новая ширина окна. В соответствие с этой процедурой, положение кнопки "X" не зависит от высоты родительского окна.

Дополнения
Перегружая процедуру SetXKnop, можно изменять внешний вид вспомогательных окон. При этом могут потребоваться отступы сверху, снизу и слева и справа от границ окна до клиентской части (см. INUpSpace, INDownSpace, INLeftSpace, INRightSpace). Стандартная процедура перемещает кнопку "X" в верхний правый угол окна.

Для получения хэндлера кнопки "X" используется поле xbut у элементов списка IPAuxWindowList.


Showmodal

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

function ShowModal (
nm : PWideChar; // название диалога
lef, top : integer; // координаты верхнего левого угла окна
wid, hei : integer; // ширина и высота
owner : HWND; // хэндлер окна-владельца
proc : WindProc; // функция обработки сообщений окна
draw : DrawProc // процедура отрисовки клиентской части окна
): integer;

Параметры
nm :
Название диалога. Именно оно будет писаться в верхней части окна. В дальнейшем название можно будет поменять с помощью функции WinAPI SetWindowText.

lef, top :
Координаты верхнего левого угла диалога. Измеряются в пикселах.

wid, hei :
Ширина и высота создаваемого диалога.

owner :
Хэндлер окна-владельца (owner window). При удалении окна-владельца подчинённое окно удаляется автоматически. Оно также становится невидимым пр минимизации окна-владельца. Кроме того, подчинённое окно всегда располагается поверх своего окна владельца. Обычно этот параметр будет равен хэндлеру главного окна (см. IHMainWindow).

proc :
Указатель на процедуру обработки сообщений окна. Формат процедуры приведен здесь. Чтобы окно вело себя так же, как и любое другое вспомогательное окно Кветки, рекомендуется все необрабатываемые сообщения передавать процедуре DopfProc. Более подробно о реакции по умолчанию на сообщения для дополнительных окон см. в описании DopfProc.

draw :
Указатель на процедуру, рисующую клиентскую часть вспомогательного окна. Описание DrawProc см. в описании SozDopWnd. Именно этой процедуре будет передаваться управление при обработке сообщения WM_PAINT по умолчанию.

Возвращаемое значение
Результат работы модального окна. Это может быть любое число, не равное 9999. Задаётся при программировании работы диалога. Если диалог закрывается с помощью нажатия на кнопку "X", то возвращается -1.

дополнения
Для завершения работы модального диалога используетс параметр IPModalResult. Как только он будет изменён с 9999, модальное окно после обработки текущего сообщения будет закрыто, а значение IPModalResult будет возвращено функцией ShowModal.

Созданный с помощью ShowModal диалог не надо удалять вручную (см. CloseWnd). Он будет удалён автоматически.

(планируется изменить в следующих версиях) При создании окна регистрируется класс окна с именем, совпадающим с nm. Таким образом, для успешного создания окна необходимо, чтобы его название в Кветке должно быть уникальным.


SozdCombo

SozdCombo создаёт элемент управления типа CheckBox или Combobox.

procedure SozdCombo (
var cmb : TCombo; // описание созданного элемента
nx, ny : integer; // локальные координаты элемента
wnd : HWND // окно, на котором расположится элемент
);

Параметры
cmb :
Элемент типа TCombo, описывающий создаваемый элемент управления (Описание TCombo см. ниже). При передаче в процедуру в нём должны быть заполнены все поля, за исключением wnd - хэндлера элемента управления. Если элемент управления создан успешно, то процедура возвращает cmb с заполненным полем wnd. В противном случае, cmb.wnd = 0. Во время работы, элемент управления будет постоянно обращаться к cmb, поэтому эту переменную нельзя удалять до тех пор, пока не будет удалён элемент упраления.

nx, ny :
Локальные координаты элемента управления. Начало координат отсчитывается от левого верхнего угла родительского окна. Измеряются в пикселях.

wnd :
Хэндлер окна, на котором расположится элемент управления.

Дополнения
Работа с созданными элементами управления происходит автоматически. Они автоматически отображаются в указанном месте окна, изменяют своё состояние при нажатии на них левой клавиши мыши. Однако если по нажатию на элемент управления необходимо дополнительно проделать специфические действия, то используется процедура, записанная в поле cmb.onclick.

Состояние элемента управления и даже его тип можно в любой момент поменять вручную. Для этого надо поменять соответствующие поля переменной cmb и обновить элемент управления (например, с помощью функции RedrawWindow из WinAPI).

Ширина и высота элементов управления фиксирована и хранится в настройках: INCheckWidth, INCheckHeight для CheckBox и INComboWidth, INComboHeight для ComboBox.

Пример кода, создающего элемент управления
приведенный код создаст два CоmboBox, из которых отмечен может быть только один.

var cmbgroup : TComboGroup;

procedure AddCombo ();
begin
SetLength (cmbgroup , 2);// у нас будет два элемента
{Заполняем поля cmbgroup}
cmbgroup[0].state := check;
cmbgroup[0].onclick := comboclick;
cmbgroup[0].iscombo := 1;
cmbgroup[1].state := usual;
cmbgroup[1].onclick := comboclick;
cmbgroup[1].iscombo := 1;
{Создаём элементы в некотором созданном нами окне mywnd}
SozdCombo (cmbgroup[0], 10, 10, mywnd);
SozdCombo (cmbgroup[1], 10, 30, mywnd);
end;

procedure comboclick (wnd : HWND);
begin
CheckCombo (cmbgroup, wnd); //снимает пометку со всех элементов группы, кроме текущего
end;

TCombo

Структура TCombo используется для описания элемента управления типа CheckBox и ComboBox.

TCombo = record
wnd : HWND; // хэндлер окна элемента управления
state : TElemState; // состояние элемента управления
onclick : procedure (wnd:hwnd); // процедура, которая будет выполняться при нажати на элемент управления
iscombo : byte; // тип элемента управления
end;

Поля
wnd :
хэндлер окна элемента управления.

state :
Состояние элемента управления. Может принимать одно из следующих значений:

  • gray - элемент неактивен. Его состояние не может быть изменено с помощью мыши.
  • check - элемент отмечен. Если это CheckBox, то на нём рисуется галочка; если ComboBox, то чёрный кружок.
  • usual - элемент не отмечен.

    onclick :
    Процедура, которая будет выполняться по щелчку левой кнопки мыши по элементу управления. Если никаких специфических действий не требуется, то onclick должен быть равен nil. При этом менять состояние элемента в onclick не требуется: это будет происходить автоматически.

    iscombo :
    Тип элемента управления. Возможные типы: 0 - CheckBox; 1 - ComboBox.


SozDopWnd

SozDopWnd создаёт дополнительное окно, по стилю и поведению совпадающее со вспомогательными окнами Кветки. Фактически, кроме создания самого окна, добавляется новый элемент к массиву IPAuxWindowList, описывающему все вспомогатеьные окна.

function SozDopWnd (
nm : PWideChar; // название окна
lef, top : integer; // координаты верхнего левого угла окна
wid, hei : integer; // ширина и высота
owner : HWND; // хэндлер окна-владельца
mn : boolean; // нужно ли создать для окна пункт в подменю "Вспомогательные окна"
vis : boolean; // создать ли окно видимым
modal : boolean; // модальное окно или нет
proc : WindProc; // функция обработки сообщений окна
draw : DrawProc // процедура отрисовки клиентской части окна
): HWND;

Параметры
nm :
Название окна. Именно оно будет писаться в верхней части окна. В дальнейшем название можно будет поменять с помощью функции WinAPI SetWindowText.

lef, top :
Координаты верхнего левого угла окна. Измеряются в пикселах.

wid, hei :
Ширина и высота создаваемого окна.

owner :
Хэндлер окна-владельца (owner window). При удалении окна-владельца подчинённое окно удаляется автоматически. Оно также становится невидимым пр минимизации окна-владельца. Кроме того, подчинённое окно всегда располагается поверх своего окна владельца. Обычно этот параметр будет равен хэндлеру главного окна (см. IHMainWindow).

mn :
Указывает, нужно ли для окна создать пункт в подменю "Вспомогательные окна". Чтобы пункт был создан, mn должен быть равен true.

vis :
Будет ли создаваемое окно автоматически видимым. Если vis = true, то сразу после создания дополнительное окно появится на экране. Если vis = false, то оно будет невидимым.

modal :
Будет ли создаваться модальное окно. При modal = true окно будет модальным. Если окно модальное, то как только оно становится видимым, все остальные окна программы теряют возможность стать активными, пока модальное окно не будет закрыто. В большинстве случаев для создания модального окна удобнее пользоваться функцией ShowModal.

proc :
Указатель на процедуру обработки сообщений окна. Формат процедуры приведен здесь. Чтобы окно вело себя так же, как и любое другое вспомогательное окно Кветки, рекомендуется все необрабатываемые сообщения передавать процедуре DopfProc. Более подробно о реакции по умолчанию на сообщения для дополнительных окон см. в описании DopfProc.

draw :
Указатель на процедуру, рисующую клиентскую часть вспомогательного окна. Описание DrawProc см. ниже. Именно этой процедуре будет передаваться управление при обработке сообщения WM_PAINT по умолчанию.

Возвращаемое значение
Хэндлер созданного окна. Если окно создано не было, возвращается 0.

Примечание. (планируется изменить в следующих версиях)
При создании окна регистрируется класс окна с именем, совпадающим с nm. Таким образом, для успешного создания окна необходимо, чтобы его название в Кветке должно быть уникальным.

Что будет работать по умолчанию во вспомогательном окне:

  • Отрисовка рамки окна, отрисовка кнопки "X";
  • Перетаскивание окна с помощью мыши;
  • По нажатию на "X" окно становится невидимым;
  • Изменение внешнего вида в зависимости от того, активно окно или нет;
  • Приклеивание окна к границам экрана и другим окнам Кветки;
  • Перемещение между окнами с помощью Tab;
  • Показать / спрятать окно по нажатию на соответствующий пункт меню.

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

Пример кода процедуры обработки сообщений вспомогательного окна
function WndProc (wind : HWND; msg : UINT; wpar : WPARAM; lpar : LPARAM) : LRESULT; stdcall; export;
begin
case msg of
----------------------------------------------
// Обработка сообщений
----------------------------------------------
else
result := DopfProc(wind, msg, wpar, lpar );
end;
end;

DrawProc

Процедура типа DrawProc получает управление при получении вспомогательным окном Кветки сообщения WM_PAINT.

DrawProc = procedure (
wnd : HWND; // хэндлер окна
dc : HDC // хэндлер графического контекста окна
);

Параметры
wnd :
Хэндлер окна, которое будет отрисовываться

dc :
Хэндлер графического контекста, в котором будет происходить рисование.


WriteonBut

WriteonBut рисует на поверхности кнопки текст. Таким обазом можно создавать кнопки с нарисованным текстом на них.

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

procedure WriteonBut (
dc : HDC; // графический контекст, на котором в итоге будет нарисована кнопка
butdc : HDC; // графический контекст для внутренней отрисовки кнопки
pict : IPicture; // изображение, используемое как внешний вид кнопки до нанесения надписи
rct : TRect; // прямоугольник в dc, в котором располагается кнопка
wid, hei : integer; // ширина и высота изображения pict
up : boolean; // нажата ли кнопка
txt : PWideChar // наносимый на кнопку текст
);

Параметры
dc :
Графический контекст окна, на котором в итоге будет нарисована кнопка. Некоторые регионы изображения pict могут быть прозрачными. dc используется для того, чтобы фон под ними отрисовывался из окна. В противном случае он был бы чёрным.

butdc :
Графический контекст, на котором в итоге будет отрисована кнопка с текстом. Процедура нарисует кнопку именно на нём, а не на dc. Для отрисовки кнопки на окне необходимо затем вручную скопировать содержимое butdc в окно, например, с помощью функции BitBlt из WinAPI.

pict :
изображение, используемое как внешний вид кнопки до нанесения надписи. Может быть получено из массива IPButtonList. В зависимости от состояния кнопки следует брать изображение pict, mpict или dpict.

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

wid, hei :
Ширина и высота изображения pict.

up :
Указывает, в нажатом ли состоянии кнопка. В нажатом состоянии (up = true) текст отображается на один пиксель ниже и правее.

txt :
Наносимый на кнопку текст.


Процедуры для работы с окнами "Журнал" и "Партии"

процедура | идентификатор (для GetFunc)
PSetTek | IFSelectGame
AddPar | IFAddGame
DelPar | IFDeleteGame
ParChange | IFGameChanged
DeletParties | IFDeleteGames
SortPrs | IFSortGames
PDraw | IFDrawGamesWindow
ZhDraw | IFDrawMovesWindow
UpdWindows | IFUpdateWIndows


AddPar

AddPar создаёт новую партию и добавляет её к списку партий. Именно эта процедура выполняется при нажатии на пункт "Добавить партию" в меню окна "Партии".

procedure AddPar ( );

Дополнение
Перегружая эту функцию, можно изменять реакцию на выбор пункта меню "Добавить партию".


DeletParties

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

function DeletParties (
pars : TGames // массив партий, предназначенный к удалению
) : boolean;

Параметры
pars :
Массив партий, которые будут удалены. Для получения списка загруженных в Кветку партий используется параметр IPGames. См. описание типа TGames.

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

Дополнения
Если в список партий были внесены изменения, то перед его удалением появляется диалог, требующий подтвердить удаление партий. Если пользователь передумал, то список не удаляется, а функция возвращает false.

Если программа находится в состоянии расстановки фигур, то она переводится в обычное состояние.

Функция DeletParties не обновляет и не подготавливает окна Кветки к удалению партий. Она также не создаёт нового списка партий. Поэтому при самостоятельном использовании этой функции все действия необходимо будет проделывать вручную (см. процедуры UpdWindows, PDraw, NewMov и AddPar).


 DelPar

DelPar

DelPar удалёет текущую партию из списка партий. Именно эта процедура выполняется при нажатии на пункт "Удалить партию" в меню окна "Партии".

procedure DelPar ( );

Дополнения
Перед удалением партии появляется диалог требующий подтверждение удаления. Если в списке всего одна партия, то после её удаления автоматически создаётся новая.

Перегружая функцию DelPar, можно изменять реакцию на выбор пункта меню "Удалить партию".


ParChange

ParChange Производит действия, указывающие, что пользователь внёс изменения в список партий. Дополнительно меняется текст в заголовке окна "Партии".

procedure ParChange (
pst : PWideChar = nil // текст, который необходимо добавить к заголовку окна "Партии"
);

Параметры
pst :
Строка, содержащая текст, который необходимо добавить к заголовку окна "Партии". После выполнения процедуры этот заголовок будет выглядеть так: "* Партии <pst>". Если pst=nil, то текст добавлен не будет.


PDraw

PDraw рисует клиентскую часть окна "Партии".

procedure PDraw (
dc : HDC // хэндлер графического контекста окна "Партии"
);

Параметры
dc :
Хэндлер графического контекста, на котором следует отрисовать окно.

Дополнение
Перегружая процедуру PDraw можно изменять внешний вид окна "Партии". При этом могут понадобиться параметры: отступы сверху, снизу, слева и справа от границ окна до клиентской области (INUpSpace, INDownSpace, INLeftSpace, INRightSpace); цвет строки с текущей партией (INHighlightBKColor); шрифт текста и шапки таблицы (INTextFont, INTopFont), массив из ширин столбцов таблицы (IPGamesColumnWidhs), список партий (IPGames).


PSetTek

PSetTek устанавливает текущую партию из списка партий. При этом производятся все необходимые сопутствующие действия: прекращается работа с текущей партией (расстановка фигур, анализ движком очередного хода), устанавливается начальная позиция новой партии, обновляется содержимое главного окна и окон "Журнал", "Партии". Внкутри PSetTek также вызывается процедура NewMov, чтобы подготовить движок к новой позиции.

procedure PSetTek (
tk : integer // номер партии
);

Параметры
tk :
Порядковый номер партии, которая должна стать текущей. Отсчёт партий начинается с нуля: 0 - самая верхняя партия в списке, 1 - следующая за ней снизу и т.д. Если значение tk указывает на несуществующую партию или совпадает с номером текущей партии, то процедура ничего не делает.

Примечания
Параметр tk не связан с номером, отображаемым в графе N партии. Если партии отсортированы, то эти номера могут кардинально различаться.

Процедуру PSetTek можно перегрузить. Однако внутри неё изменяются некоторые внутренние параметры, не доступные плагинам. Поэтому полностью заменять PSetTek на свою собственную процедуру не рекомендуется.


SortPrs

SortPrs сортирует список загруженных в Кветку партий по одному из столбцов, из окна "Партии". Сам список IPGames при этом не меняется, меняется только расположение партий в окне "Партии".

procedure SortPrs (
n : integer // номер столбца, по которому проводится сортировка
);

Параметры
n :
Номер столбца, по которому проводится сортировка. Нумерация начинается с -1.

  • n = -1 означает, что сортировка идёт по столбцу "N" окна "Партии". То есть, партии будут расположены в порядке следования их в pgn-файле.
  • n = 0..7 означает, что сортировка идёт по остальным столбцам. Столбцы нумеруются в соответствии с нумерацией семи обязательных тегов (отличается от порядка следования столбцов в окне "Партии").
    Остальные значения n игнорируются.

    Примечание
    Процедура SortPrs не обновляет окно "Партии". Поэтому при самостоятельном использовании процедуры необходимо будет это проделать вручную (см. процедуру PDraw).


UpdWindows

UpdWindows перерисовывает доску и окно "Журнал" при изменении позиции или всей партии, а также готовит движок к анализу новой позиции. Многие функции, например, большинство из этого списка, изменяют только внутреннюю структуру журнала, и позиции, но не обновляют при этом окна (это сделано с целью повышения быстродействия программы). Чтобы привести все компоненты Кветки в соответствие с этими изменениями, и используется процедура UpdWindows.

procedure UpdWindows (
bch : boolean; // изменилась ли позиция
jch : boolean; // изменился ли журнал ходов
iszhtx : boolean = true // надо ли запомнить горизонтальное положение курсора в окне "Журнал"
);

Параметры
bch :
Указывает, изменилась ли позиция. Если да (bch = true), то, во-первых, о новой позиции сообщается движку (с помощью NewMov), и во-вторых, перерисовывается доска с новой позицией (с помощью DrawDoska и BitBlt из WinAPI).

jch :
Указывает, изменился ли журнал ходов. Это, например, может произойти после сделанного на доске хода или после добавления комментария. Если да (jch = true), то производятся действия, указывающие, что пользователь внёс изменения в партию (с помощью ParChange) и перерисовывается окно "Журнал".

ifzhtx :
Указывает, надо ли запомнить горизонтальное положение курсора в окне "Журнал". Этот параметр используется для того, чтобы при перемещении курсора вверх-вниз по окну "Журнал" он придерживался одной вертикали. ifzhtx = true означает, что информацию о горизонтальном положении курсора следует обнулить. ifzhtx = false должно использоваться при обработке нажатий на клавиши "стрелка вниз" (kdclick), "стрелка вверх" (kuclick), PgUp (kpuclick), PgDown (kpdclick).


ZhDraw

ZhDraw рисует клиентскую часть окна "Журнал".

procedure ZhDraw (
wnd : HWND; // хэндлер окна , где будет происходить рисование
dc : HDC // хэндлер графического контекста окна
);

Параметры
wnd :
Хэндлер окна, в котором будет рисоваться журнал. Обычно это хэндлер окна "Журнал".

dc :
Хэндлер графического контекста, на котором будет рисоваться журнал.

Дополнение
Перегружая процедуру ZhDraw можно изменять внешний вид окна "Журнал". Однако на данный момент (Кветка 2.3) это перегрузка этой процедуры затруднена тем, что плагин не имеет непосредственного доступа к внутренней структуре списка ходов партии.


Процедуры для работы с движком

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

Список процедур для работы со вспомогательными окнами
процедура | идентификатор (для GetFunc)
NewMov | IFNewMoveNotify
DobText** | IFEngineCommand
ReadvOutput** | IFReadEngineOutput
AnalysInfo** | IFReadEngineInfo
ShowVariants** | IFShowEngineVariants
ShowVariant** | IFShowOneEngineVariant

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


AnalysInfo

AnalysInfo анализирует параметры сообщения "info", переданного движком. В этом сообщении движок передаёт информацию о рекомендуемых ходах и их рейтингах, возможных продолжениях, затраченном на анализ времени, глубине анализа и т.п. Подробнее см. описание формата UCI.

procedure AnalysInfo (
const tst : string // строка, содержащая сообщение "info" со всеми параметрами
);

Параметры
tst :
Строка, содержащая сообщение "info" со всеми её параметрами. Грантируется, что tst содержит только это сообщение (строка начинается с "info" и заканчивается следующим переводом строки).

Дополнение
Перегружая процедуру AnalysInfo можно изменять или дополнять реакцию программы на вывод движка. При этом могут понадобиться параметры: рекомендуемый следующий ход и его рейтинг IPNextMove, IPPositionRating и список рекомендуемых ходов, их рейтингов и наиболее вероятных продолжений IPMultRatings, IPMultNextMoves, IPMultPossibleContinues.

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


DobText

DobText подаёт команды на ввод движка. Дополнительно отображает поданные команды в поле "Вывод движка" окна "Движок".

procedure DobText (
const st : string // подаваемые команды
);

Параметры
st :
Строка, содержащая команды для движка. Команды Принимаются команды формата UCI. Однако при желании с помощью плагинов можно добавить поддержку и других форматов. Для корректной работы движка каждая команда должна заканчиваться символами #13#10, соответствующих нажатию на ввод.

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


NewMov

NewMov производит наобходимые действия, указывающие движку, что сделан новый ход. При этом очищаются значения параметров IPPositionRating, IPNextMove, IPMultPossibleContinues, очищается вывод "Варианты ходов" окна "Движок" и изменяет состояние движка с целью сообщить ему о новом ходе.

procedure NewMov ( );

Примечание
Процедура NewMov будет работать не только при добавлении нового хода. Она работает при любом изменении позиции.


ReadvOutput

ReadvOutput получает на вход вывод движка и анализирует его. Эта функция выполняется только в случае, если движок находится в состоянии анализа позиции.

procedure ReadvOutput (
const s : string // вывод движка
);

Параметры
s :
Строка, содержащая вывод движка. s может содержать одну или несколько строк вывода движка. Гарантируется, что все строки в s содержатся целиком с переводом строки на конце.

Дополнения
Перегружая процедуру ReadvOutput можно изменять или дополнять реакцию программы на вывод движка. При этом могут понадобиться параметры: рекомендуемый следующий ход и его рейтинг IPNextMove, IPPositionRating и список рекомендуемых ходов, их рейтингов и наиболее вероятных продолжений IPMultRatings, IPMultNextMoves, IPMultPossibleContinues.

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

ReadvOutput вызывает другую процедуру: AnalysInfo. Это происходит, когда в строке s обнаруживается сообщение info.


ShowVariant

ShowVariant формирует вывод движка для отдельного предлагаемого хода. Дополнительно изменяет параметр IPNextMove из формата UCI в формат, используемый в короткой шахматной нотации.

function ShowVariant (
q : integer // номер варианта
) : PWideChar;

Параметры
q :
Номер варианта хода, для которого формируется вывод. Варианты нумеруются, начиная с единицы. Если q превышает число выводимых вариантов (см. INMoveNumber) или не превосходит 1, то будет возвращена строка "Ход №<q> : ". Если q = 1, то дополнительно изменяется значение рекомендуемого следующего хода (см. IPNextMove) из нотации UCI в короткую шахматную нотацию.

Возвращаемое значение
Строка, содержащая вывод движка для q-го педлагаемого хода.

Дополнение
Перегружая процедуру ShowVariant можно изменять вывод в поле "Варианты ходов" окна "Движок". При этом могут понадобиться такие параметры, как число выводимых вариантов (см. INMoveNumber), рекомендуемый следующий ход, его рейтинг (см. IPNextMove, IPPositionRating), список предлагаемых ходов, их рейтинги и список возможных продолжений (см. IPMultNextMoves, IPMultRatings, IPMultPossibleContinues), максимальное число вариантов ходов, поддерживаемое движком (см. IPMaxMovesNumber).

На данный момент Кветка поддерживает не более десяти возможных вариантов ходов. И эту границу нельзя увеличить, используя стандартные параметры IPMultNextMoves, IPMultRatings, IPMultPossibleContinues, так как они - статические масивы.

Хотя процедура ShowVariant может выполняться как в основном потоке, так и в потоке движка, помещать отдельные её фрагменты кода в критическую секцию нет необходимости. Функция ShowVariant уже сама по себе находится в критической секции, объявленной в процедуре ShowVariants.


ShowVariants

ShowVariants выводит варианты ходов в окне "Движок". Вывод для каждого отдельного варианта формируется в функции ShowVariant и между выводами для разных вариантов добавляется разделитель "#13#10'--...--'#13#10.

procedure ShowVariants ( );

Дополнения
Перегружая процедуру ShowVariants можно изменять вывод в поле "Варианты ходов" окна "Движок". При этом может понадобиться число выводимых вариантов (см. INMoveNumber) и другие парамтеры, используемые в ShowVariant.

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


Процедуры управления партией

Все указанные здесь процедуры и функции работают с внутренней структурой позиции или партии (добавить или удалить ходы, процерить соответствие хода шахматным правилам, переместиться в партии на другую позицию и т.п.). Это позволяет быстро производить манипуляции с партией, однако в конце необходимо обновить внешний вид Кветки и подготовить движок. Для этих целей используется UpdWindows.
Примечание: все эти процедуры нельзя перегрузить с помощью SetProc.

процедура | идентификатор (для GetFunc)
AddMove | IFAddMove
Move | IFMove
BackMove | IFBackMove
GetMove | IFGetMove
TekMove | IFGetCurrentMove
DeltoTek | IFDeltoCurrent
CanMove | IFCanMove
Moveto | IFMoveTo
GetJurParent | IFGetParent
NumSteps | IfGetNumSteps
TekNum | IFCurrentNumber
NumNextHod | IFNextMoveNumber
SetComment | IFSetComment
FillHod | IFFillMove


AddMove

AddMove добавляет новый ход в партию. Ход может быть как продолжением основной ветки, так и началом ответвления.

function AddMove (
nx, ny : byte; // координата клетки, с которой ходит фигура
kx, ky : byte; // координата клетки, куда ходит фигура
dfig : TFigur; // дополнительная фигура
newvetka : boolean = false; // если такой ход в партии уже есть, нужно ли всё равно создать новую ветку
ng : byte = 0; // метка хода
) : interger;

Параметры
nx, ny :
Координаты клетки, с которой ходит фигура. Нумеруются числами от 1 до 8. Если nx или ny выходят за эти пределы, то раздаётся звуковой сигнал и функция прекращает работу.

kx, ky :
Координаты клетки, на которую ходит фигура. Нумеруются числами от 1 до 8. Если kx или ky выходят за эти пределы, то раздаётся звуковой сигнал и функция прекращает работу.

dfig :
дополнительная фигура. Подробнее см. описание TFigur. Если пешка дошла до конца доски и превращается в другую фигуру, то dfig описывает эту фигуру. В противном случае dfig должна быть равна empty.

newvetka :
Если newvetka = true, то новое ответвление создастся в любом случае, даже если предлагаемый ход уже имеется в партии. Если же ход встречается в партии и newvetka = false, то AddMove просто вернёт номер ответвтления, в котором был сделан указанный ход.

ng :
метка к ходу ("!", "?" и т.п.). Соответствует номеру NAG из стандарта PGN. Чаще всего используются следующие метки:
Номер | Описание
0 | Пустая метка
1 | Хороший ход ("!")
2 | Слабый ход ("?")
3 | Очень хороший ход ("!!")
4 | Очень слабый ход ("??")
5 | Интересный ход ("!?")
6 | Рискованный ход ("?!")

Полный список см. в описании стандарта PGN.

Возвращаемое значение
Если функция успешно сработала, то возвращается номер ответвления, куда добавлен ход. То есть, 0 означает, что ход добавлен в основную ветку. Положительное число n - что ход добавлен в n-ое ответвление. Если же ход добавлен не был (например, если он не соответствует шахматным правилам), то результат не определён планируется изменить в следующих версиях.

Дополнения
Так как по работе AddMove нельзя узнать, возможен ли данный ход или нет, это необходимо проверить заранее с помощью CanMove.

AddMove добавляет в партию ход, но не перемещает на него позицию. Чтобы переместить позицию, используется процедура Move.

AddMove работает следующим образом. Сначала проверяется, действительно ли возможен предлагаемый ход с текущей позиции. Если да и newvetka = false, то перебираются все продолжения из текущей позиции в данной партии. Если у одного из них следующий ход совпадает с предлагаемым, то возвращается номер соответствующего ответвления, и функция прекращает работу. В противном случае создаётся либо продолжение основной ветки (если такового ущё нет), либо новое ответвление; в него записывается добавляемый ход, и возвращается номер созданного ответвления.

AddMove изменяет только внутреннюю структуру партии. Чтобы отразить сделанные изменения в Кветке, используется процедура UpdWindows.


BackMove

BackMove перемещает позицию на один ход назад.

procedure BackMove ( );

Дополнение
BackMove изменяет только внутреннее состояние партии. Чтобы отразить сделанные изменения в Кветке, используется процедура UpdWindows.


CanMove

CanMove проверяет, соответствует ли предлагаемый ход шахматным правилам. Предполагается, что ход делается из текущей позиции.

function CanMove
nx, ny : byte; // координаты, с которой ходит фигура
kx, ky : byte; // координаты, куда ходит фигура
): boolean;

Параметры
nx, ny :
Координаты клетки, с которой ходит фигура. Нумеруются числами от 1 до 8. Если nx или ny выходят за эти пределы, то функция возвращает false.

kx, ky :
Координаты клетки, на которую ходит фигура. Нумеруются числами от 1 до 8. Если kx или ky выходят за эти пределы, то функция возвращает false.

Возвращаемое значение
Если фигура, стоящая на клетке с координатами nx, ny, может походить в клетку с координатами kx, ky, то возвращается true. Во всех остальных случаях возвращается false. Если функции переданы некорректные параметры (на клетке с координатами nx, ny ничего не стоит, или какая-то из координат выходит за пределы от 1 до 8), то CanMove также возвращает false.


DeltoTek

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

procedure DeltoTek ( );

Дополнение
DeltoTek изменяет только внутреннее состояние партии. Чтобы отразить сделанные изменения в Кветке, используется процедура UpdWindows.


FillHod

FillHod восстанавливает ход, если это возможно, по неполной информации о нём. Импользуется, например, для получения полной информации о ходе по его сокращённой шахматной записи.

function FillHod
fig: TFigur; // передвигаемая фигура
var dfig: TFigur; // дополнительная фигура
var nx, ny: byte; // координаты клетки, с которой ходит фигура
kx, ky: byte // координаты клетки, на которую ходит фигура
) : byte;

Параметры
fig:
Перемещающаяся во время хода фигура. См. описание TFigur. Если fig = empty, то функция возвращает 7 и прекращает работу.

dfig:
Дополнительная фигура. Если пешка дошла до конца доски и превращается в другую фигуру, то dfig описывает эту фигуру. В противном случае dfig игнорируется. На выходе dfig может измениться, если произошло взятие на проходе. В этом случае dfig станет описывать взятую пешку. См. описание TFigur. Если при продвижении пешки dfig = empty, то функция возвращает 8 и прекращает работу.

nx, ny :
Координаты клетки, с которой походила фигура. Изменяются от 1 до 8. Если nx = 0 или ny = 0, то считается, что соответствующая координата неизвестна. В этом случае после успешной работы функции в nx, ny будут записаны начальные координаты перемещаемой фигуры. При любом другом значении, вероятнее всего, программа аварийно завершит работу.

kx, ky :
Координаты клетки, на которую походила фигура. Изменяются от 1 до 8. При любом другом значении функция выдаст результат 5 (такой ход невозможен).

Возвращаемое значение
Результат восстановления хода. Принимает одно из следующих значений:
значение | описание
0 | Обычный ход
1 | Ход приводит к шаху
2 | Ход приводит к мату
3 | Ход приводит к пату
5 | Нет ни одного хода, удовлетворяющего заданным условиям
6 | Ходов с заданными условиями несколько. При этом в параметрах возвращается описание одного из них.
7 | Некорректные параметры: указана пустая фигура
8 | Некорректные параметры: не указано, в какую фигуру превращается пешка, пройдя до границ доски.
255 | На доске нет короля.


GetJurParent

GetJurParent возвращает указатель на ветку парти, находящуюся на уровень выше.

function GetJurParent : pointer;

возвращаемое значение
Если текущая позиция находится внутри ответвления, то возвращается указатель на ветку, находящуюся на один уровень выше. Если текущая позиция находится в основной ветке, то возвращается nil. Структура ответвления содержит список ходов и некоторую другую информацию. На данный момент (Кветка v 2.3) внутренняя структура ответвления не устоялась, поэтому читать или модифицировать её настоятельно не рекомендуется.


GetMove

GetMove Возвращает информацию о ходе по его номеру.

function GetMove
t: integer // номер запрашиваемого хода.
) : TMove;

Параметры
t :
Номер запрашиваемого хода. Нумерация начинается с нуля. Например, для ходов
1. e4 e5 2. Nc3 Nc6
t = 0 выдаст информацию о 1. e4; t = 1 - о 1... e5 и т.д. В ответвлении нумерация ходов начинается с первого хода ответвления.

Возврщаемое значение
Переменная типа TMove, содержащая информацию об искомом ходе. Она включает в себя начальные и конечные координаты похолдившей фигуры, саму фигуру, комментарий и т.п. Подробнее о типе TMove см. ниже . Если t указывает на несуществующий ход, то поле fig результата присваивается значение empty.

Примечание
С помощью GetMove можно получить доступ только к последовательности ходов текущего ответвления. Для доступа к ходам, находящимся в ответвлении на уровень ниже или на уровень выше, необходимо сначала переместить туда текущую позицию. Для перехода к ходам, находящимся на уровень выше, можно воспользоваться следующими строками:
MoveTo (0); // Перемещаемся в начало ветки
BackMove; // Выходим из ветки
Для перехода к ходам из n-го ответвления для хода с номером m можно воспользоваться строками:
MoveTo (m); // Перемещаем позицию перед ходом с номером m
Move (n + 1); // Заходим в ответвление с номером n

TMove

Структура TMove используется для описания отдельного хода в партии.

TMove = record
fig : TFigur; // двигающаяся фигура
nx, ny : byte; // координаты клетки, с которой походила фигура
kx, ky : byte; // координаты клетки, на которую походила фигура
inf : TFigur; // дополнительная фигура
bylo : TFigur; // какая фигура стояла на клетке kx, ky
flag : byte; // флаги, описывающие, передвинулась лт одна из ключевых фигур, влияющих на возможность рокировки
st : string; // запись хода
comnt : string; // комментарий
nag : byte; // метка, дающая оценку хода или позиции
alts : array of pointer; // указатели на альтернативы данному ходу.
end;

Поля
fig :
Перемещающаяся во время хода фигура. См. описание TFigur.

nx, ny :
Координаты клетки, с которой походила фигура. Изменяются от 1 до 8.

kx, ky :
Координаты клетки, на которую походила фигура. Изменяются от 1 до 8.

inf :
Дополнительная фигура, если такая присутствует во время хода. Если пешка дошла до конца строки и превращается в другую фигуру, то inf описывает эту фигуру. Если произошло взятие на проходе, то inf описывает взятую пешку. В противном случае inf = empty. См. описание TFigur.

bylo :
Фигура, которая стояла на клетке с кординатами kx, ky до того как туда пошла фигура fig. Если клетка была пустой, то bylo = empty. См. описание TFigur.

st :
Строка, содержащая запись хода. Именно в таком виде ход записывается в окне "Журнал". Для записи хода используется сокращённая шахматная нотация. Изменение этого параметра в плагине вручную может привести к трудноопределяемым ошибкам.

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

nag :
Метка, дающая оценку ходу или позиции. ("!", "?" и т.п.) Соответствует номеру NAG из стандарта PGN. Для списка наиболее употребительных меток см. параметр ng функции AddMove или описание формата PGN.

alts :
Массив ходов, представляющих альтернативу данному ходу. Каждый из элементов alts начинает в партии новое ответвление. На данный момент (Кветка v 2.3) структура элементов alts не устоялась, поэтому читать или модифицировать её настоятельно не рекомендуется. Нумерация элементов этого массива используется в таких функциях, как AddMove и Move. Так, если текущим является ход, предыдущий данному, то в результате работы AddMove будет добавлен новый элемент alts и его номер (если нумеровать их с единицы) будет возвращён в качестве результата. Если же с предыдущего хода выполнить Move (n), то текущим станет ход alts [n - 1] при n > 0 и данный ход при n = 0.


Move

Move перемещает позицию на один ход вперёд. Ход может быть как в основной ветке, так и в ответвлении.

procedure Move (
n : integer // номер ответвления
);

Параметры
n:
Номер ответвления, на которое переместится позиция. Если n = 0, то ход будет сделан из основной ветки. Если n указывает на несуществующее ответвление, то процедура ничего не делает. Если в качетсве n указать результат выполнения AddMove, то позиция переместится на только что сделанный ход.

Дополнение
Move изменяет только внутреннее состояние партии. Чтобы отразить сделанные изменения в Кветке, используется процедура UpdWindows.


Moveto

Moveto перемещает позицию на ход с заданным номером.

procedure Moveto (
n : integer // номер хода
);

Параметры
n:
Номер хода, перед которым следует переместить позицию. Нумерация начинается с нуля. Например, для ходов
1. e4 e5 2. Nc3 Nc6
t = 0 переместит позицию в исходое состояние; t = 1 - в состояние после хода 1. e4 и т.д. В ответвлении нумерация ходов начинается с первого хода ответвления.

Дополнения
С помощью Moveto можно перемещать позицию только в пределах текущего ответвления. Для перехода к ходам, находящимся на уровень выше, можно воспользоваться следующими строками:
MoveTo (0); // Перемещаемся в начало ветки
BackMove; // Выходим из ветки
Для перехода к ходам из n-го ответвления для хода с номером m можно воспользоваться строками:
MoveTo (m); // Перемещаем позицию перед ходом с номером m
Move (n + 1); // Заходим в ответвление с номером n

Moveto изменяет только внутреннее состояние партии. Чтобы отразить сделанные изменения в Кветке, используется процедура UpdWindows.


NumNextHod

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

function NumNextHod : integer;

Возвращаемое значение
Номер следующего хода, как он будет записан в записи шахматной партии. Например, для ходов
1. e4 e5 2. Nc3 Nc6
если позиция получена после хода 1. e4, то NumNextHod = 1; если после хода 1... e5, то NumNextHod = 2. Номер корректно вычисляется как в основной ветке, так и в ответвлениях.


NumSteps

NumSteps Возвращает число полуходов в текущем ответвлении. При этом ходы из ответвлений более низкого или более высокого уровня не учитываются.

function NumSteps : integer;

Возвращаемое значение
Число полуходов в текущем ответвлении. При этом ходы из ответвлений более низкого или более высокого уровня не учитываются.


SetComment

SetComment устанавливает комментарий для текущего хода (приведшего к текущей позиции).

procedure SetComment
st: PChar // текст комментария
);

Параметры
st:
Указатель на текст добавляемого комментария. Согласно формату PGN, комментарий должен начинаться с открывающей фигурной скобки "{" и заканчиваться закрывающей фигурной скобкой "}". Кроме как в кнце комментария, закрывающие скобки должны отсутствовать в комментарии. Невыполнение этих условий может привести к тому, что сохранённая в pgn файл партия впоследствии не откроется.


TekMove

TekMove возвращает информацию о текущем ходе. Текущим является ход, который привёл к текущей позиции (она отображается на доске).

function TekMove ( ) : TMove;

Возвращаемое значение
Переменная типа TMove, описывающая текущий ход. Если текущей является начальная позиция, то в поле fig результата записывается empty.

Примечание

Возможен случай, когда активным всё ещё является ответвление, но ходов в нём не сделано ни одного (например, после выполнения Moveto (0) ). В этом случае TekMove не возвратит информацию о последнем сделанном ходе (он располагается на ветке уровнем выше). Вместо этого в empty.fig будет фозвращено empty. Чтобы получить информацию о ходе, надо перейти на ветку вверх, например, с помощью BackMove.


TekNum

TekNum возвращает номер текущего хода (то есть хода, приведщего к текущей позиции).

function TekNum : integer;

Возвращаемое значение
Номер текущего хода Нумерация начинается с нуля. Например, для ходов
1. e4 e5 2. Nc3 Nc6
TekNum = 0 означает, что позиция в партии исходная (до хода 1. e4; TekNum = 1 - позиция после хода 1. e4 и т.д. В ответвлении нумерация ходов начинается с первого хода ответвления.

Примечание
Функция TekNum возвращает номер хода только внутри текущего ответвления. Для получения номера хода во всей партии используется функция NumNextHod.


Список доступных настроек

Здесь приведены все настройки, доступ к которым можно получить через GetOptions.
    Выберите категорию:
  • Общие настройки и настройки главного окна
  • Настройки дополнительных окон
  • Настройки окна "Журнал"
  • Настройки окна "Партии"
  • Настройки доски
  • Настройки движка


Общие настройки и настройки главного окна

Идентификатор (используется в GetOptions) | Тип | Описание | Значение по умолчанию
INMaxLastFilesNum | ^integer | Максимальное число сохраняемых последних pgn файлов. Именно столько файлов будет выведено в главном меню | 5
INMaxFileNameLength | ^integer | Максимальная длина строки с именем pgn файла. Если полное имя файла вместе с полным путём до него окажется больше этой настройки, то в Кветке его невозможно будет открыть. | 300
INMainUpSpace | ^integer | Отступ сверху от доски до границы главного окна | 56
INMainDownSpace | ^integer | Отступ снизу от доски до границы главного окна | 64
INMainHorzSpace | ^integer | Отступ слева и справа от доски до границы главного окна | 21
INMainButtonSpace | ^integer | Ширина верхней части окна, выделенной под кнопки | 130
INWindowFont | ^LOGFONT | Шрифт надпсей на окнах (все подписи в клиентскй части окна) | Ms Sans Serif, 11pt
INTextFont | ^LOGFONT | Шрифт для текста в окнах "Журнал" и "Партии" | Verdana, 9 pt
INTopFont | ^LOGFONT | Шрифт для шапки окон "Журнал", "Партии" | Verdana, 9 pt, bold
INCaptionFont | ^LOGFONT | Шрифт заголовков окон | Verdana, 10pt, bold
INButtonFont | ^LOGFONT | Шрифт надписей на кнопках | Verdana, 19pt


Настройки дополнительных окон

Все приведенные здесь настройки касаются только дополнительных окон, выполненных в стиле Кветки.

Идентификатор (используется в GetOptions) | Тип | Описание | Значение по умолчанию
INUpSpace | ^integer | Отступ сверху от границы окна до клиентской области | 25
INDownSpace | ^integer | Отступ снизу от границы окна до клиентской области | 3
INLeftSpace | ^integer | Отступ слева от границы окна до клиентской области | 3
INRightSpace | ^integer | Отступ справа от границы окна до клиентской области | 3
INChangeSizeDistance | ^integer | Расстояние до границ окна, на котором можно с помощью мыши изменять его размеры | 4
INGlueDistance | ^integer | Начиная с какого расстояния, окна Кветки приклеиваются друг к другу | 8
INComboHeight | ^integer | Высота элемента управления ComboBox | 11
INComboWidth | ^integer | Ширина элемента управления ComboBox | 11
INCheckHeight | ^integer | Высота элемента управления CheckBox | 11
INCheckWidth | ^integer | Ширина элемента управления CheckBox | 11


Настройки окна "Журнал"

Идентификатор (используется в GetOptions) | Тип | Описание | Значение по умолчанию
INMaxInlineCommentLen | ^integer | Максимальная длина комментария, который может быть расположен inline внутри списка ходов окна "Журнал" | 16
INMakeManyMoves | ^boolean | Если равна true, то программа разрешит делать подряд несколько ходов одному и тому же игроку | false
INHighlightBKColor | ^integer | Цвет фона под выделенным ходом | $FF9A39
INHighlightTextColor | ^integer | Цвет текста выделенного хода | чёрный ($000000)


Настройки окна "Партии"

Идентификатор (используется в GetOptions) | Тип | Описание | Значение по умолчанию
INPageRatio | ^real | На какую долю страницы будет прокручиваться список партий при нажатии PageUp и PageDown. | 0.8
INAutoVisibleParties | ^boolean | Если равна true, то при открытии pgn-файла с множеством партий, окно партий автоматически становится видимым. В противном случае окна "Партии" не меняет своего состояния. | true
INMinColumnWidth | ^integer | Минимальная ширина столбца таблицы в окне "Партии" | 20
INHighlightBKColor | ^integer | Цвет фона под выделенной партией | $FF9A39
INHighlightTextColor | ^integer | Цвет выделенного текста | чёрный ($000000)


Настройки доски

Идентификатор (используется в GetOptions) | Тип | Описание | Значение по умолчанию
INHorzFieldBorder | ^integer | Ширина границы доски слева и справа. Примечание: в режиме расстановки фигур настройка автоматически увеличивается на величину IPCellWidth + INHorzPositionBorder | 4
INVertFieldBorder | ^integer | Высота границы доски сверху и снизу | 4
INHorzPositionBorder | ^integer | Ширина вертикальной чёрной полосы на доске | 4
INVertPositionBorder | ^integer | Высота горизонтальной чёрной полосы на доске | 4
INFigureAspectRatio | ^real | Отношение отступа фигуры к длине клетки | 0.1
INCellColors | ^TBoardArray | Цвета клеток доски |
INFieldLineColor | ^integer | Цвет линии, разделяющей клетки доски. Если он оказывается больше, чем $FFFFFF, то разделительные линии на доске не рисуются | белый ( $FFFFFF )
INGoodMoveColor | ^integer | В такой оттенок окрашивается клетка, если на неё можно походить | $80FF80
INBadMoveColor | ^integer | В такой оттенок окрашивается клетка, если на неё походить нельзя | $FF8080

Графическое представление некоторых из настроек:


Celclr

Настройка CelClr описывает цвета клеток доски. Доступ к ней осуществляется с помощью
GetOptions (INCellColors)

TBoardArray = array [0 .. 7, 0 .. 7] of integer;
var CelClr : ^TBoardArray;

Следующая таблица описывает значения CelClr^ по умолчанию.

 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
0 | $CC9453 | $3F3321 | $DCA562 | $645136 | $E8B46D | $7D6743 | $EEBA73 | $7B6542
1 | $31281A | $D69E5D | $57482E | $E4B06A | $7C6643 | $F4C178 | $967B4F | $F3BF78
2 | $D19958 | $473926 | $E2AB66 | $705C3D | $F0BB72 | $8F764E | $FCC980 | $8B724A
3 | $352A1C | $D8A05F | $594B2F | $E6B26C | $7C6643 | $F3BF78 | $8E754B | $EEBB75
4 | $CE9557 | $413523 | $DCA562 | $645136 | $E7B36C | $7B6542 | $ECB871 | $765F3F
5 | $272114 | $CD9756 | $3E3422 | $DEA861 | $615035 | $E2AE68 | $655334 | $E4AD68
6 | $C48B4E | $2A2215 | $D19958 | $453724 | $DAA360 | $54442D | $DCA764 | $53432C
7 | $0D0A06 | $C68D4F | $292114 | $CF9756 | $392F1E | $D69C5A | $3F3321 | $C79456


Настройки движка

Идентификатор (используется в GetOptions) | Тип | Описание | Значение по умолчанию
INDefaultEngineName | PWideChar | Имя движка по умолчанию. При первом запуске Кветка будет пытаться загрузить именно этот движок | 'Fruit-2-3-1.exe'
INTimeToWait | ^integer | После запуска движка программа посылает ему команду "uci". Эта настройка указывает, сколько времени Кветка будет ждать ответ от движка, прежде чем принять решение, что движок не поддерживает UCI. Измеряется в миллиекундах | 30000
INMoveNumber | ^integer | Число рекомендуемых ходов, которые движок должен выводить. Примечание: Кветка не поддерживает число рекомендуемых ходов большее, чем 10. Если для этой настройки указать значение, большее 10, то программа аварийно завершит работу. И, возможно, она будет аварийно завершать работу при каждом последующем запуске. | 5
INEngineGoCommand | ^string | Параметры команды "go", передаваемой движку. Подробнее о команде см. описание формата UCI. | 'infinite'#13#10


Список доступных параметров

Здесь приведены все параметры, доступ к которым можно получить с помощью GetParam.
    Выберите категориию
  • Параметры главного окна
  • Параметры вспомогательных окон и общие параметры
  • Параметры стандартных окон Кветки
  • Параметры доски
  • Параметры движка


Параметры главного окна

Идентификатор (используется в GetParam) | Тип | Описание
IPFieldWidth | ^integer | Ширина всей доски в пикселях
IPCellWidth | ^integer | Ширина одной клетки доски в пикселях
IPCurrentOffsetX | ^integer | Параметр lx. Устанавливается при нажатии левой кнопки мыши по окну (IfLButtonDown), используется во время перемещения указателя мыши (IfMouseMove). Если перемещается окно или изменяются его размеры (параметр IPIsWindowMoving равен true), то окно следует переместить так, чтобы курсор мыши по горизонтали отстоял от левой границы окна на lx пикселей. В случае приклеивания положение левой границы может немного измениться. Если перемещается фигура (параметр IPIsFigureMoving равен true), то lx - горизонтальная координата клетки, на которой эта фигура стояла. Координата отсчитывается от 0 до 7. В режиме расстановки фигур lx может быть равным -1 (взята фигура слева от доски) и 8 (взята фигура справа от доски).
IPCurrentOffsetY | ^integer | Параметр ly. Устанавливается при нажатии левой кнопки мыши по окну (IfLButtonDown), используется во время перемещения указателя мыши (IfMouseMove). Если перемещается окно или изменяются его размеры (параметр IPIsWindowMoving равен true), то окно следует переместить так, чтобы курсор мыши по вертикали отстоял от верхней границы окна на ly пикселей. В случае приклеивания положение верхней границы может немного измениться. Если перемещается фигура (параметр IPIsFigureMoving равен true), то ly - вертикальная координата клетки, на которой эта фигура стояла. Координата отсчитывается от 0 до 7.
IPOffsetCellX | ^integer | Параметр ox. Устанавливается при нажатии левой кнопки мыши по окну (IfLButtonDown), используется во время перемещения указателя мыши (IfMouseMove). Если перемещается фигура (параметр IPIsFigureMoving равен true), то её следует переместить так, чтобы левый край воображаемой клетки вокруг неё отстоял по горизонтали на ox пикселей от курсора мыши.
IPOffsetCellY | ^integer | Параметр oy. Устанавливается при нажатии левой кнопки мыши по окну (IfLButtonDown), используется во время перемещения указателя мыши (IfMouseMove). Если перемещается фигура (параметр IPIsFigureMoving равен true), то её следует переместить так, чтобы верхний край воображаемой клетки вокруг неё отстоял по верткали на ox пикселей от курсора мыши.
IPTargetCellX | ^integer | Параметр tx. Если перемещается фигура (параметр IPIsFigureMoving равен true), то tx - это горизонтальная координата клетки, над которой сейчас находится указатель мыши. Координата отсчитывается от 0 до 7. tx может выходить за эти пределы, в этом случае курсор мыши будет находиться за пределами доски.
IPTargetCellY | ^integer | Параметр ty. Если перемещается фигура (параметр IPIsFigureMoving равен true), то ty - это вертикальная координата клетки, над которой сейчас находится указатель мыши. Координата отсчитывается от 0 до 7. ty может выходить за эти пределы, в этом случае курсор мыши будет находиться за пределами доски.
IPIsFigureMoving | ^boolean | Перемещается ли сейчас фигура. При нажатии левой кнопки мыши по фигуре (IfLButtonDown) устанавливается в true. Используется в при перемещении курсора мыши (IfMouseMove). При отпускании левой кнопки (IfLButtonUp) устанавливается в false.
IPIsWindowMoving | ^boolean | Изменяются ли сейчас расположение или размеры главного окна. При нажатии левой кнопки мыши по главному окну (IfLButtonDown) устанавливается в true, если далее оно будет перемещаться или растягиваться. Используется в при перемещении курсора мыши (IfMouseMove). При отпускании левой кнопки (IfLButtonUp) устанавливается в false.
IPTipMainWindowStretch | ^byte | Тип растягивания главного окна. Список возможных типов. Устанавливается при нажатии левой кнопки мыши по главному окну (IfLButtonDown). Используется в при перемещении курсора мыши (IfMouseMove).
IPIsOnTop | ^boolean | Находится ли Кветка в режиме "поверх всех окон". Если да, то параметр равен true, в противном случае - false.


Типы растягивания окна

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

Значение | Описание
0 | Перетаскивается всё окно
1 | Окно растягивается за левый верхний угол
2 | Окно растягивается за левую границу
3 | Окно растягивается за левый нижний угол
4 | Окно растягивается за верхнюю границу
5 | Окно растягивается за нижнюю границу
6 | Окно растягивается за правый верхний угол
7 | Окно растягивается за правую границу
8 | Окно растягивается за правый нижний угол


Параметры вспомогательных окон и общие параметры

Идентификатор (используется в GetParam) | Тип | Описание
IPtoShowWindows | ^TVisArray | Параметр avis. Указывает, какие из окон "Журнал", "Партии" и "Движок" следует открыть, если все они закрыты и нажата средняя кнопка мыши.
IPModalResult | ^integer | Параметр mres - результат модального диалога. Как только открывается модальное окно (с помощью ShowModal) этот параметр устанавливается в значение 9999. Окно закроется тогда и только тогда, когда это значение изменится. Если окно закрывается с помощью нажатия на кнопку "X", то mres устанавливается в -1. В остальных случаях значение mres полностью задаётся пользователем.
IPAuxWindowList | ^TAuxWindowArray | Параметр wnds - массив вспомогательных окон Кветки. Каждый элемент содержит информацию, необходимую программе для реализации таких возможностей при работе с окном, как единообразный внешний вид, приклеивание друг к другу, открытие окна из подпункта меню "Дополнительный окна".
IPButtonList | ^TButArray | Параметр knops - массив кнопок Кветки. Каждый элемент содержит необходимую информацию, необходимую для реализации таких возможностей, как отрисовка кнопки, изменение её внешнего вида при нажатии и при наведении на неё курсора мыши.
IPMouseWindow | ^HWND | Параметр mousew - хэндлер окна, над которым сейчас находится курсор мыши. Автоматически устанавливается при наведении курсора мыши на любое окно и любой элемент управления Кветки. Используется для изменения внешнего вида кнопок при наведении на них курсора мыши. Примечание. Если окно в плагине создаётся не с помощью SozDopWnd или ShowModal, то параметр mousew на нём автоматически меняться не будет.
IPDownWindow | ^HWND | Параметр downw. Параметр downw - хэндлер кнопки, которая сейчас находится в нажатом состоянии. Совместно с IPMouseWindow используется для правильной отрисовки кнопки, находящейся в нажатом состоянии. Если кнпока мыши не отпускается, а курсор выходит за пределы кнопки, то она отображается как отжатая. При наведении на ней курсора мыши она опять нажимается. Если ни одна кнопка не нажата, downw = 0.
IPWindowMoveType | ^byte | Тип растягивания вспомогательного окна. Список возможных типов. Устанавливается при реакции на сообщение WM_NCHITTEST в процедуре DopfProc.
IPCriticalSection | ^_rtl_critical_section | Параметр lcrits - критическая секция. Призвана гарантировать, что основной процесс Кветки и процесс, обслуживающий движок не используют одновременно одни и те же данные. В противном случае это привело бы к труднонаходимым ошибкам. Принцип работы с критическими секциями в Кветке.
IPCurrentOffsetX | ^integer | Параметр lx. Устанавливается при нажатии левой кнопки мыши по окну (сообщение WM_NCLBUTTONDOWN), используется во время перемещения указателя мыши. Если перемещается окно или изменяются его размеры (параметр IPIsWindowMoving равен true), то окно следует переместить так, чтобы курсор мыши по горизонтали отстоял от левой границы окна на lx пикселей. В случае приклеивания положение левой границы может немного измениться.
IPCurrentOffsetY | ^integer | Параметр ly. Устанавливается при нажатии левой кнопки мыши по окну (сообщение WM_NCLBUTTONDOWN), используется во время перемещения указателя мыши. Если перемещается окно или изменяются его размеры (параметр IPIsWindowMoving равен true), то окно следует переместить так, чтобы курсор мыши по вертикали отстоял от верхней границы окна на ly пикселей. В случае приклеивания положение верхней границы может немного измениться.
IPIsWindowMoving | ^boolean | Изменяется ли сейчас положение окна. При нажатии левой кнопки мыши по заголовку окна устанавливается в true. Используется в при перемещении курсора мыши. При отпускании левой кнопки (сообщене WM_LBUTTONUP) устанавливается в false.


Параметр avis

Параметр avis указывает, какие из окон "Журнал", "Партии" и "Движок" следует открыть, если все они закрыты и нажата средняя кнопка мыши.

var avis : TVisArray = (true, true, true);
TVisArray = array [0 .. 2] of boolean;

Элементы массива с окнами связаны так:

  • avis[0] - "Журнал";
  • avis[1] - "Партии";
  • avis[2] - "Движок".

    Принцип работы
    При нажатии на среднюю кнопку мыши происходит следующее:

  • Если хотя бы одно окно из перечисленных видимо, то для видимых окон avis устанавливается в true, для остальных - в false. После этого все окна закрываются.
  • Если все окна закрыты, то делаются видимыми те из них, для которых avis = true.


Wnds

Параметр Wnds описывает вспомогательные окна Кветки. Доступ к нему осуществляется с помощью GetParam (IPAuxWindowList). Имеет тип TAuxWindowArray, представляющий собой массив.

TAuxWindowArray = array of TAuxWindowInfo;

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

  • 0 - окно "Журнал";
  • 1 - окно "Партии";
  • 2 - окно "Движок";
  • 3 - окно "Информация о партии";
  • 4 - окно "Настройки позиции";
    Гарантируется, что указанные вспомогательные окна будут иметь в массиве wnds именно такие номера. Таким образом, wnds можно использовать для получения информации об этих окнах. В плагине эти окна удаляться с помощью CloseWnd не должны. Остальные окна в массиве могут расположиться на произвольной позиции, в зависимости от очерёдности открытий новых окон.

    TAuxWindowInfo

    Структура TAuxWindowInfo описывает вспомогательное окно Кветки.

    TAuxWindowInfo = record
    wnd : HWND; // хэндлер окна
    xbut : HWND; // хэндлер кнопки "X"
    draw : DrawProc; // процедура отрисовки клиентской части окна
    inmenu : boolean; // есть ли для данного окна пункт в подменю "Дополнительные окна"
    vis : boolean; // видимо ли окно
    ismodal : boolean; // модально ли окно
    id : integer; // идентификатор пункта в подменю "Дополнительные окна"
    gl : boolean; // приклеено ли окно к главному окну
    end;

    Поля
    wnd :
    Хэндлер вспомогательного окна.

    xbut :
    Хэндлер кнопки "X" вспомогательного окна.

    draw :
    Указатель на процедуру, рисующую клиентскую часть вспомогательного окна. См. описание DrawProc. Именно этой процедуре будет передаваться управление при обработке сообщения WM_PAINT по умолчанию.

    inmenu :
    Если равно true, то в подменю "Дополнительные окна" главного меню будет присутствовать пункт, открывающий и закрывающий данное окно. В противном случае такого пункта не будет.

    vis :
    Видимо ли окно. Если главное окно Кветки видимо, то это поле совпадает с результатом функции IsWindowVisible из WinAPI. Однако когда программа свёрнута в панель задач, при vis = true после восстановления главного окна, данное вспомогательное окно тоже станет видимым. В противном случае - нет.

    ismodal :
    Если равно true, то окно является модальным. Если открыто модальное окно, все остальные окна оказываются недоступны ни с помощью мыши, ни с помощью клавиатуры.

    id :
    Идентификатор пункта подменю "Дополнительные окна" главного меню. Он используется функциями WinAPI при работе с пунктами меню. Если inmenu = false, этот параметр игнорируется.

    gl :
    Приклеено ли окно к главному окну. Если да (gl = true), то при перетаскивании главного окна оно будет перемещаться вместе с ним.


Knops

Параметр Knops описывает кнопки Кветки. Доступ к нему осуществляется с помощью GetParam (IPButtonList). Имеет тип TButArray, представляющий собой массив.

TButArray = array of TButInf;

См. описание типа TButInf.

Чтобы кнопка вела себя так же, как и остальные кнопки Кветки, её окно должно быть создано с использованием оконного класса "knop", и информация о ней должна быть добавлена в массив Knops с помощью AddKnop. Перед удалением кнопки необходимо удалить соответствующий элемент из Knops с помощью DelKnop. Первые элементы массива закреплены за следующими кнопками:

  • 0 - "На ход вперёд"
  • 1 - "На ход назад"
  • 2 - "Предыдущая партия"
  • 3 - "Следующая партия"
  • 4 - "X" главного окна
  • 5 - "Меню" главного окна
  • 6 - "Перевернуть доску"
  • 7 - "Минимизировать окно"
  • 8 - "Поверх других окон"
  • 9 - "ОК" при расстановке фигур
  • 10 - "Пустая доска" при расстановке фигур
  • 11 - "Стандартная расстановка" при растановке фигур
  • 12 - "Настройки" при расстановке фигур
  • 13 - "Сохранить" окна "Настройки позиции"
  • 14 - "Отмена" окна "Настройки позиции"
  • 15 - "Меню" окна "Движок"
  • 16 - "+" окна "Движок"
  • 17 - "-" окна "Движок"
  • 18 - "Добавить/изменить" окна "Информация о партии"
  • 19 - "Удалить" окна "Информация о партии"
  • 20 - "Сохранить" окна "Информация о партии"
  • 21 - "Отмена" окна "Информация о партии"
    Гарантируется, что указанные кнопки будут иметь в массиве Knops именно такие номера. В плагине эти кнопки не должны удаляться их из массива с помощью DelKnop.

    Примечание.
    Для доступа к кнопкам "X" вспомогательных окон воспользуйтесь параметром Wnds (IPAuxWindowList).


Параметры стандартных окон Кветки

Идентификатор (используется в GetParam) | Тип | Описание
IPGamesColumnWidhs | ^TGamesColArray | Массив из ширин столбцов в окне "партии".
IPGames | ^TGames | Параметр prs. Массив открытых партий. Все они отображаются в таблице окна "Партии". Подробности см. описание TGame
IPGameTags | ^TGamesTagArray | Параметр partg. Список тегов текущей партии, в окне "Информация о партии". При открытии этого окна в partg копируется информация из соответствующего элемента prs. При редактировании в окне тегов, изменения производятся только в partg. Внесённые изменения скопируются из partg в prs только при нажатии кнопки "Сохранить".
IPFEN1stPlayerComboGroup | ^TComboGroup | Группа элементов ComboBox "Чей ход" в окне "Настройки позиции". Первый элемент - "Чёрные", второй - "Белые". Подробнее см. описание TCombo.
IPFENCastlingWL | ^TCombo | Элемент CheckBox "Рокировка белые О-О-О".
IPFENCastlingWD | ^TCombo | Элемент CheckBox "Рокировка белые О-О".
IPFENCastlingBL | ^TCombo | Элемент CheckBox "Рокировка чёрные О-О-О".
IPFENCastlingBD | ^TCombo | Элемент CheckBox "Рокировка чёрные О-О".
IPFENenPassant | ^TComboGroup | Группа элементов ComboBox, отвечающих за возможность взятия на проходе. Номера элементов в группе:ы 0 - пешка на две клетки не ходила; 1, ..., 8 - взятие на клетку с координатами a6, ..., h6 соответственно; 9, ..., 16 - взятие на клетку с координатами a3, ..., h3 соответственно. Подробнее см. описание TCombo.
IPMoves | pointer | Текущий журнал. В настойщее время (Кветка 2.3) его структура не устоялась, поэтому использовать её в плагинах настоятельно не рекомендуется. Однако вполне допускаются сравнения и присваивания этого указателя с величинами, полученными с помощью GetJurParent и с элементами массива alts структуры TMove.
IPEngineOutputType | ^byte | Параметр tpvyv. Указывает, что сейчас будет выводиться в окне "Движок". Возможные варианты: 0 - Рекомендуемые варианты ходов; 1 - Вывод движка.

TGamesColArray
Массив TGamesColArray хранит ширины столбцов таблицы в окне "Партии".

TGamesColArray = array [0 .. 8] of integer;


Параметры доски

Идентификатор (используется в GetParam) | Тип | Описание
IPBoardBits | ^TBitsArray | Массив пикселей доски. Массив имеет размер (widt + 2 * ncx)*(widt + 2 * ncy), где widt - размер самой доски (см. IPCellWidth), ncx, ncy - ширина и высота границы доски (см. INHorzFieldBorder, INVertFieldBorder). Именно в таком виде впоследствие она изображается в главном окне. Формируется в DrawDoska.
IPWhitePawnBits | ^TBitsArray | Массив пикселей белой пешки. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение белой пешки на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPBlackPawnBits | ^TBitsArray | Массив пикселей чёрной пешки. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение чёрной пешки на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPWhiteKnightBits | ^TBitsArray | Массив пикселей белого коня. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение коня на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPBlackKnightBits | ^TBitsArray | Массив пикселей чёрного коня. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение коня на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPWhiteBishopBits | ^TBitsArray | Массив пикселей белого слона. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение слона на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPBlackBishopBits | ^TBitsArray | Массив пикселей чёрного слона. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение слона на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPWhiteRookBits | ^TBitsArray | Массив пикселей белой ладьи. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение ладьи на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPBlackRookBits | ^TBitsArray | Массив пикселей чёрной ладьи. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение ладьи на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPWhiteQueenBits | ^TBitsArray | Массив пикселей белого ферзя. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение ферзя на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPBlackQueenBits | ^TBitsArray | Массив пикселей чёрного ферзя. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение ферзя на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPWhiteKingBits | ^TBitsArray | Массив пикселей белого короля. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение короля на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPBlackKingBits | ^TBitsArray | Массив пикселей чёрного короля. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В этом массиве содержится изображение короля на фоне из пикселей со значением -1. При отрисовке фигуры на доске этот цвет считается прозрачным. Формируется в DrawFig.
IPCellBits | ^TBitsArray | Массив пикселей клетки доски. Массив имеет размер cwid*cwid, где cwid - ширина клетки (см. IPCellWidth). В нём отрисовывается отдельная клетка. Формируется в DrawCell.
IPFieldWidth | ^integer | Ширина всей доски в пикселях
IPCellWidth | ^integer | Ширина одной клетки доски в пикселях
IPFigures | ^TFigureArray | Массив фигур на доске, указывает, в какой клетке стоит какая фигура. Имеет размер 8*8.
IPIsBoardFieldRotated | ^boolean | Перевёрнута ли доска. Если да (значение true), то чёрные фигуры располагаются внизу доски, а верхние - сверху.
IPMoves | pointer | Текущий журнал. В настойщее время (Кветка 2.3) его структура не устоялась, поэтому использовать её в плагинах настоятельно не рекомендуется. Однако вполне допускаются сравнения и присваивания этого указателя с величинами, полученными с помощью GetJurParent и с элементами массива alts структуры TMove.

TBitsArray

Массив TBitsArray описывает буфер битовой карты для различных изображений.

TBitsArray = array [0.. 0] of integer;

Если битовая карта имеет размер wid*hei, то доступ к пикселю с координатами (x, y) осуществляется так:

MyBitsArray [wid * y + x]

TFigureArray

Массив TFigureArray описывает фигуры на доске.

TFigureArray = array [0.. 7, 0.. 7] of TFigur;

Элемент TFigureArray описывает фигуру, которая стоит на клетке доски с соответствующими координатами. См. описание типа TFigur.


Параметры движка

Идентификатор (используется в GetParam) | Тип | Описание
IPEngineList | ^TWideStrings | Список имён файлов, содержащих известные Кветке движки. Движки из этого списка отображаются в подменю "Движки" главного меню. Каждый элемент содержит полное имя файла вместе с путём к нему.
IPEngineNameList | ^TWideStrings | Список названий известных Кветке движков. Движки из этого списка отображаются в подменю "Движки" главного меню.
IPCurrentEngine | ^integer | Номер текущего движка из списка IPEngineList. Движки нумеруются с нуля. Если равен -1, то ни один движок не запущен.
IPEngineState | ^integer | Текущее состояние движка. Состояние движка определяет, как поток, обслуживающий движок, будет с ним работать. Список состояний движка и их описание.
IPPositionRating | ^string | Рейтинг позиции. Может принимать значения "[-]XXX.YY" - каково, по мнению движка, преимущество у белых (или у чёрных, если есть знак "-"). За единицу принимается преимущество в пешку. "мат [-]N" - мат в N ходов ставят белые (или чёрные, если стоит знак "-").
IPNextMove | ^string | Рекомендуемый следующий ход. Обычно записывается в короткой шахматной нотации. Иногда может записываться в формате UCI (обычно это означает, что Кветка посчитала ход некорректным).
IPMultRatings | ^TVarStrings | Список рейтингов рекомендуемых ходов. Кветкой модифицируются только первые INMoveNumber элементов массива. Значение остальных элементов неопределено. Элементы принимают те же значения, что и параметр IPPositionRating
IPMultNextMoves | ^TVarStrings | Список рекомендуемых ходов. Кветкой модифицируются только первые INMoveNumber элементов массива. Значение остальных элементов неопределено. Элементы принимают те же значения, что и параметр IPNextMove.
IPMultPossibleContinues | ^TVarStrings | Список вероятных продолжений. Кветкой модифицируются только первые INMoveNumber элементов массива. Значение остальных элементов неопределено.Чаще всего ходы записываются в короткой шахматной нотации. Иногда они могут записываться в формате UCI (обычно это означает, что Кветка посчитала один из ходов продолжения некорректным).
IPMaxMovesNumber | ^integer | Максимальное число вариантов ходов, поддерживаемое движком. Внимание. На данный момент (Кветка 2.3) Кветка не поддерживает более 10-ти возможных продолжений, даже если движок это поддерживает.
IPEngineOptions | ^string | Тонкие настройки для движка. Передаются движку сразу после его загрузки и получения ответа "uciok". Значение по умолчанию: 'setoption name UCI_AnalyseMode value true'#13#10; Подробнее о настройках см. описание формата UCI.
IPEngineOutputType | ^byte | Параметр tpvyv. Указывает, что сейчас будет выводиться в окне "Движок". Возможные варианты: 0 - Рекомендуемые варианты ходов; 1 - Вывод движка.
IPIsEngineStop | ^boolean | Параметр ifstop. Остановлен ли движок. Изменяется при нажатии на кнопку "Остановить/продолжить анализ" окна "Движок" или двойным щелчком по заголовку главного окна. Если ifstop = true, то движок остановлен. В противном случае - нет.

TWideStrings = array of WideString;

const MAX_VARIANTS_NUMBER = 10;
TVarStrings = array [1 .. MAX_VARIANTS_NUMBER] of WideString;

Модифицировать элементы таких массивов не рекомендуется, так как это может привести к труднонаходимым ошибкам.


Состояния движка

Здесь приведены возможные состояния параметра curstate (IPEngineState), описывающего состояние движка.

Значение | Описание
0 | Движок не загружен.
1 | Движок только что загружен. Проверяется, поддерживает ли он формат UCI, и какие настройки он поддерживает. Движку посылается команда "uci" и ожидается от него ответ "uciok", что будет означать, что движок поддерживает UCI и готов к работе. Когда такой ответ получен, curstate переходит в состояние 2. Если в течение определённого времени (см. INTimeToWait) ответ не получен, то движок выгружается, и curstate устанавливается в 0. Здесь же устанавливается параметр IPMaxMovesNumber.
2 | Состояние обдумывания хода. В этом состоянии движку передаются команды "position" и "go". Параметры "position" зависят от начальной расстановки фигур (стандартная или нет) и сделанных ходов; параметры "go" описаны в INEngineGoCommand. Во время обдумывания поступающая от движка информация обрабатывается в ReadvOutput. Если движок выдал информацию "bestmove" (анализ завершён, приводятся его результаты), то curstate переходит в состояние 4. Если в программе меняется позиция, то curstate переходит в состояние 3.
3 | Ожидание завершения обдумывания. В этом состоянии движок всё ещё обдумывает ход, но программа ожидает от него завершения анализа (например, сделан новый ход или зашоужена другая партия). При этом движку через определённые промежутки времени посылаются команды "stop" до тех пор, пока не будет получена информация "bestmove", что означает, что движок завершил работу. Как только такое происходит, curstate переходит в состоние 2.
4 | Движок завершил обдумывание. В этом случае до следующего изменения позиции не происходит ничего. Как только позиция меняется, curstate переходит в состояние 2.
5 | Поток с движком закрывается. Происходит, когда пользователь выбирает другой движок или выбирает работу без движка. При этом процесс движка выгружается из памяти, а curstate переходит в состояние 0.

Подробнее о работе с движком см. в описании формата UCI.


TFigur

Структура TFigur используется для описания отдельной фигуры.

TMove = ( empty, wpesh, wkon, wslon, wladja, wferz, wkorol, bpesh, bkon, bslon, bladja, bferz, bkorol ) ;

значение | описание
empty | пустая фигура (на клетке ничего не стоит)
wpesh | белая пешка
wkon | белый конь
wslon | белый слон
wladja | белая ладья
wferz | белый ферзь
wkorol | белый король
bpesh | чёрная пешка
bkon | чёрный конь
bslon | чёрный слон
bladja | чёрная ладья
bferz | чёрный ферзь
bkorol | чёрный король


WindProc

Функции типа WindProc используются для обработки сообщений каждого окна. Указатель на функцию именно такого типа используется в при регистрации класса окна в WinAPI.

WindProc = function (
wind : HWND; // хэндлер окна, которому предназначено сообщение
msg : UINT; // тип сообщения
wpar : WPARAM; // старший параметр сообщения
lpar : LPARAM // младший параметр сообщения
): LRESULT; stdcall;

Параметры
wind :
Хэндлер окна, которому предназначено сообщение

msg :
Тип сообщения. Указывает, какое поступило сообщение.

wpar, lpar :
Старший и младший параметры собщения. Содержат дополнительную информацию о сообщении. Их содержимое зависит от значения msg.

Возвращаемое значение
Результат обработки сообщения. Зависит от значения msg.

Подробное описание сообщений и их параметров можно найти в документации WinAPI.


Типы TGame и TPGNTag

TGame

Структура TGame используется для описания одной партии.

TGame = record
jur : pointer; // указатель на структуру, содержащую ходы партии
tags : TGamesTagArray; // список тегов, принадлежащих партии
end;

Поля
jur :
Указатель на структуру, содержащую ходы партии, комментарии к ним, ответвления и т.п. На данный момент (Кветка версии 2.2) внутренняя структура данного элемента ещё не устоялась. Поэтому настоятельно не рекомендуется её модифицировать.

tags :
Список тегов, принадлежащих партии. Теги описывают такие составляющие партии, как время и место проведения, имена и ELO игроков, результат партии, начальную позицию и т.п. Формат тегов взят из стандарта PGN. Например, при загрузке партии из pgn-файла, эта структура будет заполнена в соответствии с тегами из файла. Опсание типа TGamesTagArray и наиболее распространённых тегов см. ниже.

TGames

Структура TGames - представляет собой список партий.

TGames = array of TGame;

TPGNTag

Структура TPGNTag описывает отдельный тег партии. Теги описывают такие составляющие партии, как время и место проведения, имена и ELO игроков, результат партии, начальную позицию и т.п.

TPGNTag = record
nm : string; // название тега
vl : string; // значение тега
end;

Поля
nm :
Строка, содержащая название тега. По ней каждый тег идентифицируется, а потому каждое название в списке TGamesTagArray должно быть уникальным. По правилам формата PGN, навание должно состоять только из латинских букв, цифр и символа подчёркивания. Также оно не должно начинаться с символа подчёркивания. Если созданный вручную тег не будет удовлетворять этим требованиям, то сохранённая с ним партия впоследствии не откроется.

vl :
Строка, содержащая значение тега. По правилам формата PGN, значение должно состоять только из печатаемых символов (ASCII коды 32 - 126. Коды 160 - 255 допускаются, но не рекомендуются, так как они могут различаться в различных кодировках). Переводы строки и символы табуляции не допускаются.

Стандартные теги
Некоторые названия тегов зарезервированы и имеют конкретный смысл. В списке TGamesTagArray они должны идти первыми. Первые семь тегов (Seven Tag Roster) должны присутствовать в каждой партии.
Название | Номер | Описание | Формат значения
Event | 0 | Название турнира или матча. |
Site | 1 | Место проведения | "город, регион, страна". Для обозначения стран используются коды в формате IOC.
Date | 2 | Дата проведения | "YYYY.MM.DD". Если точное значение дня изи месяца неизвестно, то на соответствующее место ставятся знаки вопроса.
Round | 3 | Тур | "тур.подтур.подподтур" (например "3", "2.1" или "4.1.2").
White | 4 | Инициалы игрока белыми фигурами |
Black | 5 | Инициалы игрока чёрными фигурами |
Result | 6 | Результат партии | "1-0" - выигрыш белых "0-1" - выигрыш чёрных "1/2-1/2" - ничья "*" - результат неизвестен
SetUp | 7 (если есть) | Статус начальной позиции | "0" - партия начинается с обычной начальной расстановки "1" - партия устанавливается с позиции, указанной в теге FEN. В этом случае тег FEN должен присутствовать в в списке тегов.
FEN | 8 (если есть) | Начальная позиция партии | Записывается в формате FEN (описание).

TGamesTagArray

Структура TGamesTagArray - представляет собой список тегов для партии.

TGamesTagArray = array of TPGNTag;