Формы и компоненты

Обзор графических компонентов

Система скриптинга работает с двумя типами компонентов: визуальными и невизуальными.

Визуальные компоненты используются для построения пользовательского интерфейса, а невизуальные — для выполнения различных задач, например с помощью компонентов Timer, OpenDialog и MainMenu.

• Невизуальный компонент Timer можно использовать для запуска определённого кода через заданные интервалы времени, при этом пользователь его никогда не видит.
• Компоненты Button, Edit и Memo являются визуальными.

Оба типа компонентов отображаются на этапе проектирования, но невизуальные компоненты не видны во время выполнения. Компоненты с панели Tool Palette являются объектно-ориентированными и имеют следующие три элемента:

• Свойства
• События
• Методы

Property — это характеристика объекта, влияющая либо на видимое поведение, либо на операции этого объекта. Например, свойство Visible определяет, будет ли этот объект видим на форме скрипта.

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

Method — это процедура, всегда связанная с объектом и определяющая поведение объекта.

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

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

Система скриптинга предоставляет ряд компонентов, которые можно использовать для создания сложных пользовательских интерфейсов для скриптов. Чтобы поместить компонент на форму, найдите его значок на панели Tool Palette panel и дважды щёлкните по нему. Это действие добавит компонент на активную форму. Визуальное представление большинства компонентов задаётся их свойствами. Изначально компонент размещается на форме в позиции по умолчанию, но при необходимости его можно перемещать (перетаскивать) и изменять размер (растягивать). Позже вы также можете изменить размер и положение с помощью панели Object Inspector .

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

Проектирование форм скриптов

Форма скрипта предназначена для взаимодействия с пользователем в рамках среды. Проектирование форм скриптов — основа визуальной разработки.

На практике все компоненты размещаются на форме скрипта, а каждое установленное свойство сохраняется в файле, описывающем форму (файл *.DFM), который связан с соответствующим кодом скрипта (файл *.PAS). Для каждой формы скрипта существует файл .PAS и соответствующий ему файл .DFM.

При работе с формой скрипта и её компонентами все свойства элементов можно просматривать и изменять с помощью панели Object Inspector. Можно выбрать несколько компонентов, удерживая Shift и щёлкая по компонентам, либо протянув прямоугольник выделения вокруг компонентов на форме. У формы скрипта есть заголовок (свойство Caption на панели Object Inspector).

Создание новой формы скрипта

При открытом проекте скрипта щёлкните правой кнопкой мыши по проекту на панели Projects, выберите пункт Add New to Project в контекстном меню и затем выберите пункт Delphi Script Form. Откроется новая форма скрипта с именем по умолчанию EditScript1.pas.

Отображение формы скрипта

Скрипт должен содержать процедуру, которая отображает форму при выполнении формы скрипта. Внутри этой процедуры для формы можно вызвать метод ShowModal. Чтобы метод ShowModal формы скрипта работал корректно, свойство Visible формы должно быть установлено в false.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

Пример ShowModal демонстрирует очень простой способ отображения формы скрипта при вызове процедуры RunDialog. Обратите внимание: значения можно присваивать компонентам объекта DialogForm до вызова метода DialogForm.ShowModal.

Пример со свойством ModalResult, показанный ниже, немного сложнее. Следующие методы в скрипте используются для кнопок на форме скрипта. Эти методы завершают диалог, когда пользователь нажимает кнопку OK или Cancel, что возвращает mrOk или mrCancel из метода ShowModal соответственно.

ModalResult Example:

Procedure TForm.OKButtonClick(Sender: TObject);
Begin
  ModalResult := mrOK;
End;

Procedure TForm.CancelButtonClick(Sender: TObject);
Begin
  ModalResult := mrCancel;
End;

Procedure RunShowModalExample;
Begin
  // Form's Visible property must be false for ShowModal to work correctly.
  If Form.ShowModal = mrOk Then ShowMessage('mrOk');
  If Form.ShowModal = mrCancel Then ShowMessage('mrCancel');
End;

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

Обратите внимание: если вы хотите установить ModalResult формы в Cancel при нажатии пользователем клавиши Esc , используйте панель Object Inspector , чтобы установить свойство Cancel кнопки Cancel в True, либо вставьте Sender.Cancel := True в обработчик события CancelButtonClick кнопки формы.

Приём ввода от пользователя

Один из распространённых компонентов, принимающих ввод от пользователя, — компонент TEdit. У этого компонента есть поле, в которое пользователь может вводить строку символов. Обратите внимание, что существуют и другие компоненты Delphi, такие как TMaskEdit — это компонент ввода с маской, хранящейся в строке, которая управляет вводом или фильтрует его.

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

Procedure TScriptForm.ButtonClick(Sender : TObject);
Begin
  If Edit1.Text = '' Then
  Begin
    ShowMessage('Warning - empty input!');
    Exit;
  End;
  // do something else for the input
End;

Обратите внимание: пользователь может менять фокус ввода в диалоге с помощью клавиши Tab или щёлкнув по другому элементу управления на форме.

Реакция на события

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

See also
Проект HelloWorld из папки Scripts\DelphiScript Scripts\General\ коллекции скриптов scripts collection.
Пример скрипта ShowModal из папки Scripts\DelphiScript Scripts\General\ коллекции скриптов scripts collection.

Написание обработчиков событий

Каждый компонент в скрипте формы имеет набор имён событий, и они используются обработчиками событий скрипта, которые определяют, как скрипт будет реагировать на действия пользователя в Altium Designer. Например, когда пользователь нажимает кнопку на форме, Altium Designer отправляет сообщение скрипту, и скрипт реагирует на это новое событие. Если для кнопки задано событие OnClick, оно выполняется.

Код реакции на события обычно содержится в обработчиках событий DelphiScript, и все компоненты имеют набор событий, на которые они могут реагировать. Например, все кликабельные компоненты имеют событие OnClick, которое срабатывает, когда пользователь щёлкает по компоненту. У всех таких компонентов также есть события получения и потери фокуса. Однако если код для OnEnter и OnExit не задан (OnEnter — элемент управления получил фокус; OnExit — элемент управления потерял фокус), событие будет проигнорировано скриптом.

Итак, событие — это связь между происходящим в Altium Designer, например нажатием кнопки, и фрагментом кода, который реагирует на это действие. Реагирующий код — это обработчик события. Этот код изменяет значения свойств и вызывает методы.

Свойства компонента

Чтобы увидеть список свойств компонента, выберите компонент и откройте вкладку Properties на панели Object Inspector.

События компонента

Чтобы увидеть список событий, на которые компонент может реагировать, выберите компонент и откройте вкладку Events на панели Object Inspector. Чтобы создать процедуру обработки события, выберите событие, на которое должен реагировать компонент, и дважды щёлкните имя события — система скриптинга автоматически вставит каркас кода обработчика события.

Например, выберите компонент TButton на панели Tool Palette и перетащите его на форму скрипта, затем дважды щёлкните рядом с именем события OnClick на панели Object Inspector . Система скриптинга переведёт фокус в редактор кода, и будет создан скелетный код для события OnClick.

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

Вкратце: выберите компонент кнопки либо на форме, либо с помощью панели Object Inspector, выберите страницу Events и дважды щёлкните в правой части события OnClick — в скрипте появится новый обработчик события. Либо дважды щёлкните по самой кнопке, и система скриптинга добавит обработчик для события OnClick. Обратите внимание, что у других типов компонентов будут другие действия по умолчанию.

Методы компонента

Чтобы увидеть список методов компонента, см. документ Component Reference.

Размещение компонентов на форме скрипта

Чтобы использовать компоненты из панели Tool Palette panel в скрипте, перед тем как можно будет перетаскивать компоненты на форму, должна существовать форма скрипта. Обычно, когда компоненты перетаскиваются на форму скрипта, эти объекты не нужно создавать или уничтожать — форма скрипта делает это автоматически.

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

Создание компонентов в скрипте

Компоненты можно напрямую создавать или уничтожать в скрипте, передавая параметр Nil в Constructor компонента. Обычно передавать handle формы не требуется, потому что форма скрипта автоматически берёт это на себя. Например, можно создавать и уничтожать диалоги Open и Save (TOpenDialog и TSaveDialog классы из Embarcadero Delphi RTL).

Настройка форм скриптов

Ключевые моменты при настройке форм скриптов:

• Чтобы принудительно удерживать форму поверх других открытых панелей, установите свойство FormStyle в fsStayOnTop.
• Чтобы определить поведение формы по умолчанию, установите FormKind в одно из следующих значений: fkNone, fkNormal, fkServerPanel или fkModal.
• Если fkModal закрыт, то форма будет модальной — то есть будет ожидать ввода пользователя перед продолжением, например, до закрытия формы. Если fkServerPanel, то форма будет показана как панель Server. Если fkNormal, то форма ведёт себя как обычная немодальная форма.
• Чтобы убрать стандартные полосы прокрутки формы, измените значения свойств HorzScrollBar и VertScrollBar.
• Чтобы сделать форму MDI-фреймом или MDI-дочерней, используйте свойство FormStyle.
• Чтобы изменить стиль границы формы, используйте свойства BorderIcons и BorderStyle (результаты видны во время выполнения).
• Чтобы изменить значок для свернутой формы, используйте свойство Icon.
• Чтобы задать начальное положение формы в окне приложения, используйте свойство Position.
• Чтобы задать начальное состояние формы (например, свернутое, развернутое или обычное), используйте свойство WindowState.
• Чтобы определить рабочую область формы во время выполнения, используйте свойства ClientHeight и ClientWidth (обратите внимание, что ClientHeight и ClientWidth представляют область внутри границы формы; Height и Width представляют всю область формы).
• Чтобы указать, какой элемент управления получает начальный фокус на форме во время выполнения, используйте свойство ActiveControl.
• Чтобы передавать все события клавиатуры форме независимо от выбранного элемента управления, используйте свойство KeyPreview.
• Чтобы указать конкретное меню, если форма содержит более одного меню, используйте свойство Menu.

Обновление форм и компонентов скриптов

Когда поверхность формы скрипта становится неактуальной — например, элементы управления не обновляются или не перерисовываются — элементы управления могут выглядеть «зависшими» или повреждёнными; это может быть вызвано интенсивной фоновой обработкой в этом скрипте.

Метод Update формы скрипта, а также многие компоненты скриптов из панели Tool Palette предоставляют способ обновить графическое содержимое формы или конкретного элемента (элементов) управления. Строки, содержащие метод Update, выделены серым цветом в примере ниже.

StatusBar component and its Update method Example:

Procedure TConverterForm.loadbuttonClick(Sender: TObject);
Begin
 If OpenPictureDialog1.Execute then
 Begin
 XPProgressBar1.Position := 0;
 XStatusBar1.SimpleText  := '  Loading...';
 XStatusBar1.Update;
 
 // loading a monochrome bitmap only
 Image1.Picture.LoadFromFile(OpenPictureDialog1.FileName);
 
 // Check if image is monochrome, otherwise prompt a warning
 If Image1.Picture.Bitmap.PixelFormat <> pf1bit Then
 Begin
 ShowWarning('The image is not a monochrome!');
 Close;
 End;
 
 lImageSize.Caption := IntToStr(Image1.Picture.Width) + ' x ' +
 IntToStr(Image1.Picture.Height) + ' mils';
 
 convertbutton.Enabled  := True;
 LoadButton.Enabled     := False;
 XStatusBar1.SimpleText := '  Ready...';
 XStatusBar1.Update;
 End;
End;

Приведённый выше фрагмент кода взят из скриптового проекта PCB Logo Creator, который можно найти в папке Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator в downloadable коллекции скриптов.