Moduli e componenti

Panoramica dei componenti grafici

Il sistema di scripting gestisce due tipi di componenti: componenti visivi e non visivi.

I componenti visivi vengono utilizzati per costruire l'interfaccia utente, mentre i componenti non visivi vengono utilizzati per attività diverse, come i componenti Timer, OpenDialog e MainMenu.

• Il componente non visivo Timer può essere utilizzato per attivare codice specifico a intervalli programmati e non è mai visibile all'utente.
• I componenti Button, Edit e Memo sono componenti visivi.

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 o meno in un modulo di script.

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

Un Method è una procedura sempre associata a un oggetto e definisce il comportamento di un oggetto.

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

Qualsiasi combinazione di componenti può essere posizionata in un modulo e, mentre lo script è in esecuzione, un utente può interagire con qualsiasi componente del modulo. È compito del programmatore decidere cosa accade quando un utente fa clic su un pulsante o modifica il testo in una casella Edit.

Il sistema di scripting fornisce un certo numero di componenti che possono essere utilizzati per creare interfacce utente complesse per gli script. Per posizionare un componente in un modulo, individua la sua icona nel pannello Tool Palette panel e fai doppio clic su di essa. Questa azione posiziona un componente nel modulo attivo. La rappresentazione visiva della maggior parte dei componenti viene impostata tramite le relative proprietà. Un componente viene inizialmente posizionato in una posizione predefinita nel modulo, ma può essere riposizionato (trascinato) e ridimensionato (allungato) secondo necessità. È anche possibile modificare successivamente dimensioni e posizione utilizzando il pannello Object Inspector .

Quando un componente viene rilasciato su un modulo, il sistema di scripting genera automaticamente il codice necessario per utilizzare il componente e aggiorna il modulo di script. Per far funzionare il componente nel modulo è necessario solo impostare le proprietà e implementare il codice del gestore eventi per usare i metodi desiderati.

Progettazione dei moduli di script

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

In pratica, tutti i componenti vengono posizionati in un modulo di script e ogni proprietà impostata viene memorizzata in un file che descrive il modulo (un file *.DFM) che ha una relazione con il codice script associato (il file *.PAS). Per ogni modulo di script esistono il file .PAS e il corrispondente file .DFM.

Quando si lavora con un modulo di script e i suoi componenti, tutte le proprietà degli elementi possono essere esaminate e modificate utilizzando il pannello Object Inspector. È possibile selezionare più di un componente facendo Maiusc-clic sui componenti oppure trascinando un rettangolo di selezione attorno ai componenti nel modulo. Un modulo di script ha un titolo (la proprietà Caption nel pannello Object Inspector).

Creazione di un nuovo modulo di script

Con un progetto di script aperto, fai clic con il pulsante destro del mouse su un progetto nel pannello Projects, fai clic sulla voce Add New to Project nel menu contestuale a comparsa e scegli una voce Delphi Script Form. Si aprirà un nuovo modulo di script con il nome predefinito EditScript1.pas.

Visualizzazione di un modulo di script

Uno script deve avere una procedura che visualizzi il modulo quando il modulo di script viene eseguito. All'interno di questa procedura, è possibile richiamare il metodo ShowModal per il modulo. La proprietà Visible del modulo deve essere false affinché il metodo ShowModal del modulo di script funzioni correttamente.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

L'esempio ShowModal è un approccio molto semplice per visualizzare il modulo di script quando viene richiamata la procedura RunDialog. Si noti che è possibile assegnare valori ai componenti dell'oggetto DialogForm prima che venga richiamato il metodo DialogForm.ShowModal.

L'esempio della proprietà ModalResult mostrato di seguito è un po' più complesso. I seguenti metodi nello script vengono utilizzati per i pulsanti di un modulo di script. I metodi 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:

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;

Quando l'utente fa clic su uno dei due pulsanti in questo modulo di script, la finestra di dialogo si chiude. Non è necessario chiamare il metodo Close, perché quando il metodo ModalResult è impostato, il motore di scripting chiude automaticamente il modulo di script.

Si noti che, se si desidera impostare il valore ModalResult del modulo su Cancel quando un utente preme il tasto Esc , utilizzare il pannello Object Inspector  per impostare la proprietà Cancel del pulsante Cancel su True, oppure inserire Sender.Cancel := True nel gestore eventi CancelButtonClick del pulsante del modulo.

Accettazione dell'input dell'utente

Uno dei componenti comuni che possono accettare input dall'utente è il componente TEdit. Questo componente dispone di un campo in cui l'utente può digitare una stringa di caratteri. Si noti che esistono altri componenti Delphi come TMaskEdit, che è un componente di modifica con una maschera di input memorizzata in una stringa: questa controlla o filtra l'input.

L'esempio seguente illustra il processo quando l'utente fa clic sul pulsante dopo aver digitato qualcosa nella casella di modifica. Se l'utente non ha digitato nulla nel componente di modifica (vuoto), il gestore eventi risponde con un messaggio di avviso.

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

Si noti che un utente può cambiare il focus di input della finestra di dialogo utilizzando il tasto Tab oppure facendo clic su un altro controllo nel modulo.

Risposta agli eventi

Quando si fa clic su un pulsante in un modulo o su un componente, il sistema di scripting risponde ricevendo una notifica di evento da Altium Designer e chiamando il metodo del gestore eventi appropriato.

See also
Il progetto HelloWorld dalla cartella Scripts\DelphiScript Scripts\General\ della raccolta di script .
Lo script di esempio ShowModal dalla cartella Scripts\DelphiScript Scripts\General\ della raccolta di script .

Scrittura dei gestori eventi

Ogni componente in uno script di modulo ha un insieme di nomi di eventi e questi vengono utilizzati dai gestori eventi dello script che determinano come lo script reagirà alle azioni dell'utente in Altium Designer. Ad 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.

Il codice per rispondere agli eventi è normalmente contenuto nei gestori eventi DelphiScript e tutti i componenti hanno un insieme di eventi ai quali possono reagire. Ad esempio, tutti i componenti cliccabili hanno un evento OnClick che viene attivato quando un utente fa clic su un componente. Tutti questi componenti hanno anche un evento per ricevere e perdere il focus. Tuttavia, se il codice per OnEnter e OnExit non è stato specificato (OnEnter - il controllo ha ricevuto il focus; OnExit - il controllo ha perso il focus), l'evento verrà ignorato da uno script.

In sintesi, 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 eventi. Questo codice modifica i valori delle proprietà e richiama metodi.

Proprietà del componente

Per vedere un elenco di proprietà di un componente, seleziona un componente e apri la scheda Properties nel pannello Object Inspector.

Eventi del componente

Per vedere un elenco di eventi a cui un componente può reagire, seleziona un componente e apri la scheda Events nel pannello Object Inspector. Per creare una procedura di gestione eventi, seleziona l'evento a cui vuoi che il componente reagisca e fai doppio clic sul nome dell'evento: il sistema di scripting inserirà automaticamente il codice framework del gestore eventi.

Ad esempio, seleziona il componente TButton dal pannello Tool Palette e rilascialo nel modulo di script, quindi fai doppio clic accanto al nome dell'evento OnClick nel pannello Object Inspector . Il sistema di scripting porterà in primo piano l'Editor del codice e verrà creato il codice scheletro per l'evento OnClick.

Se un pulsante ha, ad esempio, un metodo Close nel gestore eventi CloseClick, quando si fa clic sul pulsante il gestore eventi del pulsante intercetterà l'evento OnClick, causando l'esecuzione del codice all'interno del gestore eventi. Di conseguenza, il metodo Close chiude il modulo di script.

In sintesi, seleziona un componente pulsante nel modulo oppure utilizzando il pannello Object Inspector, seleziona la pagina Events e fai doppio clic sul lato destro dell'evento OnClick; nel codice dello script apparirà un nuovo gestore eventi. In alternativa, fai doppio clic direttamente sul pulsante e il sistema di scripting aggiungerà un gestore per questo evento OnClick. Si noti che altri tipi di componenti avranno azioni predefinite diverse.

Metodi del componente

Per vedere un elenco di metodi di un componente, consulta il documento Component Reference.

Rilascio dei componenti in un modulo di script

Per utilizzare i componenti del pannello Tool Palette panel in uno script, è necessario che esista prima una form di script, così che i componenti possano essere rilasciati sulla form. Normalmente, quando i componenti vengono rilasciati su una form di script, questi oggetti non devono essere creati o distrutti, poiché la form di script lo fa automaticamente.

Il sistema di scripting genera inoltre automaticamente il codice necessario per utilizzare un componente e aggiorna la form di script. A quel punto si tratta semplicemente di impostare le proprietà, inserire il codice nei gestori di eventi e usare i metodi richiesti per implementare una form di script funzionante.

Creazione di componenti in uno script

I componenti possono essere creati o distrutti direttamente in uno script passando un parametro Nil al Constructor di un componente. Normalmente non è necessario passare l'handle della form perché la form di script se ne occupa automaticamente. Ad esempio, è possibile creare e distruggere finestre di dialogo Open e Save (TOpenDialog e TSaveDialog classi della RTL Delphi di Embarcadero).

Personalizzazione delle form di script

I punti essenziali per personalizzare le form di script sono:

• Per forzare una form a rimanere sopra gli altri pannelli aperti, impostare la proprietà FormStyle su fsStayOnTop.
• Per definire il comportamento predefinito di una form, impostare FormKind su uno dei seguenti valori: fkNone, fkNormal, fkServerPanel o fkModal.
• Se fkModal è chiuso, la form sarà modale, cioè attenderà l'input dell'utente prima di procedere, ad esempio prima di chiudere la form. Se fkServerPanel, la form verrà mostrata come pannello Server. Se fkNormal, la form si comporta come una normale form non modale.
• Per rimuovere le barre di scorrimento predefinite della form, modificare il valore delle proprietà HorzScrollBar e VertScrollBar.
• Per rendere la form un frame MDI o una finestra figlia MDI, usare la proprietà FormStyle.
• Per modificare lo stile del bordo della form, usare le proprietà BorderIcons e BorderStyle (i risultati sono visibili in fase di esecuzione).
• Per cambiare l'icona della form minimizzata, usare la proprietà Icon.
• Per specificare la posizione iniziale di una form nella finestra dell'applicazione, usare la proprietà Position.
• Per specificare lo stato iniziale della form (ad esempio, minimizzata, massimizzata o normale), usare la proprietà WindowState.
• Per definire l'area di lavoro della form in fase di esecuzione, usare le proprietà ClientHeight e ClientWidth (si noti che ClientHeight e ClientWidth rappresentano l'area all'interno del bordo della form; Height e Width rappresentano l'intera area della form).
• Per specificare quale controllo ha il focus iniziale nella form in fase di esecuzione, usare la proprietà ActiveControl.
• Per inoltrare tutti gli eventi della tastiera alla form, indipendentemente dal controllo selezionato, usare la proprietà KeyPreview.
• Per specificare un menu particolare, se una form contiene più di un menu, usare la proprietà Menu.

Aggiornamento delle form di script e dei componenti

Quando la superficie di una form di script non è aggiornata, ad esempio quando i controlli non vengono aggiornati o ridisegnati, i controlli possono apparire bloccati o corrotti: ciò potrebbe essere dovuto a un'elaborazione intensiva in background da parte di quello script.

Il metodo Update della form di script, e molti componenti di script del pannello Tool Palette , forniscono un modo per aggiornare il contenuto grafico della form o dei controlli specifici. Le righe contenenti il metodo Update sono evidenziate in grigio nell'esempio seguente.

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;

Il frammento di codice sopra riportato proviene dal progetto di script PCB Logo Creator, che si trova nella cartella Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator della raccolta di script scaricabile.