DelphiScript Forms & Components Supported in Altium Designer

Overview of Graphical Components

The scripting system handles two types of components: Visual and Non-visual components.

Visual components are used to build the user interface and the non-visual components are used for different tasks, such as the Timer, OpenDialog and MainMenu components.

• The Timer non-visual component can be used to activate specific code at scheduled intervals, and it is never seen by the user.
• The Button, Edit and Memo components are visual components.

Both types of components appear at design time but non-visual components are not visible at runtime. Components from the Tool Palette panel are object-oriented and have the three following items:

• Properties
• Events
• Methods

A Property is a characteristic of an object that influences either the visible behavior or the operations of this object. For example, the Visible property determines whether this object can be seen or not on a script form.

An Event is an action or occurrence detected by the script. In a script, the programmer writes code for each event handler designed to capture a specific event such as a mouse click.

A Method is a procedure that is always associated with an object and defines the behavior of an object.

All script forms have one or more components. Components usually display information or allow the user to perform an action. For example, a Label is used to display static text, an Edit box is used to allow a user to input some data, a Button can be used to initiate actions.

Any combination of components can be placed on a form, and while the script is running, a user can interact with any component on a form. It is the programmer's task to decide what happens when a user clicks a button or changes the text in an Edit box.

The Scripting system supplies a number of components that can be used to create complex user interfaces for scripts. To place a component on a form, locate its icon on the Tool Palette panel and double-click it. This action places a component on the active form. The visual representation of most components is set with their properties. A component is initially placed in a default position on the form but can be repositioned (dragged) and resized (stretched) as required. You can also change the size and position later using the Object Inspector panel.

When a component is dropped onto a form, the Scripting system automatically generates the code necessary to use the component and updates the script form. Only the properties need to be set and the event handler code implemented to use the desired methods to get the component on the form working.

Designing Script Forms

A script form is designed to interact with the user within the environment. Designing script forms is the core of visual development.

In practice, all components are placed on a script form, and each property that is set is stored in a file describing the form (a *.DFM file) which has a relationship with the associated script code (the *.PAS file). For every script form, there is the .PAS file and its corresponding .DFM file.

When working with a script form and its components, all of the element properties can be inspected and modified using the Object Inspector panel. You can select more than one component by shift-clicking on the components, or by dragging a selection rectangle around the components on the form. A script form has a title (the Caption property on the Object Inspector panel).

Creating a New Script Form

With a script project open, right-click on a project in the Projects panel, click on the Add New to Project item in the pop-up context menu, and choose a Delphi Script Form item. A new script form will open with the default name of EditScript1.pas.

Displaying a Script Form

A script needs to have a procedure that displays the form when the script form is executed. Within this procedure, the ShowModal method can be invoked for the form. The Visible property of the form needs to be false if the ShowModal method of the script form is to work correctly.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

The ShowModal example is a very simple approach to displaying the script form when the RunDialog procedure is invoked. Note that values can be assigned to the components of the DialogForm object before the DialogForm.ShowModal method is invoked.

The ModalResult property example shown below is a bit more complex. The following methods in the script are used for buttons on a script form. The methods cause the dialog to terminate when the user clicks either the OK or Cancel button, which returns mrOk or mrCancel from the ShowModal method respectively.

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;

When the user clicks either button on this script form, the dialog box closes. There is no need to call the Close method, because when the ModalResult method is set, the script engine closes the script form automatically.

Note that if you wish to set the form's ModalResult to Cancel when a user presses the Esc key, use the Object Inspector panel to set the Cancel button's Cancel property to True, or insert Sender.Cancel := True in the form's button CancelButtonClick event handler.

Accepting Input from the User

One of the common components that can accept input from the user is the TEdit component. This component has a field where the user can type in a string of characters. Note that there are other Delphi components such as TMaskEdit, which is an edit component with an input mask stored in a string — this controls or filters the input.

The example below illustrates the process when the user clicks the button after typing something in the edit box. If the user did not type anything in the edit component (blank), the event handler responds with a warning message.

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

Note that a user can change the dialog's input focus using the Tab key or by clicking another control in the form.

Responding to Events

When a button on a form or a component is clicked, the Scripting System responds by receiving an event notification from Altium Designer and calling the appropriate event handler method.

See also
The HelloWorld project from the Scripts\DelphiScript Scripts\General\ folder of the scripts collection.
The ShowModal example script from the Scripts\DelphiScript Scripts\General\ folder of the scripts collection.

Writing Event Handlers

Each component in a form script has a set of event names, and these are used by script event handlers that determine how the script will react to user actions in Altium Designer. For instance, when a user clicks a button on a form, Altium Designer sends a message to the script and the script reacts to this new event. If the OnClick event for a button is specified it is executed.

The code to respond to events is normally contained in DelphiScript event handlers, and all components have a set of events that they can react to. For example, all clickable components have an OnClick event that is fired when a user clicks a component. All such components also have an event for receiving and losing the focus. However, if the code for OnEnter and OnExit has not been specified (OnEnter - the control has received the focus; OnExit - the control has lost the focus) the event will be ignored by a script.

In summary, an event is a link between an occurrence in Altium Designer, such as clicking a button, and a piece of code that responds to that occurrence. The responding code is an event handler. This code modifies property values and calls methods.

Component's Properties

To see a list of properties for a component, select a component and open the Properties tab in the Object Inspector panel.

Component Events

To see a list of events a component can react on, select a component and open the Events tab in the Object Inspector panel. To create an event handling procedure, select the event you want the component to react to and double-click the event name — the scripting system will automatically insert the event handler framework code.

For example, select the TButton component from the Tool Palette panel and drop it on the script form, then double-click next to the OnClick event name in the Object Inspector panel. The scripting system will bring the Code Editor in focus and the skeleton code for the OnClick event will be created.

If a button has a Close method in the CloseClick event handler for example, when the button is clicked the button event handler will capture the OnClick event causing the code inside the event handler to be executed. Consequently, the Close method closes the script form.

In a summary, select a button component either on the form or by using the Object Inspector panel, select the Events page, and double-click the right side of the OnClick event and a new event handler will appear in the script. Alternatively, double-click the button itself, and the scripting system will add a handler for this OnClick event. Note that other types of components will have different default actions.

Component Methods

To see a list of methods for a component, see the Component Reference document.

Dropping Components on a Script Form

To use components from the Tool Palette panel in a script, a script form needs to exist before components can be dropped on the form. Normally when components are dropped on a script form, these objects do not need to be created or destroyed — the script form does this automatically.

The scripting system also automatically generates the code necessary to use a component and updates the script form. Then it's just a matter of setting the properties, putting code in event handlers, and using required methods to implement a working script form.

Creating Components in a Script

Components can be directly created or destroyed in a script by passing a Nil parameter to the Constructor of a component. Normally you don't need to pass in the handle of the form because the script form automatically takes care of it. For example, you can create and destroy Open and Save Dialogs (TOpenDialog and TSaveDialog classes from the Embarcadero Delphi RTL).

Customizing Script Forms

The essential points for customizing script forms are:

• To force a form to stay on the top of other open panels, 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, waiting for user input before proceeding 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 the form's default scroll bars, change the value of the HorzScrollBar and VertScrollBar properties.
• To make the form an MDI frame or MDI child, use the FormStyle property.
• To change the 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 the form (e.g., minimized, maximized, or normal), use the WindowState property.
• To define the working area of the form at runtime, use the ClientHeight and ClientWidth properties (note that ClientHeight and ClientWidth represent the area within the form's border; Height and Width represent the entire area of the form).
• To specify which control has the initial focus in the form at runtime, use the ActiveControl property.
• To pass all keyboard events to 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.

Refreshing Script Forms and Components

When the surface of a script form becomes out of date, where for example, the controls are not updated or repainted, then the controls can look frozen or corrupted — this might be due to intensive background processing from that script.

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

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;

The above code snippet is from the PCB Logo Creator script project, which can be found in the Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator folder of the downloadable scripts collection.