Contact our corporate or local offices directly.
Parent page: DelphiScript
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
Timernon-visual component can be used to activate specific code at scheduled intervals, and it is never seen by the user.
Memocomponents 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:
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
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.
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
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).
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
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.
Procedure RunDialog; Begin DialogForm.ShowModal; End;
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.
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
mrCancel from the
ShowModal method respectively.
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
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.
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.
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.
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.
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
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.
To see a list of properties for a component, select a component and open the Properties tab in the Object Inspector panel.
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.
To see a list of methods for a component, see the Component Reference document.
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.
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
Save Dialogs (
TSaveDialog classes from the Embarcadero Delphi RTL).
The essential points for customizing script forms are:
FormKindto one of the following values;
fkModalis closed, then the form will be a modal form — that is, waiting for user input before proceeding such as closing the form. If
fkServerPanelthen the form will be shown as a Server panel. If
fkNormalthen the form acts as a normal non-modal form.
BorderStyleproperties (the results are visible at runtime).
ClientWidthproperties (note that
ClientWidthrepresent the area within the form's border;
Widthrepresent the entire area of the form).
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.
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.
Contact our corporate or local offices directly.