Component Reference

Parent page: Scripting

This reference outlines the supported graphical components for scripting and their main properties and methods.

The visual form components available for use in Altium Designer scripts are mostly derived from Embarcadero's Visual Component Library (VCL), which is a collection of defined visual components for developing Windows applications using Delphi and C++ languages.

Developed as a visual class library, the VCL classes descend from the TComponent object (itself a descendant from the TObject root object) in a linear object hierarchy.

Thus a common script component, such as the TButton object, inherits the properties, methods and events from its ascending objects. In this case the class hierarchy is: TObject → TPersistent → TComponent → TControl → TWinControl → TButtonControl → TButton.

Note that the components that descend from the TControl object are generally visual components (controls), and common components that descend from TWinControl are mostly wrappers around the Windows API.

When creating a Form in the Altium Designer Script Editor, the components are accessed from the Tool Palette panel. Script Forms have an associated *.DFM file that includes details of the form's configuration, its component locations and other attributes. Altium Designer allows the components to be used by either DelphiScript, VBScript or JScript when designing Script Forms.

The Tool Palette Panel contains categorized visual controls that can be dropped onto a script Form.

The Tool Palette panel (accessed from the Script button on the bottom of the Altium Designer status bar) contains categorized selections of components that can be placed on a Script Form. The components are assembled under the Tool Palette panel's tabs: the Standard, Additional, Win32, System, Dialogs, Altium Standard and Instrument Controls tabs.

The components (or 'controls') available in the Palette are visual components when used on a script form, meaning that a user can see a contol and possibly interact with it at runtime. All controls have properties, methods, and events that describe aspects of their appearance, such as the position property of the control, methods to paint or move the control, and events that respond to user actions.

The properties and events are available in the Object Inspector panel for the currently focused component, including the form itself. The methods are procedures and functions supported by that component.
 

Script Forms Overview

Script Forms

A Script Form is the primary user interface in scripts, although there are other forms such as dialog boxes, secondary windows and so on. To create a new Script Form, with a project open in Altium Designer, select File » New » Script Files and choose a Script Form item in the applicable scripting language.

A new Script Form appears with the EditScript name as the default name, which can be changed through the Name property in the Object Inspector panel. Script form names should be unique in a project.

When designing a script Form, open the Object Inspector Panel from the Script button in the lower status bar.

A blank form is basically a visual window that controls can be added to. A dialog and a panel are different types of forms, and by default, a form includes standard window functionality such as:

• Control menu
• Minimize and Maximize buttons
• Title bar
• Resizable borders

These features, along with any other available form property, can be changed at design time using the Object Inspector panel. Since a Script Form is a VCL component it has the three following items:

• Properties - The characteristics of an object that influence its visible behavior or operations. For example, the Visible property determines whether an object can be seen on a script form.
• Events - Actions or occurrences detected by the script. A script must include code for each Event handler, which is designed to capture a specific event such as a mouse click.
• Methods - Procedures that are is associated with objects (in this case component objects) and define their behavior.

Form Properties, Methods and Events

The Tool Palette panel's controls are based on the Embarcadero Visual Component Library (VCL). For full details on the methods, properties and events for the Form component (TForm), refer to the Embarcadero VCL documentation.

TForm Properties

The available Properties for the TForm component object, the base script form, can be viewed in the following ways:

• Via the Object Inspector Panel - In the editor's Form view (Form tab selected), click in the body of the form itself and select the Object Inspector's Properties tab.
  
  
  Note that only visual component objects will appear in the panel. Non-visual objects, that act as behind the scenes controls, are not displayed on the form.
   
• By using the Code Completion Feature - In the editor's Code view (Code tab selected), the context-sensitive Code Completion window will display all code options for an object name.
  
  
  For the Form object, type TForm. (note the period) to activate the window. Narrow the search by typing the first few letters of a desired property — note that both properties and methods are shown.
   
• From the Embarcadero reference documentation - Selected the Properties link on the TFrom reference page. Note that this shows all inherited Properties, however the option can be deselected.

TForm Methods

The available Methods for the TForm component object can be viewed in the following ways:

• Use the Code Completion Feature - In the editor's Code view, type a component name followed by a period. The Code Completion window will open to display the code methods (and properties) for an object name. Note that the code window can be manually activated with the Crtl+Space shortcut keys.
  
  
   
• Refer to the Embarcadero reference documentation - Select the Methods link on the TFrom reference page.

TForm Events

The available Events for the TForm component object can be viewed in the following ways:

• The Object Inspector Panel - In the editor's Form view, click in the body of the form itself and select the Object Inspector's Events tab.
  
  
   
• The Embarcadero reference documentation - Select the Methods link in the TFrom reference page.
   

Component Properties, Events and Methods

The Tool Palette panel's controls are based on the Embarcadero Visual Component Library (VCL). For full details on the methods, properties and events for the majority of components, refer to the component categories in the Embarcadero VCL documentation. Some Component types in the Tool Palette, in particular the Altium Instrument Controls, are exclusive to Altium Designer and not included in the Embarcadero reference documentation.

Component Properties

To see a list of Properties for a component:

• Select a component on the Form and activate the Properties tab in the Object Inspector panel — as shown above for the TForm component object.
   
• Select the Properties link on the appropriate component reference page in the Embarcadero reference documentation. In the case of the TButton control for example, select the Standard category, the TButton page and then the Properties view.

Component Events

To see a list of Events that a component can react on:

• Select a component on the Form and activate the Events tab in the Object Inspector panel — as shown above for the TForm component object.
   
• Select the Events link on the appropriate component reference page in the Embarcadero reference documentation. Note that this is useful as a guide to available events for a component and may not fully match the events available for the Altium Designer scripting components.

Component Methods

This includes references for the following control object categories.

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

In the most part, these categories collect together types of visual form controls based on standard Delphi-type VCL components. The Altium Standard and Instrument Controls categories are the exception, and offer components that are exclusive to Altium Designer's scripting system.

Working with Forms and Components

Customizing Script Forms

• To make a form stay on top of other open panels for example, set the FormStyle property to fsStayOnTop.
• To define the default behavior of a form, set the FormKind to one of the following values; fkNone, fkNormal, fkServerPanel or fkModal.
• If fkModal is closed, then the form will be a modal form. That is, a form waiting for user input before proceeding with actions such as closing the form. If fkServerPanel then the form will be shown as a Server panel. If fkNormal then the form acts as a normal non-modal form.
• To remove a form's default scroll bars, change the value of the HorzScrollBar and VertScrollBar properties.
• To make the form a MDI (Multiple Document Interface) frame or child, use the FormStyle property.
• To change a form's border style, use the BorderIcons and BorderStyle properties. (The results are visible at runtime.)
• To change the icon for the minimized form, use the Icon property
• To specify the initial position of a form in the application window, use the Position property
• To specify the initial state of a form, (for example; minimized, maximized or normal) use the WindowState property
• To define the working area of a form at runtime, use the ClientHeight and ClientWidth properties. Note that ClientHeight and ClientWidth represent the area within the form's border, whereas Height and Width represent the entire area of the form.
• To specify which control has initial focus in a form at runtime, use the ActiveControl property
• To pass all keyboard events to a form, regardless of the selected control, use the KeyPreview property
• To specify a particular menu, if a form contains more than one menu, use the Menu property.

Refresh Forms and Components

In some instances the visual surface of a script form can become out of date, for example if intensive background processing from a script causes the controls to be not updated or repainted and appear frozen or corrupted.

The Update method of the script form and a number of script components from the Tool Palette provide a way to refresh the graphical contents of a form or specific control(s). In the below code example, the Update method code lines are highlighted in gray.

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;

Refer to the PCB Logo Creator script project located in the Scripts\Delphiscript Scripts\PCB\PCB Logo Creator folder of the downloadable scripts collection.