Scripting Graphical Components

Questo riferimento descrive i componenti grafici supportati per lo scripting e le loro principali proprietà e metodi.

I componenti visivi dei moduli disponibili per l’uso negli script di Altium Designer derivano per la maggior parte dalla Visual Component Library (VCL) di Embarcadero, che è una raccolta di componenti visivi definiti per lo sviluppo di applicazioni Windows usando i linguaggi Delphi e C++.

Sviluppate come libreria di classi visive, le classi VCL discendono dall’oggetto TComponent (a sua volta discendente dall’oggetto radice TObject) in una gerarchia lineare di oggetti. Pertanto, un comune componente di script, come l’oggetto TButton, eredita proprietà, metodi ed eventi dai suoi oggetti ascendenti. In questo caso, la gerarchia delle classi è: TObject → TPersistent → TComponent → TControl → TWinControl → TButtonControl → TButton.

Si noti che i componenti che discendono dall’oggetto TControl sono generalmente componenti visivi (controlli), mentre i componenti comuni che discendono da TWinControl sono per lo più wrapper attorno alla Windows API.

► Vedere Embarcadero RAD Studio VCL per una panoramica dell’architettura e dei componenti VCL.

Quando si crea un Form nell’Editor di script di Altium Designer, ai componenti si accede dal pannello Tool Palette. Gli Script Form hanno un file *.DFM associato che include i dettagli della configurazione del form, la posizione dei suoi componenti e altri attributi: il file si trova nella cartella host del progetto di script. Altium Designer consente di usare i componenti sia con DelphiScript sia con VBScript durante la progettazione degli Script Form.

Il pannello Tool Palette contiene controlli visivi categorizzati che possono essere trascinati su uno Script Form.

Il pannello Tool Palette panel contiene selezioni categorizzate di componenti che possono essere posizionati su uno Script Form. I componenti disponibili sono raccolti in sezioni espandibili nel pannello Tool Palette, categorizzate come Standard, Additional, Win32, System, Dialogs, Altium Standard e Instrument Controls.

I componenti (o “controlli”) disponibili nella Palette sono componenti visivi quando vengono usati in uno script form, il che significa che un utente può vedere un controllo e possibilmente interagire con esso in fase di esecuzione. Tutti i controlli hanno proprietà, metodi ed eventi che descrivono aspetti del loro aspetto, come la proprietà di posizione del controllo, metodi per disegnare o spostare il controllo, ed eventi che rispondono alle azioni dell’utente.

Le proprietà e gli eventi sono disponibili nel pannello Object Inspector panel per il componente del form attualmente selezionato, incluso il form stesso. I metodi sono procedure e funzioni supportate da quel componente.

Panoramica degli Script Form

Script Form

Uno Script Form è l’interfaccia utente principale negli script, anche se esistono altri moduli come finestre di dialogo, finestre secondarie e così via. Per creare un nuovo Script Form, con un progetto aperto in Altium Designer, selezionare File » New » Script » Script Form oppure fare clic con il pulsante destro sul nome del progetto Script e scegliere Add New to Project » Script Form. Se il linguaggio VBScript è abilitato, il comando è disponibile sia per VB Script sia per Delphi Script.

Un nuovo Script Form appare con il nome del form Form1 come predefinito, che può essere modificato tramite la proprietà Name (in Misc) nel pannello Object Inspector. I nomi degli script form devono essere univoci all’interno di un progetto.

Durante la progettazione di uno Script Form, aprire il pannello Object Inspector dal pulsante Script nella barra di stato inferiore.

Un form vuoto è fondamentalmente una finestra visiva alla quale possono essere aggiunti controlli. Una finestra di dialogo e un pannello sono tipi diversi di form e, per impostazione predefinita, un form include funzionalità standard di finestra quali:

• Controlli
• Pulsanti Riduci a icona e Ingrandisci
• Barra del titolo
• Ridimensionabile trascinando il bordo

Queste funzionalità, insieme a qualsiasi altra proprietà disponibile del form, possono essere modificate in fase di progettazione usando il pannello Object Inspector. Poiché uno Script Form è un componente VCL, ha i tre elementi seguenti:

• Properties – Le caratteristiche di un oggetto che influenzano il suo comportamento visibile o le sue operazioni. Ad esempio, la proprietà Visible determina se un oggetto può essere visto su uno script form.
• Events – Azioni o occorrenze rilevate dallo script. Uno script deve includere codice per ciascun gestore di eventi, progettato per intercettare un evento specifico come un clic del mouse.
• Methods – Procedure di script associate agli oggetti (in questo caso oggetti componente) e che ne definiscono il comportamento.

► Vedere Writing Scripts per una guida di base allo sviluppo di uno script basato su form.

Proprietà, metodi ed eventi del Form

I controlli del pannello Tool Palette sono basati sulla Visual Component Library (VCL) di Embarcadero. Per i dettagli completi su metodi, proprietà ed eventi del componente Form (TForm), fare riferimento alla documentazione VCL di Embarcadero.

► Vedere il riferimento Embarcadero TFormSi noti che il collegamento sopra fa riferimento al Embarcadero RAD Studio XE6 della libreria VCL. È disponibile anche la documentazione per le versioni precedenti (fino alla versione 2010).

Proprietà di TForm

Le proprietà disponibili per l’oggetto componente TForm, il form di script di base, possono essere visualizzate nei seguenti modi:

• Tramite il pannello Object Inspector – Nella vista Form dell’editor (scheda Form selezionata), fare clic nel corpo del form stesso e selezionare la scheda Object Inspector's Properties .

Si noti che nel pannello appariranno solo gli oggetti componente visivi. Gli oggetti non visivi, che agiscono come controlli dietro le quinte, non vengono visualizzati sul form.

• Usando la funzione di completamento del codice – Nella vista Code dell’editor (scheda Code selezionata), la finestra di completamento del codice sensibile al contesto mostrerà tutte le opzioni di codice per il nome di un oggetto.Per l’oggetto Form, immettere TForm. (notare il punto) per attivare la finestra. Restringere la ricerca digitando le prime lettere della proprietà desiderata: si noti che vengono mostrate sia le proprietà sia i metodi.
  • Dalla documentazione di riferimento Embarcadero nella pagina di riferimento delle proprietà di TForm.

  Metodi di TForm

  I metodi disponibili per l’oggetto componente TForm possono essere visualizzati nei seguenti modi:

  • Usare la funzione di completamento del codice – Nella vista Code dell’editor, digitare il nome di un componente seguito da un punto. Si aprirà la finestra di completamento del codice per mostrare i metodi di codice (e le proprietà) per il nome di un oggetto. Si noti che la finestra del codice può essere attivata manualmente con i tasti di scelta rapida Crtl+Space.

  

  • Fare riferimento alla documentazione di riferimento Embarcadero nella pagina di riferimento dei metodi di TForm. Si noti che questa mostra tutti i metodi ereditati, tuttavia l’opzione può essere deselezionata.

  Eventi di TForm

  Gli eventi disponibili per l’oggetto componente TForm possono essere visualizzati nei seguenti modi:

  • Il pannello Object Inspector – Nella vista Form dell’editor, fare clic nel corpo del form stesso e selezionare la scheda Events dell’Object Inspector.

  

  • La documentazione di riferimento Embarcadero nella pagina di riferimento degli eventi di TFrom.

  Proprietà, eventi e metodi dei componenti

  I controlli del pannello Tool Palette sono basati sulla Visual Component Library (VCL) di Embarcadero. Per i dettagli completi su metodi, proprietà ed eventi per la maggior parte dei componenti, fare riferimento alle categorie di componenti nella documentazione VCL di Embarcadero. Alcuni tipi di componente nel Tool Palette, in particolare gli Altium Instrument Controls, sono esclusivi di Altium Designer e non sono inclusi nella documentazione di riferimento Embarcadero.

  ► Vedere il Indice delle categorie dei componenti VCL di EmbarcaderoSi noti che il collegamento sopra fa riferimento alla documentazione Embarcadero RAD Studio XE6 per la libreria VCL. È disponibile anche la documentazione per le versioni precedenti (fino alla versione 2010).

  Proprietà dei componenti

  Per vedere un elenco delle proprietà di un componente:

  • Selezionare un componente sul Form e attivare la scheda Properties nel pannello Object Inspector – come mostrato sopra per l’oggetto componente TForm.
  • Selezionare il collegamento Properties (in alto) nella pagina di riferimento del componente appropriato nella documentazione di riferimento Embarcadero. Nel caso del controllo TButton, ad esempio, selezionare la categoria Standard Component, la pagina TButton e quindi la vista Properties.

  Eventi dei componenti

  Per vedere un elenco degli eventi a cui un componente può reagire:

  • Selezionare un componente sul Form e attivare la scheda Events nel pannello Object Inspector – come mostrato sopra per l’oggetto componente TForm.
  • Selezionare una pagina di riferimento del componente appropriata e quindi il relativo collegamento Events nella documentazione di riferimento Embarcadero. Si noti che questo è utile come guida agli eventi disponibili per un componente e potrebbe non corrispondere completamente agli eventi disponibili per i componenti di scripting di Altium Designer.

  Per creare una procedura di gestione eventi, scegliere nella scheda Object Inspector Events l’evento a cui il componente deve reagire e fare doppio clic nel campo di immissione dell’evento. La procedura di gestione eventi, denominata in base al componente e all’azione dell’evento, viene quindi generata automaticamente nello script. Se l’evento viene rinominato nel pannello Object Inspector, anche la corrispondente procedura di codice viene rinominata di conseguenza.

  

  

  Metodi dei componenti

  Fare riferimento alla documentazione Component Categories per informazioni sui metodi disponibili per un componente Tool Palette.

  Questa include riferimenti per le seguenti categorie di oggetti controllo.

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

  Per la maggior parte, queste categorie raggruppano tipi di controlli visivi per form basati su componenti VCL standard di tipo Delphi. Le categorie Altium Standard e Instrument Controls fanno eccezione, poiché offrono componenti esclusivi del sistema di scripting di Altium Designer.

  ► Vedere Tool Palette Component Categories.

  Lavorare con form e componenti

  Personalizzazione degli Script Form

  • Per fare in modo che un form rimanga sopra gli altri pannelli aperti, ad esempio, impostare la proprietà FormStyle su fsStayOnTop.
  • Per definire il comportamento predefinito di un form, impostare FormKind su uno dei seguenti valori: fkNone, fkNormal, fkServerPanel oppure fkModal.
    • Se è selezionato fkModal, il form sarà modale. Vale a dire, un form che attende l'input dell'utente prima di procedere con azioni come la chiusura del form.
    • Se è selezionato fkServerPanel, il form verrà mostrato come pannello Server.
    • Se è selezionato fkNormal, il form si comporta come un normale form non modale.
  • Per aggiungere/rimuovere le barre di scorrimento di un form, modificare il valore delle proprietà HorzScrollBar e VertScrollBar.
  • Per rendere il form una finestra o una finestra figlia MDI (Multiple Document Interface), usare la proprietà FormStyle.
  • Per modificare lo stile del bordo di un form, usare le proprietà BorderIcons e BorderStyle. (I risultati sono visibili in fase di esecuzione.)
  • Per cambiare l'icona del form minimizzato, usare la proprietà Icon.
  • Per specificare la posizione iniziale di un form nella finestra dell'applicazione, usare la proprietà Position.
  • Per specificare lo stato iniziale di un form (ad esempio: minimizzato, massimizzato o normale), usare la proprietà WindowState.
  • Per definire l'area di lavoro di un form in fase di esecuzione, usare le proprietà ClientHeight e ClientWidth. Si noti che ClientHeight e ClientWidth rappresentano l'area all'interno del bordo del form, mentre Height e Width rappresentano l'intera area del form.
  • Per specificare quale controllo ha il focus iniziale in un form in fase di esecuzione, usare la proprietà ActiveControl per scegliere tra i componenti disponibili.
  • Per passare tutti gli eventi della tastiera a un form, indipendentemente dal controllo selezionato, usare la proprietà KeyPreview.
  • Per specificare un menu particolare, se un form contiene più di un menu, usare la proprietà Menu.

  Aggiornare form e componenti

  In alcuni casi l'aspetto visivo di un form di script può non essere aggiornato, ad esempio se un'elaborazione intensiva in background da parte di uno script fa sì che i controlli non vengano aggiornati o ridisegnati e appaiano bloccati o corrotti.

  Il metodo Update del form di script fornisce un modo programmatico per aggiornare il contenuto grafico di un form o di controlli specifici. Nell'esempio di codice seguente, le righe di codice del metodo Update sono evidenziate in grigio.

  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;

  Fare riferimento al progetto di script PCB Logo Creator situato nella cartella Scripts\Delphiscript Scripts\PCB\PCB Logo Creator della raccolta di script scaricabile .