KOLmirrorReadme.rus

Mirror Classes Kit для Key Objects Library, v2.00 [15 ноября 2004г.]
Copyright (C) 1999, 2000-2003 by Vladimir Kladov
-------------------------------------------------
Поддерживает Delphi 2, 3, 4, 5, 6, 7
Совмесима с Free Pascal 1.0.5/1.0.6 
Частично совместима с Kylix/FPC для компиляции под Linux с использованием Qt 

ПОЖАЛУЙСТА, ВНИМАТЕЛЬНО ПРОЧИТАЙТЕ ПРЕДУПРЕЖДЕНИЯ В КОНЦЕ ЭТОГО ФАЙЛА!
И ОСОБЕННО ОБРАТИТЕ ВНИМАНИЕ НА РАЗДЕЛ "РАЗРЕШЕНИЕ ПРОБЛЕМ", если у вас возникли какие-либо проблемы с установкой или использованием MCK.

	     СОДЕРЖАНИЕ

	I.	ВВЕДЕНИЕ
	II.	УСТАНОВКА
	III.	НАЧАЛО НОВОГО ЗЕРКАЛЬНОГО ПРОЕКТА
	IV.	ДОБАВЛЕНИЕ ФОРМЫ
	V.	УДАЛЕНИЕ ФОРМЫ
	VI.	ПЕРЕИМЕНОВАНИЕ ФОРМЫ
	VII.	НАПИСАНИЕ ЗЕРКАЛЬНОГО КОДА
	VIII.	ДОБАВЛЕНИЕ ССЫЛКИ НА МОДУЛЬ
	IX.	ИСПОЛЬЗОВАНИЕ НАСЛЕДНИКОВ TComponent ИЗ VCL
	X.	АВТОМАТИЧЕСКИ ГЕНЕРИРУЕМЫЕ ФАЙЛЫ
	XI.	MAINTAINANCE (КОПИРОВАНИЕ ФАЙЛОВ ПРОЕКТА)
	XII.	ПРЕДУПРЕЖДЕНИЯ
	XIII.   РАЗРЕШЕНИЕ ПРОБЛЕМ

	I. ВВЕДЕНИЕ

MCK (Mirror Classes Kit) - это набор зеркальных классов для ВИЗУАЛЬНОЙ разработки проекта в среде Delphi с использованием библиотеки KOL. (Что такое KOL - здесь разъяснять не буду, отсылаю на http://xcl.cjb.net). Хотя изначально ни KOL, ни ее предшественник XCL для визуальной разработки не годились и предназначены не были, предложения, идеи, вопросы и мысли от разрличных людей по этому поводу поступали с завидной регулярностью. Наконец, поразмыслив, я пришел к выводу, что все-таки реализовать визуальность для KOL возможно. И, несмотря на провал предыдущей попытки (проект XCL Wizard, если кто в курсе - он отнял у меня более полугода), я решился на новый проект. И хотя я сам неоднократно убеждал своих оппонентов в том, что это невозможно... За четыре вечера мне, кажется удалось совершить этот рывок.

Суть идеи "зеркальных классов" заключается в следующем. Для каждого визуально обособленного объекта библиотеки KOL создается компонент Delphi, который регистрируется обычным для компонента Delphi способом и размещается на палитре компонентов. Термин "визуально обособленный" я использую потому, что один и тот же (с формальной точки зрения) объектный тип в KOL может выполнять функции различных визуальных элементов. Например, TControl может быть и формой, и кнопкой, и меткой, и вообще каким угодно диалоговым элементом.

Проектирование в "зеркальных" классах состоит в том, что на этапе времени разработки (design-time) на форме размещается необходимое число зеркальных компонентов, настраиваются их свойства и события, пишется код обработчиков событий и делается все остальное, что нужно делать на этом этапе. При запуске полученного проекта... (и это новое)... генерируется код, который не содержит никаких обращений к классам VCL, и использует только возможности KOL. Этот код может быть запущен и отлажен самостоятельно или под отладчиком IDE. То есть, после начального создания проекта KOL согласно прилагаемым ниже инструкциям нет никакой необходимости переключаться в зеркальный проект - сам целевой проект является зеркальным. В том смысле, что во время разработки он ведет себя как визуальный, а после компиляции превращается в... чистый от VCL.

Описанный выше способ нисколько не сложнее того, к которому мы привыкли. Однако, результат превосходит все ожидания! Размер полученного приложения иногда в десять и более раз меньше аналогичного VCL-приложения, исполняется оно намного быстрее и ресурсов потребляет намного меньше, что действительно важно.

То, что есть на данном этапе - уже НЕ макет, а годный к ПРАКТИЧЕСКОМУ ИСПОЛЬЗОВАНИЮ инструмент, который прекрасно выполняет поставленную задачу (его, конечно, можно совершенствовать, но это не должно мешать главной цели - его использованию).
Основные отличие при программировании для KOL с MCK (от программирования в VCL) следующие:

- Не следует изменять свойства самой формы, кроме изменения ее размеров и позиции. Вместо этого изменяйте свойства объекта (компонента) TKOLForm, лежащего на ней. То же касается обработчиков событий. События, относящиеся к форме, назначайте для компонента TKOLForm!

- Не следует бросать на форму не-MCK компоненты и визуальные объекты. Работать можно только с компонентами, входящими в состав MCK.

- Некоторые свойства MCK-компонентов специально предназначены для времени проектирования и недоступны во время исполнения. Обычно названия таких свойств начинаются со строчной буквы.

- Для разрешения конфликта между VCL.Self и KOL.@Self введено заменяющее слово Form, которое требуется теперь использовать при написании кода в зеркальном проекте как синоним @Self для формы. На этапе разработки Form "как бы возвращает" Self (как бы - потому что этот код никогда не компилируется и не исполняется). После конверсии проекта Form ссылается теперь на объект формы (Form теперь является полем объекта, содержащего форму и ее дочерние объекты, и имеет тип PControl - в полном соответствии с требованиями KOL).
  Таким образом, не следует писать в обработчике события
	Caption := 'Привет';
Такой код не будет скомпилирован. Вместо этого следует писать:
	Form.Caption := 'Привет';

- локальные в VCL-форме компоненты, брошенные на нее во время разработки, одинаково "видны" в результирующем проекте KOL, хотя и не являются членами класса формы. Так происходит потому, что обработчики событий в "отраженном" проекте становятся методами того же объектного типа, членами которого теперь являются "образы" компонентов - визуальные и невизуальные объекты, "принадлежащие" форме.
  Примечание. Сия замысловатая фраза означает, что можно написать в обработчике события Button1, и это будет воспринято именно так, как Вы подумали.

- визуальное отображение контролов на этапе разработки (design-time) выполняется схематически, но позже (ещ позже) несложно может быть смоделировано более тщательное отображение путем переопределения процедуры Paint в каждом из зеркальных классов. (Более того, появляется потенциальная возможность менять визуальное представление объектов на форме простым изменением соответствующего (design-time-only) свойства в компоненте TKOLProject, или получать от этого дополнительные выгоды, что пока не реализовано).

- возможные конфликты между одинаковым наименованием типов, процедур, функций, констант и переменных в KOL и VCL предлагается решать по следующему правилу: 1. если имя имеет тождественный по смыслу тип, конфликт не возникает. 2. если совпадает только имя, то добавление уточняющего префикса <KOL.> устранит конфликт полностью (ссылка на KOL должна быть добавлена в директиву uses ПЕРВОЙ, чтобы объявления KOL имели меньший приоритет по сравнению с объявлениями VCL на этапе разработки кода в исходном проекте. Впрочем, такое добавление ссылки на KOL делается автоматически).

	II. УСТАНОВКА
___________________________________
DELPHI7 - УСТАНОВКА

1. Распаковать файлы в ту же директорию, в которой установлен KOL.
2. Открыть MirrorKOLPackageD7.dpk в Delphi IDE и нажать 'Install'.

DELPHI7 - ПЕРЕУСТАНОВКА (UPGRADE)

1. Во избежание возможных неприятностей, закрыть все файлы в IDE (File|Close All).
2. Распаковать файлы в ту же директорию, в которой установлен KOL.
3. Открыть MirrorKOLPackageD7.dpk в Delphi IDE и нажать 'Compile' (если пакет уже установлен, кнопка 'Install' должна быть недоступна).

___________________________________
DELPHI6 - УСТАНОВКА

1. Распаковать файлы в ту же директорию, в которой установлен KOL.
2. Открыть MirrorKOLPackageD6.dpk в Delphi IDE и нажать 'Install'.

DELPHI6 - ПЕРЕУСТАНОВКА (UPGRADE)

1. Во избежание возможных неприятностей, закрыть все файлы в IDE (File|Close All).
2. Распаковать файлы в ту же директорию, в которой установлен KOL.
3. Открыть MirrorKOLPackageD6.dpk в Delphi IDE и нажать 'Compile' (если пакет уже установлен, кнопка 'Install' должна быть недоступна).

___________________________________
DELPHI5 - УСТАНОВКА

1. Распаковать файлы в ту же директорию, в которой установлен KOL.
2. Открыть MirrorKOLPackage.dpk в Delphi IDE и нажать 'Install'.

DELPHI5 - ПЕРЕУСТАНОВКА (UPGRADE)

1. Во избежание возможных неприятностей, закрыть все файлы в IDE (File|Close All).
2. Распаковать файлы в ту же директорию, в которой установлен KOL.
3. Открыть MirrorKOLPackage.dpk в Delphi IDE и нажать 'Compile' (если пакет уже установлен, кнопка 'Install' должна быть недоступна).

___________________________________
DELPHI4 - УСТАНОВКА

1. Распаковать файлы в ту же директорию, в которой установлен KOL.
2. Открыть MirrorKOLPackageD4.dpk в Delphi IDE и нажать 'Install'.

DELPHI4 - ПЕРЕУСТАНОВКА (UPGRADE)
1. Во избежание возможных неприятностей, закрыть все файлы в IDE (File|Close All).
2. Распаковать файлы в ту же директорию, в которой установлен KOL.
3. Открыть MirrorKOLPackageD4.dpk в Delphi IDE и нажать 'Compile' (если пакет уже установлен, кнопка 'Install' должна быть недоступна).

___________________________________
DELPHI3 - УСТАНОВКА

1. Распаковать файлы в ту же директорию, в которой установлен KOL.
2. Открыть MirrorKOLPackageD3.dpk в Delphi IDE и нажать 'Install'.

DELPHI3 - ПЕРЕУСТАНОВКА (UPGRADE)
1. Во избежание возможных неприятностей, закрыть все файлы в IDE (File|Close All).
2. Распаковать файлы в ту же директорию, в которой установлен KOL.
3. Открыть MirrorKOLPackageD3.dpk в Delphi IDE и нажать 'Compile' (если пакет уже установлен, кнопка 'Install' должна быть недоступна).

___________________________________
DELPHI2 - УСТАНОВКА

1. Распаковать файлы в ту же директорию, в которой установлен KOL.
2. Component|Install...|Add|Browse|mirror.pas|OK
3. Component|Install...|Add|Browse|mckObjs.pas|OK
4. Component|Install...|Add|Browse|mckCtrls.pas|OK

DELPHI2 - ПЕРЕУСТАНОВКА (UPGRADE)
1. Во избежание возможных неприятностей, закрыть все файлы в IDE (File|Close All).
2. Распаковать файлы в ту же директорию, в которой установлен KOL.
3. Component|Install...|OK (установленные ранее модули mirror, mckObjs, mckCtrls уже должны быть видны в списке)


	III. НАЧАЛО НОВОГО ЗЕРКАЛЬНОГО ПРОЕКТА

1. В IDE Delphi: File|NewApplication.

2. Не бросать пока никакие компоненты на форму. Из меню выполнить File|Save All, выбрать папку для сохранения зеркального проекта и его модулей, и сохранить проект (два файла). ВСЕ МОДУЛИ проекта ВСЕГДА должны находиться В ОДНОЙ ДИРЕКТОРИИ!
   Внимание! Не называйте dpr-файл именем конечного проекта. Пусть он останется пока с именем Project1 (например). Назовите главный модуль (Unit1.pas) так, как он будет называться в проекте. 

3. Бросить TKOLProject на форму.

4. Изменить свойство ProjectDest (это имя результирующего проекта, здесь как раз можно ввести "настоящее" имя проекта, т.е. его dpr-файла, без расширения или указания пути - ввести следует только идентификатор).

5. Бросить на форму компонент TKOLForm.

6. В Delphi5 (только), необходимо теперь прописать в опциях САМОГО ПРОЕКТА путь к сервисным модулям:
   Project | Options | Directories/Conditionals | Search path
   и вписать сюда: $(Delphi)\Source\ToolsApi
   (возможно ввести этот путь в список Library path в Tools | Environment options | Library один раз, чтобы больше не заботиться об этом).

7. Если TKOLForm был брошен (5.) ПОСЛЕ изменения свойства TKOLProject.projectDest (4.), данный шаг не нужен, и результирующий проект готов (переходим к п.8).
   Иначе:
   измените в свойствах формы (TKOLForm), например, ее размер. Хотя exe-файл и не создается, результирующий проект при этом формируется, и готов к тому, чтобы его открыть.

8. Откройте полученный проект (в той же директории, имя - то, которое было задано в KOLProject1.ProjectDest). Файлы Project1.* можно со спокойной совестью удалить.

9. А вот теперь Вы имеете проект KOL/MCK. Можно бросать на форму зеркальные контролы из палитры (закладка KOL), настраивать их, назначать события, кодировать... Запускать, отлаживать. Короче, Банзай! т.е. Enjoy!

	IV. ДОБАВЛЕНИЕ ФОРМЫ
1. File|New form
2. Сохранить ее В ТУ ЖЕ ДИРЕКТОРИЮ, где лежат остальные файлы проекта.
3. Бросить на форму компонент TKOLForm. (Убедиться так же, что на главной форме уже лежит TKOLApplet, если нет - положить).
4. Собственно, все. Если в TKOLProject свойство AutoBuild = True (по умолчанию), то через BuildDelay микросекунд форма превратится в KOL-совместимую. Если нет, надо сделать двойной щелчок по свойству Build компонента TKOLProject (на главной форме).

	V. УДАЛЕНИЕ ФОРМЫ
1. Project|Remove from prject... - как обычно
2. В главной форме выделить TKOLProject, двойной щелчок по свойству Build.

	VI. ПЕРЕИМЕНОВАНИЕ ФОРМЫ
Не изменяйте имя формы, вместо этого измените свойство FormName компонента TKOLForm, лежащего на этой форме. (Главная форма тоже должна быть открыта).

	VII. НАПИСАНИЕ ЗЕРКАЛЬНОГО КОДА
  
  Если имена методов, процедур, переменных, типов, констант и т.д. будут конфликтовать с именами из VCL, добавляйте префикс <KOL.> для разрешения конфликтов.
  Не используйте имена из VCL, особенно из SysUtils, Classes, Forms, Dialogs и т.д. Все, что нужно для программирования, можно найти в самом KOL, а так же в Windows.pas, Messages.pas, ShellAPI.pas. Или написать самим (либо скопировать откуда-нибудь).
  Когда Вы пишете зеркальный код, обычно он размещается в обработчиках событий.
  Вы можете так же добавлять любой код (требуемые процедуры, функции, переменные, константы, типы и т.д. где угодно, кроме автоматически генерируемых inc-файлов и первой секции в декларации класса зеркальной формы), а так же добавлять ссылки на внешние модули в кластерах uses.
  При написании кода всегда следует помнить, что хотя он пишется для среды KOL, он должен быть синтаксически верен и в VCL. Иначе просто не дойдет до компиляции кода.
  ЭТО ВАЖНО:
  Для разрешения конфликта между словом Self из VCL и словом @Self в KOL, которые интерпретируются по-разному, введено специальное слово Form. В VCL-проекте (зеркале) Form - это свойство компонента TKOLForm, возвращающее Self. В KOL-проекте - это поле объекта с именем исходной формы, и является указателем на объект самой формы. Так что, для корректного обращения к свойствам формы из назначенного обработчика в обоих случаях правильно будет звучать:
	Form.Caption := 'Hello!';
  (В то же время старый стиль Caption := 'Hello!'; выдаст ошибку в сконвертированном KOL-проекте при попытке компиляции).
  Но предлагаемое слово Form следует использовать только для доступа к свойствам формы. Для доступа к дочерним объектам формы оно не требуется (и неверно). Надо, как обычно: 
	Button1.Caption := 'OK';
	Button1Click( Form );
  конец ЭТО ВАЖНО.
  Возможно создание нескольких экземпляров той же самой формы во время исполнения (run-time). По крайней мере, это полезно для динамического создания форм, которые не создаются автоматически (Project|Options|Forms, только не надо делать динамической главную форму). Используйте глобальную функцию NewForm1 (заменяя <Form1> именем своей формы), например:
  TempForm1 := NewForm1( Applet );
  Чтобы такое было возможным, НИКОГДА не используйте глобальную переменную, выделенную для формы при генерации проекта, если только Вы не знаете точно, зачем это надо. Используйте слово Form вместо нее.

	VIII. ДОБАВЛЕНИЕ ССЫЛКИ НА МОДУЛЬ

  Если необходимо использовать внешний модуль, не перечисленный в директиве uses, добавьте его как показано в приведенном отрывке:

====== НАЧАЛО ТИПИЧНОГО МОДУЛЯ, СОДЕРЖАЩЕГО ФОРМУ KOL: ========
{ KOL MCK } // Do not remove this line!
{$DEFINE KOL_MCK}
unit Unit1;

interface

{$IFDEF KOL_MCK}
uses Windows, Messages, ShellAPI, KOL {$IFNDEF KOL_MCK}, mirror, Classes,
  Controls, mckCtrls {$ENDIF}, <-- список имен дополнительных модулей -->;
{$ELSE}
{$I uses.inc} mirror,
  Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs,
  mirror;
{$ENDIF}
====== КОНЕЦ ОТРЫВКА ======

	IX. ИСПОЛЬЗОВАНИЕ НАСЛЕДНИКОВ TComponent ИЗ VCL

  Начиная с версии MCK v0.71, возможно использовать невизуальные компоненты, основанные на VCL, в визуальных проектах KOL+MCK. Для них будет сгенерирован код, их конструирующий, и разрушающий, присвоены события и те свойства, которые отличаются от присваиваемых в конструкторе.
  Тем не менее, использование компонентов VCL в проектах, основанных на KOL, не рекомендуется, так как в любом случае они потянут за собой очень большой объем неиспользуемого кода.
  В то же время, использование визуальных компонентов VCL в проекта MCK невозможно вообще. Компоненты TKOLProject и TKOLForm блокируются немедленно в случае обнаружения таких объектов на форме, что предотвращает порчу VCL-проектов в случае ошибочного бросания компонентов MCK на форму обычного VCL-проекта.
  Если VCL компонент используется в проекте MCK, учтите, что:
- автоматическая генерация кода не происходит, когда свойства такого компонента изменяются или ему назначаются обработчики событий. Следует (например) двойным щелчком по компоненту TKOLProject форсировать генерацию кода после внесения каких-либо изменений в настройку чужеродного компонента.
- когда VCL компонент "брошен" на форму, Delphi добавляет ссылку на его модуль в кластер uses, но она оказывается обычно помещена между скобками {$IFNDEF KOL_MCK}...{$ENDIF}, так что проект не может быть нормально откомпилирован. Чтобы исправить это, перенесите ссылку на модуль за скобки:
   ..., SomeUnit {$ENDIF};      ->    ... {$ENDIF} , SomeUnit;

	X. АВТОМАТИЧЕСКИ ГЕНЕРИРУЕМЫЕ ФАЙЛЫ

1. В дополнение к <YourProject>.dpr, генерируются файлы:
   - <YourProject>_0.inc - содержит альтернативный код инициализации приложения,
				замещающий собой то, что находится в dpr-файле между
				begin и end. Структура примерно следующая:

				Applet := NewApplet( ... ); // если используется TKOLApplet
				[ Applet.Visible := False; ] // опционально
				[ Applet.OnMessage := ...; ] // опционально

				{$I <YourProject>_1.inc}

				{$I <YourProject>_2.inc} // автоматический, создает формы

				{$I <YourProject>_3.inc}

				Run( ... );

				{$I <YourProject>_4.inc}

   - <YourProject>_1.inc - создается пустым, если не существует. Вы можете изменять
				его, помещая в него код, который сработает немедленно после
				(опциональной) инициализации переменной Applet. Например,
				здесь можно написать условный оператор, который предотвратит
				дальнейший запуск приложения в некоторых случаях.

   - <YourProject>_2.inc - генерируется автоматически, содержит код инициализации
				автоматически создаваемых форм. Никогда не модифицируйте
				его.

   - <YourProject>_3.inc и <YourProject>_4.inc - так же, как и <YourProject>_1.inc, генерируется пустым, если не существует. Размещайте в нем свой код (любой).

тут уже просто некогда было перевести... но это не так важно:

2. For every unit with form, additional file <UnitName>_1.inc is generated automatically. You should never change it manually.

3. File uses.inc also is generated automatically and You should not alter it manually. It contains word 'uses' only, included to final code via directive {$I uses.inc}. 

	XI. MAINTAINANCE
  For backup / copy purposes, following files are necessary to be stored to restore your project later or in another directory (on another PC):
  <YourProject>.dpr
  <YourProject>_1.dpr - if You altered it
  <YourProject>_3.dpr - if You altered it
  <YourProject>_4.dpr - 	-||-
  <YourProject>.res   - if You use app icon and altered it
  <YourUnit>.pas      - for every unit
  <YourUnit>.dfm      - for every unit with form
  <YourProject>.cfg
  <YourProject>.dof
  other files, created specially for a project (*.rc;*.res;*.bmp;*.ico; etc.)

Files could be recreated, but desired for backup / copy:
  <YourProject>_0.inc
  <YourProject>_2.inc
  <YourUnit>_1.inc    - for every unit
  <YourProject>.dsk
  <YourProject>.drc

And following files You are free to remove any time You wish:
  *.dcu; *.~*; *.$$$; *.exe

######################################
#                                    #
#  XII. П Р Е Д У П Р Е Ж Д Е Н И Е  # 
#                                    #
######################################
1. Никогда не бросайте TKOLProject (и другие KOL-компоненты) на форму нормального VCL-проекта - они будут заблокированы и не будут функционировать.
2. В модулях полученного KOL/MCK проекта не трогайте все, что лежит между автоматически добавленными {$IF[N]DEF}...{$ENDIF}.
3. Не надо пытаться редактировать автоматически генерируемые INC-файлы.
4. Если Вы включили консоль (св-во ConsoleOut обьекта TKOLProject), НЕ ЗАКРЫВАЙТЕ ее. Просто смените значение ConsoleOut в False.
5. Сохраняйте зеркальные проекты по крайней мере в другой директории, чем обычные проекты VCL - во избежание каких-либо потенциальных совпадений имен модулей.
6. Если у Вас на компьютере что-нибудь испортится, помните - разработчик в соответствии с лицензионным соглашением НЕ НЕСЕТ НИКАКОЙ ответственности. 

	XIII. РАЗРЕШЕНИЕ ПРОБЛЕМ

1. Если у вас не получилось установить MCK, прочитайте инструкцию по установке еще раз. Например, обратите внимание, тот ли пакет вы пытаетесь установить: может быть, у вас другая версия Delphi.
2. Нет никаких проблем с установкой MCK в Delphi, независимо от того, какая у вас редакция: Enterprise или Personal. У вас проблемы? Прочитайте инструкцию, пожалуйста.
3. Если при попытке компиляции вы получаете сообщение о том, что не найдены файлы ToolsAPI (DsgnIntf например), обнаруживается синтаксическая ошибка в коде (хотя вы еще не писали код), или еще что-нибудь в этом духе, прочитайте еще раз раздел "НАЧАЛО НОВОГО ЗЕРКАЛЬНОГО ПРОЕКТА". Чаще всего ошибка в том, что вы пытаетесь откомпилировать и запустить исходный проект, тогда как следовало его закрыть и открыть тот, который сформировался в результате выполнения п.п. 1-7.
4. Еще что-то не получается? Вы, наверное, не читали инструкцию. Извините :)
5. Нет, конечно, всякие вещи возможны. Но попробуйте провести чистый эксперимент. Установите Delphi заново (или на другой машине) и попробуйте сделать все согласно инструкции, шаг за шагом. Уверяю вас, все получится.
6. На всякий случай: пакет замены system.dcu не должен устанавливаться в ту же директорию, где расположены файлы самих KOL и MCK.

-----------------------------------------------------------------
http://bonanzas.rinet.ru ИЛИ http://xcl.cjb.net
bonanzas@online.sinor.ru ИЛИ bonanzas@xcl.cjb.net
   
------------------------------------------------------------------
(C) 2000-2003, by Vladimir Kladov. All rights reserved.