Сценарии графических компонентов

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

Визуальные компоненты форм, доступные для использования в скриптах Altium Designer, в основном основаны на Visual Component Library (VCL) компании Embarcadero — это набор определённых визуальных компонентов для разработки Windows‑приложений на языках Delphi и C++.

Будучи разработанной как визуальная библиотека классов, классы VCL в линейной иерархии объектов наследуются от объекта TComponent (который, в свою очередь, является потомком корневого объекта TObject). Поэтому типовой компонент скрипта, например объект TButton, наследует свойства, методы и события от своих предков. В данном случае иерархия классов такова: TObject → TPersistent → TComponent → TControl → TWinControl → TButtonControl → TButton.

Обратите внимание: компоненты, происходящие от объекта TControl, как правило, являются визуальными компонентами (элементами управления), а общие компоненты, происходящие от TWinControl, в основном представляют собой обёртки над Windows API.

► См. Embarcadero RAD Studio VCL для обзора архитектуры VCL и её компонентов.

При создании Form в Script Editor Altium Designer доступ к компонентам осуществляется из панели Tool Palette. Для Script Forms существует связанный файл *.DFM, содержащий сведения о конфигурации формы, расположении её компонентов и других атрибутах — этот файл можно найти в папке хоста проекта скрипта. Altium Designer позволяет использовать компоненты при проектировании Script Forms как с DelphiScript, так и с VBScript.

Панель Tool Palette содержит визуальные элементы управления, сгруппированные по категориям, которые можно перетаскивать на Script Form.

Панель Tool Palette panel содержит категоризированные наборы компонентов, которые можно размещать на Script Form. Доступные компоненты собраны в раскрывающиеся разделы на панели Tool Palette и распределены по категориям Standard, Additional, Win32, System, Dialogs, Altium Standard и Instrument Controls.

Компоненты (или «controls»), доступные в Palette, при использовании на форме скрипта являются визуальными компонентами — то есть пользователь видит элемент управления и, возможно, может взаимодействовать с ним во время выполнения. У всех элементов управления есть свойства, методы и события, описывающие аспекты их внешнего вида, например свойство позиции элемента управления, методы для отрисовки или перемещения элемента, а также события, реагирующие на действия пользователя.

Свойства и события доступны в панели Object Inspector panel для текущего выбранного компонента формы, включая саму форму. Методы — это процедуры и функции, поддерживаемые данным компонентом.

Обзор Script Forms

Script Forms

Script Form — это основной пользовательский интерфейс в скриптах, хотя существуют и другие формы, такие как диалоговые окна, вторичные окна и т. п. Чтобы создать новую Script Form при открытом проекте в Altium Designer, выберите File » New » Script » Script Form или щёлкните правой кнопкой по имени Script‑проекта и выберите Add New to Project » Script Form. Если включён язык VBScript, команда доступна как для VB Script, так и для Delphi Script.

Появится новая Script Form с именем по умолчанию Form1, которое можно изменить через свойство Name (в разделе Misc) в панели Object Inspector. Имена Script Form должны быть уникальными в пределах проекта.

При проектировании Script Form откройте панель Object Inspector с помощью кнопки Script в нижней строке состояния.

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

• Элементы управления
• Кнопки Minimize и Maximize
• Строка заголовка
• Изменение размера перетаскиванием границы

Эти возможности, как и любые другие доступные свойства формы, можно изменить на этапе проектирования с помощью панели Object Inspector. Поскольку Script Form является компонентом VCL, у неё есть следующие три сущности:

• Properties – Характеристики объекта, влияющие на его видимое поведение или операции. Например, свойство Visible определяет, может ли объект быть видимым на форме скрипта.
• Events – Действия или события, обнаруживаемые скриптом. Скрипт должен содержать код для каждого обработчика событий (Event handler), который предназначен для перехвата конкретного события, например щелчка мышью.
• Methods – Процедуры скрипта, связанные с объектами (в данном случае — объектами компонентов) и определяющие их поведение.

► См. Writing Scripts — базовое руководство по разработке скрипта на основе формы.

Свойства, методы и события формы

Элементы управления панели Tool Palette основаны на Embarcadero Visual Component Library (VCL). Полные сведения о методах, свойствах и событиях компонента Form (TForm) см. в документации Embarcadero VCL.

► См. Embarcadero TForm referenceОбратите внимание: ссылка выше ведёт на справочник Embarcadero RAD Studio XE6 для библиотеки VCL. Также доступна документация для предыдущих выпусков (вплоть до версии 2010).

Свойства TForm

Доступные свойства для объекта компонента TForm (базовой формы скрипта) можно просмотреть следующими способами:

• Через панель Object Inspector Panel — в режиме Form редактора (выбрана вкладка Form ) щёлкните в области самой формы и выберите вкладку Object Inspector's Properties .

Обратите внимание: в панели будут отображаться только объекты визуальных компонентов. Невизуальные объекты, которые работают «за кулисами» как элементы управления, на форме не отображаются.

• С помощью функции Code Completion — в режиме Code редактора (выбрана вкладка Code ) контекстно‑зависимое окно Code Completion покажет все варианты кода для имени объекта.

Для объекта Form введите TForm. (обратите внимание на точку), чтобы открыть окно. Сузьте поиск, набрав первые несколько букв нужного свойства — учтите, что отображаются и свойства, и методы.

• Из справочной документации Embarcadero на странице TForm Properties reference page.

Методы TForm

Доступные методы для объекта компонента TForm можно просмотреть следующими способами:

• Использовать функцию Code Completion — в режиме Code редактора введите имя компонента и точку. Откроется окно Code Completion, где будут показаны методы (и свойства) для имени объекта. Обратите внимание: окно подсказок можно вручную вызвать сочетанием клавиш Crtl+Space.

• Обратиться к справочной документации Embarcadero на странице TForm Methods reference page. Учтите, что там показаны все унаследованные методы, однако эту опцию можно отключить.

События TForm

Доступные события для объекта компонента TForm можно просмотреть следующими способами:

• Панель Object Inspector — в режиме Form редактора щёлкните в области самой формы и выберите вкладку Events в Object Inspector.

• В справочной документации Embarcadero на странице TFrom Events reference page.

Свойства, события и методы компонентов

Элементы управления панели Tool Palette основаны на Embarcadero Visual Component Library (VCL). Полные сведения о методах, свойствах и событиях для большинства компонентов см. в категориях компонентов документации Embarcadero VCL. Некоторые типы компонентов в Tool Palette, в частности Altium Instrument Controls, являются эксклюзивными для Altium Designer и не включены в справочную документацию Embarcadero.

► См. Embarcadero VCL Components Categories Index

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

Чтобы увидеть список свойств компонента:

• Выберите компонент на форме и активируйте вкладку Properties в панели Object Inspector — как показано выше для объекта компонента TForm.
• Выберите ссылку Properties (вверху) на соответствующей странице справки компонента в Embarcadero reference documentation. Например, для элемента управления TButton выберите категорию Standard Component, страницу TButton, а затем представление Properties.

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

Чтобы увидеть список событий, на которые компонент может реагировать:

• Выберите компонент на форме и активируйте вкладку Events в панели Object Inspector — как показано выше для объекта компонента TForm.
• Выберите соответствующую страницу справки компонента, а затем ссылку Events в Embarcadero reference documentation. Учтите, что это полезно как ориентир по доступным событиям компонента и может не полностью совпадать с событиями, доступными для компонентов скриптинга Altium Designer.

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

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

Она включает справочные материалы по следующим категориям объектов элементов управления.

• Standard
• Additional
• Win32
• System
• Dialog
• Altium Standard
• Instrument Controls

В основном эти категории объединяют типы визуальных элементов управления форм, основанные на стандартных VCL‑компонентах Delphi‑типа. Категории Altium Standard и Instrument Controls являются исключением, поскольку предлагают компоненты, эксклюзивные для системы скриптинга Altium Designer.

► См. Tool Palette Component Categories.

Работа с формами и компонентами

Настройка Script Forms

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

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

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

Метод Update скриптовой формы предоставляет программный способ обновить графическое содержимое формы или конкретных элементов управления. В приведённом ниже примере кода строки с вызовом метода Update выделены серым.

Using the Update method to refresh the Status Bar:

Procedure TConverterForm.loadbuttonClick(Sender: TObject);
Var
   I, J : Integer;
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
            For J := 0 to Image1.Picture.Height – 1 Do
                For I := 0 to Image1.Picture.Height – 1 Do
            Begin
                If Image1.Canvas.Pixels[I,J] <> clWhite Then
                    Image1.Canvas.Pixels[I,J] := clBlack;
            End;
        End;

        ScalingFactorChange(Nil);

        convertbutton.Enabled  := True;
        LoadButton.Enabled     := False;
        XStatusBar1.SimpleText := '  Ready...';
        XStatusBar1.Update;
    End;
End;

См. скриптовый проект PCB Logo Creator, расположенный в папке Scripts\Delphiscript Scripts\PCB\PCB Logo Creator загружаемой коллекции скриптов .