Using VBScript Form Components

Uso dei componenti nei moduli VBScript

Sebbene i moduli e i componenti siano basati sulla Visual Component Library (VCL) di Embarcadero Delphi™, il Tool Palette basato su Delphi di Altium Designer viene ancora utilizzato per inserire i controlli in un modulo quando si usa VBScript. Inoltre, i gestori di eventi vengono generati e il codice viene scritto usando il linguaggio VBScript, indipendentemente dalle origini Delphi di moduli/componenti in Altium Designer.

Panoramica dei componenti

Il sistema di scripting gestisce due tipi di componenti: componenti visivi e componenti non visivi. I componenti visivi vengono utilizzati per creare l'interfaccia utente, mentre i componenti non visivi vengono utilizzati per attività diverse, come le funzioni fornite dai componenti Timer, OpenDialog e MainMenu. Ad esempio, il componente non visivo Timer viene utilizzato per attivare codice specifico a intervalli programmati e non è mai visibile all'utente. I componenti Button, Edit e Memo sono componenti visivi: sono visibili all'utente.

Entrambi i tipi di componenti compaiono in fase di progettazione, ma i componenti non visivi non sono visibili in fase di esecuzione. I componenti del pannello Tool Palette sono orientati agli oggetti e hanno i tre elementi seguenti:

• Proprietà
• Eventi
• Metodi

Una property è una caratteristica di un oggetto che influenza il comportamento visibile oppure le operazioni di questo oggetto. Ad esempio, la proprietà Visible determina se questo oggetto può essere visto in un modulo di script.

Un event è un'azione o un'occorrenza rilevata dallo script. In uno script, il programmatore scrive codice per ciascun gestore di eventi progettato per intercettare un evento specifico, come un clic del mouse.

Un method è una procedura sempre associata a un oggetto e che definisce il comportamento di quell'oggetto.

Tutti i moduli di script hanno uno o più componenti. I componenti di solito visualizzano informazioni oppure consentono all'utente di eseguire un'azione. Ad esempio, una Label viene utilizzata per visualizzare testo statico, una casella Edit viene utilizzata per consentire all'utente di inserire dati, un Button può essere utilizzato per avviare azioni.

Qualsiasi combinazione di componenti può essere posizionata in un modulo, consentendo all'utente di interagire con essi quando lo script è in esecuzione (runtime). È compito del programmatore dello script decidere cosa accade quando un utente fa clic su un pulsante o modifica il testo in una casella Edit.

Il sistema di scripting fornisce una gamma di componenti per creare interfacce utente semplici o complesse per gli script. Tutti i componenti che possono essere posizionati in un modulo si trovano nel pannello Tool Palette.

Per posizionare un componente in un modulo, individuarne l'icona nel pannello Tool Palette e fare doppio clic su di essa. Questa azione inserisce un componente nel modulo attivo nella posizione predefinita, con larghezza e altezza predefinite. La rappresentazione visiva della maggior parte dei componenti è determinata dall'insieme delle proprietà associate.

Un componente inserito, nella sua posizione e dimensione predefinite, può essere ridimensionato o riposizionato usando il mouse oppure tramite il pannello Object Inspector. Quando un componente viene rilasciato in un modulo, il sistema di scripting genera automaticamente il codice di base necessario per utilizzare il componente e aggiorna il modulo di script. Per far funzionare il componente nel modulo, non resta che impostare le proprietà, inserire il codice nei gestori di eventi e usare i metodi secondo necessità.

Progettazione dei moduli di script

Un modulo di script è progettato per interagire con un utente all'interno dell'ambiente Altium Designer. La progettazione dei moduli di script è il nucleo dello sviluppo visuale in Altium Designer.

Ogni componente posizionato in un modulo di script e ogni proprietà impostata vengono memorizzati in un file che descrive il modulo (un file *.dfm) e hanno una relazione con il codice script associato (il file *.vbs). Quindi, per ogni modulo di script, esistono il file *.vbs e il corrispondente file *.dfm.

Quando si lavora con un modulo di script e i suoi componenti, le relative proprietà possono essere consultate e modificate tramite il pannello Object Inspector. È possibile selezionare più componenti facendo Shift+clic sui componenti oppure trascinando un rettangolo di selezione attorno ai componenti nel modulo di script. Un modulo di script ha un titolo associato alla proprietà Caption nel pannello Object Inspector.

Creazione di un nuovo modulo di script

Con un progetto di script aperto, fare clic con il pulsante destro sul progetto nel pannello Projects e selezionare gli elementi Add New to Project e quindi VB Script Form dai menu contestuali. Viene creato un nuovo modulo di script con il nome predefinito EditScript1.vbs . In alternativa, in un progetto *.PrjPCB, selezionare il comando File » New » Script Files » VB Script Form.

Visualizzazione di un modulo di script

Uno script deve avere una routine che visualizzi il modulo quando il modulo di script viene eseguito in Altium Designer. All'interno di questa routine, per il modulo viene richiamato il metodo ShowModal. La proprietà Visible del modulo deve essere impostata su false (non selezionata) affinché il metodo ShowModal del modulo di script funzioni correttamente.

Esempio di ShowModal

Sub RunDialog
  DialogForm.ShowModal
End Sub

L'esempio ShowModal sopra riportato è un modo semplice per visualizzare il modulo di script quando viene richiamata la finestra di dialogo RunDialog dallo script. Si noti che è possibile assegnare valori ai componenti dell'oggetto DialogForm prima che venga richiamato il metodo DialogForm.ShowModal.

L'esempio ModalResult mostrato di seguito è più complesso. I metodi successivi vengono utilizzati per i pulsanti nel modulo di script. I metodi dello script fanno terminare la finestra di dialogo quando l'utente fa clic sul pulsante OK o Cancel, restituendo rispettivamente mrOk o mrCancel dal metodo ShowModal.

ModalResult Example

sub bOKButtonClick(Sender)
  ModalResult := mrOK
end sub
 
sub bCancelButtonClick(Sender)
  ModalResult := mrCancel
end sub
 
sub RunShowModalExample
  'Form Visible property must be false for ShowModal to work properly.
  If Form.ShowModal = mrOk     Then ShowMessage("mrOk")
  If Form.ShowModal = mrCancel Then ShowMessage("mrCancel")
end sub

Lo stesso risultato potrebbe essere ottenuto impostando il valore ModalResult su mrOk per il pulsante OK e su mrCancel per il pulsante Cancel nei rispettivi gestori di eventi. Quando l'utente fa clic su uno dei due pulsanti, la finestra di dialogo si chiude. Non è necessario chiamare il metodo Close, perché quando il metodo ModalResult è stato impostato, il motore di scripting chiude automaticamente il modulo di script.

Si noti che, per impostare il valore ModalResult del modulo su cancel quando l'utente preme il tasto Esc, impostare la proprietà Cancel del pulsante Cancel su true (selezionata) nel pannello Object Inspector, oppure inserire Sender.Cancel := True nel gestore di eventi CancelButtonClick del pulsante del modulo.

Accettazione dell'input dell'utente

Uno dei componenti comuni che possono accettare input da un utente è il componente EditBox. Questo componente EditBox ha un campo di testo in cui l'utente può digitare una stringa di caratteri. Esistono anche altri componenti che possono accettare testo, come il componente masked edit, che è un componente edit con una maschera di input per il campo di testo. La maschera controlla, o filtra, l'input ed è memorizzata in una stringa di parametri.

L'esempio seguente illustra cosa accade quando un utente fa clic sul pulsante dopo aver digitato del testo nella casella edit. Si noti che, se l'utente non ha digitato alcun testo nel componente edit, il gestore di eventi risponde con un messaggio di avviso

sub TScriptForm.ButtonClick(Sender)
  If Edit1.Text = "" Then
  ShowMessage("Warning - empty input!")
  Exit
  End
  ' do something else for the input
End sub

Si noti che l'utente può spostare il focus di input nel modulo usando il tasto Tab oppure facendo clic su un altro controllo del modulo.

Risposta agli eventi

Quando un modulo o un componente viene selezionato da un utente, Altium Designer invia un messaggio al sistema di scripting, che risponde alla notifica dell'evento chiamando il metodo del gestore di eventi appropriato.

Scrittura dei gestori di eventi

Uno script potrebbe dover rispondere a eventi che possono verificarsi su un componente in fase di esecuzione. Un evento è un collegamento tra un'occorrenza in Altium Designer, come il clic su un pulsante, e una porzione di codice che risponde a tale occorrenza. Il codice di risposta è un gestore di eventi, che modifica i valori delle proprietà e richiama metodi.

Insieme alle proprietà di un componente, ciascuno dispone di un insieme di nomi di eventi. Il programmatore dello script decide come reagirà alle azioni dell'utente in Altium Designer. Per esempio, quando un utente fa clic su un pulsante in un modulo, Altium Designer invia un messaggio allo script e lo script reagisce a questo nuovo evento: se è specificato l'evento OnClick per un pulsante, esso viene eseguito.

Tutti questi componenti hanno anche un evento per ottenere e perdere il focus. Tuttavia, se il codice per OnEnter e OnExit non è specificato (OnEnter - il controllo ha il focus; OnExit - il controllo perde il focus), l'evento verrà ignorato dallo script.

Proprietà dei componenti

Per vedere un elenco delle proprietà di un componente, selezionare un componente e attivare la scheda Properties nel pannello Object Inspector.

Eventi dei componenti

Per vedere un elenco degli eventi a cui un componente può reagire, selezionare un componente e attivare la scheda Events nel pannello Object Inspector. Per creare una procedura di gestione eventi a cui un componente possa reagire, scegliere un evento adatto e fare doppio clic sul suo nome.

Ad esempio, selezionare il componente Button1 dal pannello Tool Palette, inserirlo nel modulo di script e fare doppio clic accanto al nome dell'evento OnClick. Il sistema di scripting riporterà il focus all'Editor di codice, dove sarà stato creato il codice scheletro per l'evento OnClick. Se un pulsante ha un metodo Close nel proprio gestore di eventi CloseClick, quando si fa clic sul pulsante il relativo gestore intercetta l'evento di clic e viene eseguito il codice all'interno del gestore di eventi. Vale a dire, il metodo Close chiude il modulo di script.

In sintesi, un gestore di eventi viene creato in uno script selezionando un componente nel modulo, oppure con il pannello Object Inspector, e quindi facendo doppio clic a destra dell'evento desiderato (ad esempio, OnClick) nella scheda Events dell'Inspector: nel codice dello script apparirà la struttura appropriata.

In alternativa, facendo doppio clic su un pulsante, il sistema di scripting aggiungerà un gestore per un evento OnClick. Altri tipi di componenti avranno azioni predefinite completamente diverse.

Metodi dei componenti

Vedere il Riferimento dei componenti per un elenco dei metodi di un componente e fare riferimento alla documentazione di Embarcadero Delphi per informazioni più dettagliate.

Creazione di componenti in fase di esecuzione

I componenti possono essere creati e distrutti direttamente in uno script. Normalmente non è necessario passare l'handle del form, perché il form dello script se ne occupa automaticamente — al suo posto, passare un parametro Nil al costruttore del componente.

Ad esempio, le finestre di dialogo Open e Save possono essere create e distrutte (le classi TOpenDialog e TSaveDialog, come parte della RTL di Delphi).