Google Desktop
 Introduzione al Gadget Sidebar di Google Desktop



Scarica SDK
Forum per gli sviluppatori
Al momento, la restante documentazione è disponibile solo in inglese.

Invia gadget
Introduzione a SDK
Blog di Desktop

Indice

Introduzione

L'API di Google Gadget di Google Desktop comprende oggetti e metodi che consentono di scrivere gadget per la Sidebar (un tempo chiamati "plug-in") in linguaggi di script quali JavaScript o VBScript. In questo documento vengono illustrate le procedure per la scrittura di gadget utilizzando questa API insieme al Gadget Designer di Google Desktop. Designer è un ambiente di sviluppo integrato che permette di progettare l'interfaccia utente dei propri gadget utilizzando componenti a trascinamento, nonché di testare i gadget creati al di fuori della Sidebar.

In questo documento non vengono trattati aspetti dell'API di Google Desktop non connessi ai gadget o agli script quali, ad esempio, le API Indice, Ricerca, Azioni Eventi (Al momento, la restante documentazione è disponibile solo in inglese). Per maggiori dettagli su queste API fai clic sul link corrispondente.

Osservato dalla prospettiva dei file e del contenuto, un gadget basato su script di Google Desktop è costituito da:

  • Un file XML gadget.gmanifest contenente meta-dati sul gadget.
  • Un file main.xml che definisce la visualizzazione principale del gadget. Una visualizzazione è composta dall'interfaccia utente e dagli oggetti che compongono un riquadro visibile del gadget.
  • Se necessario, un file options.xml che definisce la visualizzazione delle opzioni del gadget.
  • Tutti i file JavaScript o VBScript con il codice necessario per implementare la funzionalità del gadget.
  • Tutti i file di immagine necessari, ad esempio quelli per gli elementi dell'interfaccia (pulsanti, caselle di controllo ecc.), le immagini visualizzate nel gadget o le icone associate al gadget.
  • Se necessario, cartelle e file distinti per ogni lingua in cui è disponibile l'interfaccia utente del gadget.

Una volta terminato di scrivere questi file nel Designer, quest'ultimo li comprime insieme nel file gadget_name.gg, dove .gg indica Google Gadget. Se non utilizzi Designer, devi comprimere insieme i file in un file zip e ridenominare quest'ultimo in modo tale che termini con il suffisso .gg.

Per distribuire il tuo gadget, metti a disposizione questo file .gg tramite la pagina http://desktop.google.com/pluginsubmit?hl=it oppure attraverso altri mezzi.

Quando un utente installa un gadget basato su file .gg, l'installazione di Google Desktop provvede a decomprimerlo, installarlo e registrarlo utilizzando le informazioni contenute nel file gadget.gmanifest.

Le versioni di Google Desktop anteriori alla 4.0 NON sono in grado di gestire file .gg. Gli utenti che hanno installato versioni di Google Desktop anteriori alla 4.0 non saranno in grado di utilizzare gadget di tipo .gg. Tuttavia, è possibile convertire plug-in scritti per versioni precedenti in gadget per Google Desktop 4.0 creando i necessari file .xml e .gmanifest e apportando alcune lievi modifiche al codice.

La procedura completa per lo sviluppo e la distribuzione di gadget per la Sidebar basati su script utilizzando il Gadget Designer di Google Desktop è la seguente:

  1. Lancia Gadget Designer di Google Desktop eseguendo il file designer.exe da SDK per Google Desktop.
  2. Fai clic su File->Crea progetto.
  3. Fai doppio clic su Impostazioni progetto nel Riquadro File per richiamare la finestra di dialogo Impostazioni del progetto. Inserisci i dati richiesti. Designer utilizza queste informazioni per scrivere il file gadget.gmanifest.
  4. Trascina gli elementi dell'interfaccia utente che compongono l'interfaccia utente del gadget nel Riquadro Visualizzazione del Designer.
  5. Aggiungi al progetto tutti i file di immagine dell'interfaccia necessari, ad esempio un'immagine per ogni diverso pulsante. A tale scopo, dovrai utilizzare un browser di file esterno quale, ad esempio, Esplora risorse di Windows. Aggiungi i file necessari alla cartella del progetto oppure sovrascrivi il contenuto di file esistenti.
  6. Seleziona, uno alla volta, tutti gli elementi dell'interfaccia utente e imposta i loro i valori di proprietà e di evento sui valori desiderati per il tuo gadget. Premi Ctrl+S per salvare il lavoro.
  7. In alternativa, seleziona Progetto->Aggiungi vista opzioni per aggiungere al tuo gadget una visualizzazione delle opzioni, definita nel file options.xml. Ripeti i passaggi 4-6 della procedura descritta qui sopra, in questo caso per la visualizzazione delle opzioni.
  8. Apri il file main.js (o, se preferisci, crea e apri un file di script diverso), quindi scrivi le funzioni chiamate dagli eventi degli elementi dell'interfaccia. Premi Ctrl+S per salvare il lavoro.
  9. Per testare il tuo gadget, procedi nel seguente modo:
    1. Fai clic sulla scheda in alto Anteprima per visualizzare il tuo gadget completamente operativo nel Riquadro Visualizzazione.
    2. Fai clic su Visualizza->Console di debug per aprire la console di debug. Configura le impostazioni in modo tale da visualizzare i messaggi desiderati, quindi imposta le dimensioni della finestra del Designer in modo tale che sia il Riquadro Visualizzazione che la Console di debug risultino interamente visibili.
    3. Esegui un test del tuo gadget cercando di utilizzare alcune delle sue funzioni.
    4. Se rilevi un errore, prova a correggere il codice o l'interfaccia utente (incluse le proprietà). Salva le modifiche, quindi fai clic su Visualizza->Aggiorna per ripristinare lo stato iniziale del gadget. Esegui nuovamente il test e ripeti la procedura sopra descritta finché non ottieni i risultati desiderati.
    5. Se non rilevi alcun errore, fai clic su Visualizza->Aggiorna per ripristinare lo stato iniziale del gadget. Continua a testare il gadget finché non funziona nel modo desiderato.
  10. Fai clic su Progetto->Crea pacchetto per comprimere tutti i file del progetto in un file zip denominato Nome_progetto.gg.
  11. Per distribuire il tuo gadget, invia il file.gg alla pagina http://desktop.google.com/pluginsubmit?hl=it

Ricordati di salvare regolarmente il lavoro premendo ogni volta Ctrl+S oppure selezionando File->Salva, in modo particolare prima di dare inizio a ogni test del gadget.

Un aspetto importante da segnalare riguardo a Designer è il fatto che questo strumento non possiede una procedura propria per aggiungere file a un progetto, alla relativa cartella o alle relative sottocartelle. Mentre la procedura File->Crea progetto crea una serie di file nello stesso punto visualizzato inizialmente nel riquadro File, non è possibile aggiungere o eliminare file dalla cartella del gadget direttamente da Designer.

Per aggiungere o eliminare file dalla cartella del progetto, utilizza un browser di file esterno come Esplora risorse di Windows. Questa è anche la procedura che devi utilizzare per sovrascrivere qualsiasi file creato con il Gadget Designer, quale, ad esempio, plugin_large.gif, che contiene l'icona grande associata al gadget.

Per iniziare

Per lanciare Gadget Designer di Google Desktop, esegui il file designer.exe incluso in SDK per Google Desktop. Inizialmente Designer avrà l'aspetto dell'immagine riportata qui sulla destra.

Aspetto iniziale di Designer

In Designer i gadget vengono chiamati Progetti. Per iniziare a creare un nuovo gadget, procedi nel seguente modo:

  1. Apri il menu File, quindi fai clic su Crea progetto.
  2. Si aprirà la finestra di dialogo visualizzata qui sulla destra:
  3. Nella parte inferiore del campo Nome file: digita il nome del gadget.
  4. Fai clic sul pulsante Salva.

 Finestra di dialogo Nome nuovo progetto

Una volta attribuito un nome al tuo gadget, Designer crea una cartella per il progetto insieme a diversi file e cartelle (descritti nella sezione File e Riquadro File) per permetterti di iniziare. A questo punto la finestra di Designer ha l'aspetto dell'immagine riportata qui sulla destra.

 Finestra di Designer

Finestra di dialogo Impostazioni del progetto e file gadget.gmanifest

Per richiamare la finestra di dialogo Impostazioni del progetto, fai doppio clic su Impostazioni progetto nel Riquadro File. In questa finestra di dialogo devi inserire le informazioni di base sul tuo gadget che Designer utilizzerà per scrivere il suo file gadget.gmanifest.

 Finestra di dialogo Impostazioni del progetto

File gadget.gmanifest

Nel file obbligatorio gadget.gmanifest sono specificati in formato XML i metadati che descrivono il gadget, nonché i componenti da installare prima della creazione del gadget. La maggior parte dei contenuti può essere specificata tramite la finestra di dialogo Impostazioni progetto. Eventuali modifiche, tuttavia, possono anche essere apportate manualmente.

Il contenuto del file "gadget.gmanifest" include un elemento <gadget>, il quale contiene un parametro minimumGoogleDesktopVersion con un valore corrispondente alla versione più antica di Google Desktop in grado di eseguire il gadget. All'interno di questo elemento è contenuto l'elemento obbligatorio <about> e, eventualmente, un elemento opzionale <install>.

L'elemento <about> può includere i seguenti sottoelementi:

  • <id> : il CLSID del gadget. Obbligatorio
  • <name> : il nome del gadget. Obbligatorio.
  • <description> : una breve descrizione del gadget. Obbligatorio.
  • <version> : il numero di versione del gadget.
  • <author> : l'autore del gadget. Obbligatorio.
  • <authorEmail> : l'indirizzo email per contattare lo sviluppatore.
  • <authorWebsite> : l'URL del tuo sito web.
  • <copyright> : l'avviso sul copyright.
  • <aboutText> : il testo visualizzato nella finestra di dialogo "Informazioni su…" del gadget.
  • <smallIcon> : l'icona di 12x12 pixel visualizzata nella barra del titolo del gadget.
  • <icon> : l'icona di 32x32 pixel visualizzata nella finestra di dialogo "Informazioni su…" e nell'interfaccia utente "Avvisi" (se supportata dal gadget).
  • <eventAPI> : se incluso (non richiede alcun valore, è sufficiente specificare <eventAPI />), permette al gadget di utilizzare l'API Eventi di Google Desktop. La registrazione viene gestita automaticamente.
  • <displayAPI usersNotifier="true"/> : Impostando l'elemento usersNotifier su true, vengono attivate le notifiche per l'interfaccia utente della Sidebar. La registrazione viene gestita automaticamente.
  • <queryAPI allowModifyIndex="true"/> : Impostando l'elemento allowModifyIndex su true, il gadget può utilizzare le notifiche dell'API di ricerca e dell'API Indice. La registrazione viene gestita automaticamente.

È necessario includere, insieme ai relativi valori, gli elementi <id>, <name> e <description>. Inoltre, ti suggeriamo di includere, insieme ai relativi valori, anche gli elementi <version>, <author>, <authorEmail>, <authorWebsite>, <copyright>, <aboutText>, <smallIcon> e <icon>. Un esempio di questo set di elementi, inclusi ma senza specificare alcun valore, è <authorEmail></authorEmail>. Questa soluzione è accettabile, ma non preferibile.

Di seguito viene riportato un esempio di file gadget.gmanifest per il gadget Orologio digitale:



<gadget minimumGoogleDesktopVersion="4.2006.505.0">
  <about>
    <id>5EBA73D8-8A97-47de-A373-2BCBDCA3D539</id>

    <version>1.0.0.0</version>
    <author>Google</author>
    <authorEmail></authorEmail>
    <authorWebsite>http://desktop.google.com/plugins.html</authorWebsite>

    <copyright>Copyright (c) 2006 Google Inc.</copyright>
    <description>Leggi l'ora con un colpo d'occhio. Con un orologio digitale</description>
    <aboutText>&strAboutText</aboutText>
    <smallIcon>gadget_small.gif</smallIcon>

    <icon>gadget_large.gif</icon>
  </about>
</gadget>

All'interno dell'elemento <gadget>, oltre all'elemento obbligatorio <about>, puoi inserire anche un elemento opzionale <install> in cui vengono specificati i componenti del pacchetto, ad esempio i tipi di carattere da installare prima di creare il gadget. Ad esempio: 


<install>
  <font src="mcfont.ttf"/>
</install>

Riquadro File e file

Il Riquadro File contiene le cartelle e i file che vengono compressi nel file zip nome_gadget.gg utilizzato per la distribuzione del gadget. La cartella di livello superiore presenta il nome scelto per il gadget nella finestra di dialogo Impostazioni progetto. Quest'ultima contiene inizialmente due cartelle e cinque file.

  • Cartella 1033: 1033 è l'ID lingua dell'inglese americano. Questa cartella contiene il file strings.xml, dove l'autore e Designer salvano la versione in inglese americano di tutte le stringhe utilizzate nell'interfaccia utente del gadget. Per maggiori informazioni sull'uso di altre lingue, consulta la sezione Internazionalizzazione di questo documento.
  • Impostazioni progetto: fai doppio clic su questo comando per richiamare la finestra di dialogo Impostazioni del progetto.
  • main.js: un file JavaScript predefinito nel quale è possibile scrivere funzioni che implementano il comportamento e la gestione degli eventi del gadget. Facendo doppio clic, il file viene aperto per la modifica nel Riquadro Visualizzazione e viene aggiunta una scheda per la visualizzazione nella parte superiore dello stesso riquadro. Una volta apportate le modifiche al file, salva le modifiche selezionando File->Salva oppure premendo Ctrl+S.
  • main.xml: il file XML che definisce il layout/la visualizzazione dell'interfaccia utente del gadget. Facendo doppio clic su questa voce, viene selezionata automaticamente la scheda main.xml nella parte superiore del Riquadro Visualizzazione e viene visualizzato il contenuto del file main.xml all'interno dello stesso riquadro. Se trascini elementi dell'interfaccia utente nella visualizzazione principale del Riquadro Visualizzazione e imposti i valori delle rispettive proprietà, il contenuto del file cambia automaticamente per rispecchiare le modifiche apportate. Tuttavia, non è possibile modificare direttamente questo file dal Riquadro Visualizzazione. Per modificarlo, è necessario utilizzare un editor di file esterno, quale, ad esempio, Emacs, vim, Blocco note ecc.
  • plugin_large.gif: un file contenente l'immagine dell'icona grande associata al gadget. Sostituisci questo file con un file con lo stesso nome contenente un'icona di dimensioni adatte al tuo gadget (32 x 32 pixel).
  • plugin_small.gif: un file contenente l'immagine dell'icona piccola associata al gadget. Sostituisci questo file con un file con lo stesso nome contenente un'icona di dimensioni adatte al tuo gadget (12 x 12 pixel).
  • Cartella stock_images: contiene file di immagine precaricati relativi a componenti dell'interfaccia utente, quali, ad esempio, pulsanti e caselle di controllo. Normalmente, gli utenti sostituiscono questi file con file di immagine personali oppure li sovrascrivono in modo che il contenuto includa immagini personali.

Tieni presente, in ogni caso, che per aggiungere, eliminare o copiare contenuti nei file visualizzati all'interno del Riquadro File, devi utilizzare un browser di file esterno a Designer, quale, ad esempio, Esplora risorse di Windows. Il Riquadro File deve essere considerato come una semplice immagine visiva del contenuto della cartella del gadget, e non come uno strumento che permette di modificarne i contenuti.

 Riquadro File

Riquadro Visualizzazione

L'area centrale di visualizzazione è costituita inizialmente da un quadrato bianco contenuto all'interno di un quadrato più grande di colore grigio. L'area bianca rappresenta l'aspetto corrente del gadget, ossia costituisce l'oggetto view globale, il quale, all'interno di un file XML, rappresenta l'aspetto generale del gadget. Quando lanci Designer e devi ancora definire gli elementi dell'interfaccia del gadget, il Riquadro Visualizzazione appare vuoto come nello screenshot riportato qui sulla destra. Quando aggiungi contenuti all'area bianca, puoi cambiare le proprietà globali dell'oggetto view, ad esempio, le dimensioni.

Riquadro Visualizzazione

Schede

All'inizio sono presenti in tutto quattro schede attorno all'area centrale "Riquadro Visualizzazione" della finestra, due in alto e due in basso. Abbiamo già illustrato in che modo è possibile aggiungere una scheda main.js in alto aprendo il file dal Riquadro File. In seguito, verranno illustrati altri metodi per aggiungere o rimuovere schede dalla parte superiore.

  • Schede superiori:
    • main.xml: selezionando questa scheda, Designer mostra il contenuto del file main.xml del gadget nell'area del Riquadro Visualizzazione. In funzione della scheda selezionata nella parte inferiore, viene visualizzata l'interfaccia utente del gadget definita dai contenuti XML oppure viene visualizzato il codice XML vero e proprio.
    • Anteprima: visualizza l'interfaccia utente del gadget ed esegue tutti gli script e le funzioni associati agli elementi dell'interfaccia utente. In pratica, ciò consente di eseguire e testare il gadget al di fuori della Sidebar e di Google Desktop. Ad esempio, se il tuo gadget include un pulsante che, quando premuto, esegue una funzione che cambia il colore di sfondo del gadget nel colore successivo dello spettro, in modalità Anteprima puoi premere il pulsante e il colore di sfondo del gadget cambierà (ipotizzando che tu abbia scritto la funzione correttamente). Tieni presente che le schede inferiori scompaiono quando è attiva l'Anteprima.
  • Schede inferiori:
    • Designer: mostra l'interfaccia utente effettiva del gadget.
    • Origine: mostra il codice XML che definisce l'interfaccia utente del gadget
 Schede

Scrittura di file XML di visualizzazione

Designer consente di trascinare gli elementi dell'interfaccia utente e di impostarne le proprietà in una visualizzazione principale o in una visualizzazione delle opzioni. Allo stesso tempo aggiorna automaticamente il file XML (main.xml o options.xml) che descrive quella particolare visualizzazione. Tale aggiornamento include l'aggiunta o la rimozione di elementi XML, l'impostazione di valori delle proprietà ecc.

È possibile anche aprire e modificare i file XML manualmente. Prima di illustrare in che modo si usa Designer per trascinare oggetti e impostare proprietà, esaminiamo il formato dei file XML.

Il riferimento API riportato di seguito mostra le proprietà, i metodi e gli eventi degli elementi che puoi definire in un gadget e le relative visualizzazioni (dove "visualizzazione" indica l'aspetto generale di un riquadro). Puoi utilizzare questi elementi nei file di visualizzazione XML per specificare i componenti, il layout e il comportamento dell'interfaccia del gadget. La visualizzazione principale del tuo gadget è definita dall'elemento <view> nel file XML main.xml, il quale è definito automaticamente da Designer al momento della creazione di un nuovo progetto. Se il tuo gadget ha una visualizzazione delle opzioni, devi includere anche un file options.xml che definisca un elemento <view> diverso. La definizione <view> contiene al proprio interno elementi XML che definiscono gli oggetti dell'interfaccia utente che compongono la visualizzazione. Ad esempio, un file main.xml può contenere:

<view width="200" height="200">

<button image="button.png" overImage="button_over.png"
downImage="button_down.png" onclick="button_clicked()"/>

</view>

Questo codice definisce una visualizzazione a 200x200 pixel contenente un pulsante. Impostando le proprietà dell'oggetto button, vengono specificate inoltre immagini distinte del pulsante rispettivamente per lo stato normale, per lo stato al passaggio del cursore e per lo stato al momento del clic del mouse. Attraverso l'evento onclick del pulsante, quando un tente fa clic su un pulsante, richiama la funzione button_clicked(), definita in un altro punto.

Per specificare una proprietà in un file XML, aggiungi property="value" a un elemento. Puoi specificare uno scriptlet dell'evento in XML aggiungendo event="script" all'elemento. Come nel DHTML, è possibile manipolare gli elementi di uno script una volta che questi sono stati creati... ma solamente se presentano una proprietà name. Ad esempio:

<button name="sample_button" ... />

Quando un elemento ha un nome, gli script possono accedervi e manipolarlo, nonché chiamare qualsiasi metodo ad esso associato:

sample_button.property = "nuovo valore";
sample_button.event = "nuovo script";
sample_button.method();

È possibile utilizzare funzioni script definite altrove nel file compresso .gg, incluse all'interno di file .js or .vbs dedicati (come ad esempio la funzione button_clicked() utilizzata nel pulsante nell'esempio riportato sopra) oppure includere funzioni implementate tramite script all'interno della definizione <view>. Ad esempio:


<view width="200" height="200" onopen="view_onopen()">
 <script language="jscript"><!--
  function view_onopen()
  {
    foo( "bar()", 1000 );
  }

  function bar()
  {
    x = 2 + 2;
  }

 --></script>

 <div background="#FFFFFF" width="200" height="200"/>
</view>

È possibile definire un solo oggetto contentArea all'interno di un oggetto view. Consulta il Riferimento API per maggiori dettagli su contentArea.

Gestione degli eventi del gadget

Il modello dell'evento gadget è simile a quello del DHTML. Per alcuni oggetti, più precisamente view e basicElement e alcuni dei loro oggetti figli, viene riportato di seguito un elenco di eventi associati nella sezione Riferimento API. Per specificare in che modo deve essere gestito un evento di uno di questi oggetti, è necessario specificare l'evento e la funzione da eseguire nella definizione XML dell'oggetto. Ad esempio, per specificare che cosa accade quando un oggetto view riceve un evento onmouseover, devi scrivere:

<view onmouseover="do_something_when_mouse_is_over;"/>

...dove do_something_when_mouse_is_over è una porzione di script, ad esempio alert('mouse over!'), o la chiamata di una funzione implementata in un blocco script, ad esempio, view_onmouseover().

Come nel DHTML, gli eventi e i relativi gestori non hanno argomenti. Lo script utilizza invece l'oggetto view.event per conoscere le caratteristiche dell'evento. Dal momento che è possibile eseguire un solo evento alla volta, un oggetto event di una visualizzazione contiene informazioni sull'evento eseguito in quel momento.

La proprietà event.returnValue può essere utilizzata per impostare un valore da restituire. Come nel DHTML, questo valore è un operatore booleano che determina se viene eseguito il comportamento predefinito dell'evento. Ad esempio:

event.returnValue = false; // disattiva il comportamento predefinito
event.returnValue = true; // attiva il comportamento predefinito
// non specifica un valore da restituire, attiva il comportamento predefinito

In particolare, la proprietà event.returnValue può avere uno dei due seguenti valori da restituire:

  • view.event.returnValue = false; //Disattiva il comportamento predefinito dell'evento visualizzazione
  • view.event.returnValue = true; //Attiva il comportamento predefinito dell'evento visualizzazione

Ad esempio: 


    <edit onkeypress="edit_onkeypress()"/>
    function edit_onkeypress()
    {
     if( event.keyCode == 'j' ) event.returnValue = false;
    }

Ogni qualvolta premi un tasto mentre il controllo si trova all'interno di questo oggetto edit, viene chiamata la funzione edit_onkeypress(). Se il tasto premuto è j, dal momento che event.returnValue è impostato su false, l'evento e il suo consueto valore da restituire vengono annullati, come se, in pratica, il tasto j non fosse mai stato premuto. Infatti, l'elemento <edit> non consente di digitare il carattere "j".

Gestione di eventi basati su oggetti anteriori alla versione 4.0

Il set di oggetti corrente del gadget include alcuni oggetti di versioni anteriori alla 4.0. Alcuni di questi oggetti, in modo particolare googleTalk e contentItem, hanno un modello di gestione degli eventi diverso da quello descritto qui sopra. Nel Riferimento API riportato di seguito essi sono associati a gestori di eventi anziché semplicemente a eventi.

Per gestire un evento utilizzando oggetti anteriori alla versione 4.0, è necessario impostare una funzione gestore per quello specifico evento. Questi funzioni gestore possono essere impostate unicamente all'interno blocchi JavaScript o VBScript, non all'interno di definizioni XML, come per gli oggetti 4.0.

I gestori di eventi sono di sola scrittura. L'unica operazione possibile con i gestori eventi è quella di assegnare loro una funzione. Se non imposti un gestore particolare, verrà eseguita l'azione predefinita in risposta all'evento associato. Nelle descrizioni riportate nella sezione Riferimento API viene specificata una firma prototipo per ciascun gestore di eventi; la funzione assegnata a un particolare gestore di eventi deve corrispondere alla firma prototipo.

Esaminiamo adesso i componenti più importanti del codice di esempio Opzioni e menu per vedere un esempio pratico dell'utilizzo di un gestore di eventi.


    // le proprietà del gadget che vengono impostate, simile all'esempio Ciao a tutti.
    // ...
    // Associa l'evento dell'oggetto del gadget onAddCustomMenuItems a
    // una funzione definita nello script.
    plugin.onAddCustomMenuItems = AddCustomMenuItems;  // gestore per aggiungere voci di menu    

    // ...

    function AddCustomMenuItems(menu) {
      // Aggiunge i diversi layout delle voci come voci di
			// menu e verifica quello selezionato al momento
      var itemLayout = options.GetValue("item_layout");
      for (var i = 0; i < menuItems.length; ++i) {
        if (i == itemLayout) {
          menu.AddItem(menuItems[i], gddMenuItemFlagChecked, MenuItemClicked);
        } else {
          menu.AddItem(menuItems[i], 0, MenuItemClicked);
        }
      }    
    }

    // ...

In questo caso assegniamo la funzione AddCustomMenuItems all'evento onAddCustomMenuItems dell'oggetto plugin. Nota che il valore assegnato è costituito solamente dal nome della funzione e non dalla firma completa del parametro. Questo evento si verifica quando la Sidebar inizializza il menu del gadget prima di visualizzarlo.

Il prototipo indicato per AddCustomMenuItems è AddCustomMenuItems(menu), pertanto la funzione da noi assegnata deve prendere analogamente un unico argomento, un oggetto menu.

Introduzione agli oggetti

In questa sezione verranno presi in esame diversi oggetti. Illustreremo a che cosa servono e in che modo essi sono in relazione tra loro.

    Oggetto gadget

gadget viene utilizzato per due scopi molto diversi a livello generale di gadget.

  • I metodi gadget.debug aiutano nell'operazione di debug visualizzando la stringa desiderata nella console di debug quando è attivata la modalità debug.

    Per l'esecuzione in modalità debug, decomprimi il gadget, quindi nel file decompresso, fai doppio clic sul file gadget.gmanifest. Ciò ti consente di sviluppare il gadget senza doverlo zippare ogni volta che desideri testarlo.

    I messaggi di debug vengono visualizzati nella console di debug solamente quando il gadget viene lanciato da una cartella (facendo clic su gadget.gmanifest). Non vengono visualizzati, invece, quando il gadget viene lanciato dal file .gg. I messaggi vengono visualizzati nella console di debug di Designer o nel file gdpconsole.exe fornito con SDK per Google Desktop.

  • I metodi gadget.storage funzionano insieme ai file che compongono il pacchetto complessivo del gadget. Questi metodi consentono di estrarre o aprire un file del pacchetto. Gli argomenti dei nomi di file per l'oggetto archiviato possono essere i seguenti:
    • "foo.xml" cerca foo.xml nella cartella principale del file .gg. Se non riesce a trovarlo, cerca nelle cartelle di localizzazione (ad es. 1033\foo.xml).
    • "subfolder\foo.xml" cerca foo.xml nella cartella subfolder del file .gg. Se non riesce a trovarlo, cerca nella cartella subfolder delle cartelle di localizzazione (ad es. 1033\subfolder\foo.xml).
    • "c:\bar.xml" cerca bar.xml nell'unità c:\. Devi specificare il percorso esatto.

    Oggetto view

Devi definire un oggetto view per ciascun aspetto generale del riquadro proprio del gadget. Ciascuno di essi deve essere contenuto in un file .XML distinto. Quando crei un progetto, Designer crea automaticamente un file main.xml con un oggetto view. Inoltre, può creare un file options.xml con il relativo oggetto view.

Le proprietà e i metodi di view definiscono e permettono di determinare il comportamento generale di un riquadro di visualizzazione. Ad esempio, è possibile determinare quali elementi devono far parte dell'aspetto del riquadro, le dimensioni del riquadro, se il riquadro può essere ridimensionato dall'utente, i timer che controllano l'esecuzione dello script, l'aggiunta o la rimozione di elementi dell'interfaccia utente e la visualizzazione di una casella per i messaggi o di conferma.

Gli eventi view attivano ed eseguono una funzione a seguito di diverse azioni (uso del pulsante del mouse, dei tasti, ridimensionamento, cambiamento di valori delle proprietà o uso del cursore), e, inoltre, quando questa visualizzazione viene aperta per la prima volta.

    basicElement e oggetti dell'interfaccia utente

basicElement è l'oggetto padre dei diversi elementi dell'interfaccia utente che compongono l'aspetto esteriore di una particolare visualizzazione. basicElement in sé non viene mai istanziato; esso fornisce semplicemente un set di proprietà ed eventi comuni per gli oggetti figli dell'interfaccia utente.

Le proprietà specificano le dimensioni e la posizione dell'elemento, il nome, la visibilità e l'opacità ed altre proprietà generali dell'elemento dell'interfaccia utente.

Gli eventi sono quelli comunemente associati a un oggetto dell'interfaccia utente: azioni originate da clic o dalla rotella di scorrimento del mouse, trascinamento dell'elemento, ricezione o perdita del focus della tastiera, tasti e movimento del cursore.

È possibile definire i figli di basicElement:

  • button: proprietà specifiche permettono di impostare immagini diverse per il pulsante e per i suoi diversi stati.
  • checkbox: proprietà specifiche permettono di impostare immagini diverse per la casella di controllo e i suoi diversi stati e di determinare se la casella è selezionata oppure no. Un evento si attiva allorché il valore selezionato della casella cambia.
  • object: un controllo ActiveX incorporato senza finestre. Utilizzato principalmente per incorporare oggetti Windows Media Player.
  • div: utilizzato per impostare colori e immagini di sfondo dell'elemento.
  • edit: proprietà specifiche permettono di controllare l'aspetto del contenuto di testo e impostare o richiamare il contenuto di testo. Un evento si attiva allorché il contenuto cambia.
  • img: proprietà specifiche permettono di impostare l'immagine da visualizzare e di ottenere le sue dimensioni originarie. Inoltre, include un metodo di ridimensionamento delle immagini.
  • label: proprietà specifiche permettono di controllare l'aspetto del testo dell'etichetta e il suo posizionamento/allineamento.
  • a: un oggetto link con proprietà specifiche che permettono di controllare l'aspetto del link e il relativo URL.
  • progressBar: proprietà specifiche che permettono di controllare l'aspetto della barra di avanzamento e dei suoi componenti, nonché un evento che si attiva al cambiamento del valore.

Vi è inoltre l'oggetto elements, che rappresenta un contenitore di oggetti figli di basicElement.

    Oggetto options

Memorizza opzioni e i relativi valori come un dizionario/mappa standard. I due seguenti metodi di impostazione di un valore sono equivalenti:
options("tasto") = "valore";
options.item("tasto") = "valore";

Come per tutti i dizionari, è possibile aggiungere voci in uno dei due seguenti metodi:
options("tasto") = "valore"; // Aggiunge o sostituisce il valore corrente.
options.add("tasto", "valore"); // Aggiunge il valore. Se il valore esiste già, non compie alcuna operazione.

La proprietà defaultValue permette che i tasti restituiscano valori predefiniti se il tasto non possiede un valore effettivo associato ad esso nel dizionario, eliminando così la necessità di controllare manualmente se esiste già un valore per quel tasto. Ad esempio:

options.defaultValue("colore") = "rosso";

Il dizionario restituisce ora "rosso" ogni qualvolta viene richiesto "colore" e "colore" non esiste effettivamente nel dizionario. Ad esempio:

options.defaultValue("colore") = "rosso";
options("colore") = "blu";
debug.trace(options( "colore")); // visualizza "blu"
options.remove("colore");
debug.trace(options("colore")); // visualizza "rosso" (il valore predefinito)
options("trama") = "irregolare";
debug.trace(options("trama")); // visualizza "irregolare"
options.remove("trama");
debug.trace(options("trama")); // visualizza "" (perché non è presente alcun valore predefinito)

    Oggetti anteriori alla versione 4.0 (googleTalk, friend, ContentItem,menu, DetailsView)

Quattro oggetti, googleTalk, friend, ContentItem e menu, ereditati dal modello di sviluppo anteriore alla versione 4.0., sono stati inclusi nel modello di sviluppo della versione 4.0. Ricorda: quando utilizzi gestori di eventi googleTalk o menu nel tuo codice, devi utilizzare il pmodello di gestione eventi anteriore alla versione 4.0. Inoltre, diversamente da altri elementi dell'interfaccia utente, questi non sono elementi figli di basicElement.

Per maggiori informazioni sulla procedura di utilizzo degli oggetti googleTalk e friend per scrivere gadget in grado di comunicare con altri gadget eseguiti su altre macchine, confronta il documento sull'Api di comunicazione della Sidebar di Google Desktop (Al momento, la restante documentazione è disponibile solo in inglese).

Gli oggetti menu e i loro metodi permettono di creare un menu a più voci per il tuo gadget, includendo le funzioni gestore associate da eseguire quando un utente seleziona una voce di menu con il mouse.

Gli oggetti ContentItem vengono trasmessi tra più gadget eseguiti su macchine diverse e possono comporre gli elementi dell'interfaccia utente contenuti in un oggetto contentArea.

DetailsView è una funzione dell'interfaccia utente che consente a un gadget di visualizzare ulteriori informazioni in una finestra/gadget separato all'esterno della Sidebar. I gadget che fanno uso di questa funzione possono ricevere inoltre notifiche ed eventi dalla visualizzazione dettagli.

Spazio dei nomi framework

Lo spazio dei nomi framework permette l'utilizzo di API che colmano il vuoto lasciato da Windows Scripting Host e sono utili per l'implementazione dei gadget. In particolare, gli oggetti framework.* non discendono da basicElement e non appaiono nelle definizioni XML di oggetti dell'interfaccia utente del gadget. framework è essenzialmente uno spazio dei nomi di oggetti simile a .NET utilizzato per eseguire interrogazioni di dati di sistema utilizzati dagli script chiamati da eventi negli oggetti dell'interfaccia utente definiti in XML.

Gli oggetti framework, insieme alle loro proprietà e ai loro metodi, ti consentono di:

  • Visualizzare finestre di dialogo per la selezione del percorso di file.
  • Caricare file di immagine.
  • Conoscere la posizione corrente del cursore.
  • Ottenere informazioni sulla capacità di memoria e sull'utilizzo del sistema.
  • Ottenere informazioni sulle funzionalità wireless e sulla connessione del sistema.
  • Impostare e monitorare contatori per il controllo durante l'esecuzione di codici script.
  • Ottenere informazioni sull'alimentazione e la capacità delle batterie del sistema (capacità totale e capacità residua).
  • Ottenere informazioni sul processore del sistema.
  • Ottenere informazioni sulle dimensioni dello schermo del sistema.

Infine, esistono altri due oggetti definiti utilizzati solamente per tipi inclusi nello spazio dei nomi Framework:

  • point: rappresenta un punto, con proprietà di coordinate x e y.
  • size: rappresenta le dimensioni dell'oggetto, con le proprietà di altezza e larghezza.

A titolo di esempio del modo in cui si possono utilizzare oggetti framework, proviamo a scrivere un gadget di esempio per visualizzare la capacità di batteria residua del tuo computer portatile:


<view width="200" height="200" onopen="view_onopen()">
 <script language="jscript"><!--
  function view_onopen()
  {
    setInterval( "update_battery()", 1000 );
  }

  function update_battery()
  {
    percent_used.innerText = system.power.percentRemaining + "%";
  }

 --></script>

 <div background="#FFFFFF" width="200" height="200"/>

 <label name="percent_used" align="center" valign="middle">0%</label>
</view>

Abbiamo definito una visualizzazione di 200x200 pixel contenente al proprio interno due elementi:

  • un <div> con un colore di sfondo bianco
  • una <label> denominata percent_used con lettura iniziale di 0%.

Quando il gadget viene caricato, si attiva l'evento view::onopen, il quale, a sua volta, chiama view_onopen(). Questa funzione imposta un intervallo tale per cui update_battery() venga chiamato una volta ogni secondo. update_battery() utilizza l'oggetto e la proprietà system.power.percentRemaining dello spazio dei nomi framework per aggiornare innerText dell'elemento percent_used.

Nota che non è stato necessario inserire framework. davanti a system.power.percentRemaining; la scelta di farlo o meno dipende unicamente da te.

Oggetti dell'interfaccia utente a trascinamento

Icone dell'interfaccia utente a trascinamento

Di seguito viene illustrato in che modo definire inizialmente l'interfaccia utente del gadget in Designer. Fai clic con il mouse su uno di questi otto elementi dell'interfaccia utente e trascinalo nell'area di visualizzazione bianca nella posizione in cui desideri che appaia nel tuo gadget. Rilascia il pulsante del mouse. L'elemento dell'interfaccia utente è ora nel gadget ed è anche l'elemento dell'interfaccia utente selezionato al momento. Come per l'elemento dell'interfaccia utente selezionato, le sue proprietà e i suoi valori appaiono nel Riquadro Proprietà sulla destra. Fai clic su un oggetto dell'interfaccia utente nell'area di visualizzazione per renderlo l'oggetto dell'interfaccia selezionato al momento.

Tutti gli oggetti dell'interfaccia utente possiedono le proprietà, i metodi e gli eventi descritti nella sezione Riferimento API. Ricordati che tutti gli oggetti visualizzati qui discendono dall'oggetto basicElement, pertanto verifica l'eventuale presenza di descrizioni di proprietà o eventi non specificati per singoli oggetti. Gli otto elementi dell'interfaccia utente sono:

  • Div: utilizzato per impostare il colore di sfondo del gadget o dell'elemento dell'interfaccia utente, nonché come ponte per l'inserimento o la rimozione programmatica di elementi dell'interfaccia utente dall'elemento contenitore.
  • Image: specifica un'immagine da visualizzare nella visualizzazione.
  • Button: oggetto pulsante.
  • Edit: specifica un'area nella quale l'utente del gadget può modificare il contenuto di testo.
  • Check: oggetto casella di controllo.
  • Link: definisce un link HTML.
  • Text Label: un oggetto etichetta a testo fisso.
  • Content: un oggetto contenente ContentArea. Per maggiori informazioni sul suo utilizzo, consulta il Riferimento API.

Gli elementi dell'interfaccia utente progressbar e object non sono disponibili come elementi a trascinamento di Designer, ma possono essere definiti nel codice XML. Tieni presente che Designer non consente di modificare direttamente i file XML del tuo gadget. A tal fine, devi utilizzare un editor esterno.

Riquadro Elementi

Una volta che sono presenti uno o più elementi dell'interfaccia utente nel Riquadro Visualizzazione, puoi selezionare un elemento in uno di questi due diversi modi:

  • Facendo clic una sola volta su di esso nel Riquadro Visualizzazione.
  • Facendo clic sul relativo nome nel Riquadro Elementi.

Quando un oggetto viene inserito per la prima volta nel Riquadro Visualizzazione, appare come figlio dell'elemento view nel Riquadro Elementi, presentando come unico segno di identificazione il proprio tipo. Se, ad esempio, hai trascinato l'elemento Button nel Riquadro Visualizzazione per due volte, il Riquadro Elementi conterrà due elementi, entrambi contrassegnati da button. Se attribuisci un nome a un elemento, ad esempio Pulsante1, nel Riquadro Elementi apparirà come button (Pulsante1).

Tieni presente che l'unico modo per accedere alle proprietà e agli eventi dell'oggetto view in Designer è quello di fare clic sulla voce view nel Riquadro Elementi.

 Riquadro Elementi

Riquadro Proprietà

Il Riquadro Proprietà mostra le proprietà e i relativi valori dell'oggetto dell'interfaccia utente selezionato al momento. È in questo riquadro che puoi modificare anche i valori delle proprietà dell'oggetto e determinare le funzioni associate ai suoi eventi.

Per modificare il valore di una proprietà, fai clic sul nome o sul valore.Le opzioni di inserimento dipendono dal tipo di proprietà.

  • Nel caso di una proprietà booleana, il valore cambia per creare un piccolo menu a discesa con i valori true e false values. Fai clic sul valore che desideri assegnare alla proprietà.
  • Nel caso di una proprietà con valore di testo o valore numerico, digita il nuovo del valore nell'apposito campo, quindi premi Invio.
    • Alcuni valori di proprietà quali, ad esempio, mask o uno background di div, possono essere rappresentati da una stringa o da un file. Per questo tipo di proprietà appare una piccola casella con 3 punti. Facendo clic sulla casella, si apre una finestra di dialogo Apri file del browser che ti permette di selezionare un file come valore della proprietà. Se invece desideri inserire come valore una stringa, digita la stringa nel campo valore, quindi premi Invio.

Se apporti modifiche, la visualizzazione cambierà riflettendo il nuovo valore della proprietà dell'oggetto dell'interfaccia utente.

Tieni presente che alcune proprietà quali, ad esempio, cursor, presentano un set definito e limitato di valori consentiti. Designer non verifica che il valore immesso sia incluso nel set di valori consentiti della proprietà. Tuttavia, quando tenti di aprire la visualizzazione, si verifica un errore.

Tieni presente, inoltre, che l'oggetto globale view, accessibile tramite la selezione nel Riquadro Elementi, presenta un set di proprietà ed eventi proprio. Se, ad esempio, desideri cambiare le dimensioni della visualizzazione stessa, fai clic su view nel Riquadro Elementi, quindi cambia il valore di height e/o width nel Riquadro Proprietà.

Nel caso di eventi, inserisci nel campo valore il nome di una funzione definita in un file script incluso nel gadget. Ad esempio, nel caso dell'evento onOpen di view, puoi digitare view_onOpen(), una funzione definita in main.js , nel campo del valore.

Riquadro Script

Questo riquadro mostra tutti i file script utilizzati dal gadget nel suo file XML visualizzato al momento. Questi file script verranno compressi in un zip insieme ai file XML e ai file di immagine dell'interfaccia utente una volta completata la creazione del gadget. Per impostazione predefinita è presente inizialmente solo un file main.js, tuttavia è possibile aggiungere altri file script e/o rimuovere il file main.js

Per aggiungere un file script al Riquadro Script, fai clic sull'icona del pezzo di carta sulla sinistra delle tre icone. Si aprirà una finestra di selezione dei file impostata per mostrare solamente file di script, cominciando dalla cartella del gadget. Individua il file script che desideri aggiungere, quindi fai clic su Apri. Tieni presente che il file script deve essere già esistente, affinché possa essere aggiunto. Diversamente dai comandi File->, questo comando copia il file script nella cartella del progetto e fa in modo che Designer lo visualizzi nel Riquadro File. Inoltre, aggiunge una riga <script src="filename" /> a qualsiasi file XML del gadget correntemente attivo nel Riquadro Visualizzazione. Se, ad esempio, main.xml è attivo, viene aggiunta la riga <script src="filename"/> solamente a main.xml e non a options.xml.

Nel Riquadro Script, una volta selezionato uno dei file script facendo clic su di esso, è possibile:

  • Aprire il per modificarlo, facendo clic sull'icona della cartella semiaperta. In questo modo, verrà aggiunta una nuova scheda in alto avente per etichetta il nome del file. Facendo clic su questa nuova scheda, potrai inoltre cambiare il Riquadro Visualizzazione in un riquadro di modifica per modificare il contenuto de file.
  • Rimuovere il file dal Riquadro Script facendo clic sull'icona "X" sulla destra. Nota che lo script verrà rimosso immediatamente senza una finestra di dialogo di conferma e che il file dello script sarà ancora presente nel Riquadro File e verrà zippato insieme al gadget, a meno che tu non lo elimini dalla cartella del gadget utilizzando un browser di file esterno.

Un aspetto importante da sottolineare è che il Riquadro Script non mostra i file script sono archiviati nella cartella del progetto, bensì i file script utilizzati nel file XML di definizione della visualizzazione visualizzato al momento.

Osservando il file main.xml immediatamente dopo che è stato creato selezionando File->Nuovo progetto, esso presenta una riga <script src="main.js" /> nel suo elemento <view>. main.js è presente inoltre nel Riquadro Script e nel Riquadro File.

Se rimuovi main.js dal Riquadro Script, <script src="main.js" /> scomparirà dall'elemento <view>. Ciò significa che la visualizzazione del tuo gadget non conterrà più alcuna informazione sulle funzioni definite nel file. Il file in sé è ancora presente nella cartella del progetto e deve essere rimosso utilizzando un browser di file esterno (se decidi di rimuoverlo), altrimenti verrà zippato nel file .gg insieme agli altri file del progetto.

Tieni presente, infine, che per impostazione predefinita, quando crei un nuovo progetto, main.xml contiene automaticamente la riga <script src="main.js" /> e main.js contiene una definizione per la funzione view_onOpen() utilizzata da main.xml. Se elimini main.js dal Riquadro Script senza specificare una definizione sostitutiva per la funzione o senza riscrivere main.xml in modo tale che non utilizzi più view_onOpen(), ti apparirà un messaggio di errore.

 Riquadro Script

Comandi del menu

Nella parte superiore della finestra di Designer sono presenti cinque comandi, ognuno provvisto di un menu a discesa: File, Modifica, Visualizza, Project e Guida. Esaminiamo adesso ognuno di questi comandi in dettaglio.

 Comandi del menu

      Comandi del menu File

Il menu File è composto da sette comandi:

  • Nuovo progetto: Apre una finestra di dialogo Salva con nome in cui puoi specificare la cartella del progetto e il suo nome. Facendo clic su OK, il nuovo progetto apparirà nella finestra di Designer. Nota: se è già stato visualizzato un progetto nella finestra di Designer, non apparirà un messaggio chiedendo all'utente di salvare il progetto prima di aprire un nuovo progetto. La combinazione di tasti equivalente è Ctrl+Shift+N.
  • Apri progetto: apre una finestra di dialogo di selezione delle cartelle che permette di selezionare una cartella di progetto esistente. Una volta selezionata la cartella desiderata, fai clic OK. Se la cartella selezionata non contiene un file main.xml, apparirà un messaggio di errore a comparsa e l'operazione verrà interrotta. Altrimenti, il progetto selezionato verrà aperto nella finestra di Designer. La combinazione di tasti equivalente è Ctrl+Shift+O.
  • Chiudi progetto: chiude il progetto corrente lasciando la finestra di Designer vuota ad eccezione dei comandi del menu in alto. Nota che non apparirà alcun messaggio chiedendo di salvare il progetto aperto al momento. Questo comando non ha alcuna combinazione di tasti equivalente.
  • Apri: apre browser di file impostato per visualizzare file XML. Se selezioni e apri un file, verrà creata una nuova scheda in alto avente per etichetta il nome del file. Selezionando la nuova scheda, il contenuto dei file verrà visualizzato nell'area del Riquadro Visualizzazione. Nota che il nuovo file non è stato aggiunto alla cartella del gadget, come appare invece nel Riquadro File, in quanto il file non si trova nella cartella del progetto. Per aggiungere un file alla cartella del progetto, utilizza un browser di file esterno come, ad esempio, Esplora risorse di Windows. La combinazione di tasti equivalente è Ctrl+O.
  • Salva: salva tutti i file del gadget aperti. Il salvataggio risulta necessario ogni qualvolta modifichi un file o cambi le proprietà di un oggetto dell'interfaccia utente. La combinazione di tasti equivalente è Ctrl+S.
  • Chiudi: chiude immediatamente qualunque file visibile al momento nel Riquadro Visualizzazione e rimuove la scheda corrispondente in alto. Il file in sé è ancora presente nel Riquadro File. La combinazione di tasti equivalente è Ctrl+F4.
  • Esci: visualizza una finestra pop-up chiedendo all'utente se desidera salvare le modifiche al file main.xml. Dopo aver fatto clic su Sì o No, Gagdet Designer viene chiuso. La combinazione di tasti equivalente è Alt+F4.

Inoltre, tutti i progetti recenti appaiono in una sezione del menu, immediatamente al di sopra del comando Esci. Facendo clic su un progetto recente, il progetto verrà aperto in Designer.

 Comandi del menu File

      Comandi del menu Modifica

Il menu Modifica è composto da sei comandi:

  • Annulla: annulla l'ultima o le ultime operazioni eseguite in Designer, ad esempio cambiamento del valore di una proprietà, spostamento di un oggetto dell'interfaccia utente, creazione di un nuovo oggetto ecc. Puoi annullare retroattivamente più operazioni selezionando in sequenza il comando. La combinazione di tasti equivalente è Ctrl+Z.
  • Ripeti: questo comando appare disattivato, a meno che non sia già stata eseguita un'operazione di annullamento. Selezionando questo comando, l'azione annullata viene eseguita nuovamente. Se hai annullato più operazioni, puoi selezionare questo comando per ripristinare lo stato di Designer. La combinazione di tasti equivalente è Ctrl+Y.
  • Taglia: taglia gli elementi dell'interfaccia utente selezionati nel Riquadro Visualizzazione. La combinazione di tasti equivalente è Ctrl+X.
  • Copia: copia gli elementi dell'interfaccia utente selezionati nel Riquadro Visualizzazione. Nota che, quando copi un oggetto dell'interfaccia utente, viene creata una copia esatta, inclusi tutti i valori delle proprietà. Se, ad esempio, copi un pulsante denominato Pulsante2, la copia avrà anche il valore Pulsante2 come proprietà del nome. I due pulsanti appariranno identici nel Riquadro Elementi. La combinazione di tasti equivalente è Ctrl+C.
  • Incolla: incolla gli elementi dell'interfaccia utente selezionati nel Riquadro Visualizzazione. La combinazione di tasti equivalente è Ctrl+V.
  • Elimina: elimina gli elementi dell'interfaccia utente selezionati nel Riquadro Visualizzazione. Il tasto equivalente è DEL.

 Comandi del menu Modifica

      Comandi del menu Visualizza

Il menu Visualizza è composto da cinque comandi:

  • Aggiorna: aggiorna i vari oggetti e riquadri nella finestra di Designer. Inoltre, cosa ancora più importante, reinizializza tutte le variabili globali e i valori delle proprietà del gadget, per cui ciascun codice del progetto viene eseguito nuovamente dall'inizio. Essenzialmente, questo comando ripristina lo stato originario del gadget, una funzione molto utile quando si deve testare il proprio gadget. Il tasto equivalente è F5.
  • Scheda successiva: seleziona la scheda superiore sulla destra della scheda selezionata al momento. Se al momento è selezionata l'ultima scheda, utilizzando questo comando verrà selezionata la prima scheda. La combinazione di tasti alternativa è Ctrl+Tab.
  • Scheda precedente: seleziona la scheda superiore sulla sinistra della scheda selezionata al momento. Se al momento è selezionata la prima scheda, utilizzando questo comando verrà selezionata l'ultima scheda. La combinazione di tasti alternativa è Ctrl+Shift+Tab.
  • Console di debug: apre una console di debug nella parte inferiore della finestra di Designer (occupando lo spazio precedentemente utilizzato dai consueti contenuti della finestra; ti suggeriamo di ridimensionare la finestra per ripristinare le dimensioni originali degli altri contenuti). A seconda delle caselle di controllo selezionate, appaiono in questa console debug, informazioni, avvisi e/o messaggi di errore generati durante l'anteprima o l'esecuzione del gadget. Puoi scegliere anche se i messaggi debbano includere i relativi dettagli. Per rendere invisibile la console di debug, fai clic nuovamente sulla voce di menu Console di debug.
  • Finestra di anteprima: cambia il Riquadro Visualizzazione in modo che esso visualizzi il gadget in modalità esecutiva, permettendoti così di testare interfaccia utente e funzionamento. Il comando può essere selezionato anche facendo clic sulla scheda superiore Anteprima.

 Comandi del menu Visualizza

      Comandi del menu Progetto

Il menu Progetto è composto da tre comandi:

  • Impostazioni: apre la finestra di dialogo Impostazioni progetto. Il tasto equivalente è F3.
  • Se selezionato, Aggiungi vista opzioni aggiunge un file options.xml al progetto e una scheda options.xml in alto. A quel punto, Aggiungi vista opzioni apparirà disattivato, in quanto è possibile definire solamente un file options.xml per progetto. Una volta selezionato questo comando, devi creare e testare la visualizzazione delle opzioni e la relativa interfaccia utente utilizzando la stessa procedura usata per la visualizzazione principale.
  • Crea pacchetto: comprime i file del gadget in un file Nome_progetto.gg per renderne possibile la distribuzione. Il tasto equivalente è F7.

Comandi del menu Progetto

      Comandi del menu Guida

Il menu Guida è composto da due comandi:

  • Guida utente: apre il documento della Guida in una finestra del browser.
  • Informazioni su: visualizza una finestra pop-up con alcune brevi informazioni su Designer.

Comandi del menu Guida

Comunicazione tra Gadget Sidebar

I gadget della Sidebar possono comunicare con altri gadget di Sidebar in esecuzione su altre macchine alle seguenti condizioni:

  • I gadget devono essere dello stesso tipo. Un gadget Tic-Tac-Toe può comunicare con un altro gadget Tic-Tac-Toe, ma non con un gadget Appunti e viceversa.
  • Tutti gli utenti dei gadget comunicanti devono essere connessi a Google Talk.

Google Talk funge da mezzo di comunicazione tra i gadget delle Sidebar. Se un utente è connesso a Google Talk, un gadget può fornire un elenco degli amici Google Talk dell'utente attualmente online. Una volta ottenuto l'elenco degli amici online, un gadget è in grado di inviare e ricevere dati da un gadget dello stesso tipo in esecuzione su un computer di un amico online. Se un amico non ha installato la Sidebar, un gadget è in grado comunque di inviare un messaggio di testo a quell'amico.

Quando aggiungi funzionalità di comunicazione a un gadget basato su script, devi utilizzare la variabile globale googleTalk sia per inviare dati che per impostare la funzione gestore chiamata quando il gadget riceve i dati.

Quando invii dati, la prima operazione da compiere è quella di creare un riferimento alla proprietà friends di googleTalk, ossia di creare un insieme di oggetti friend rappresentati dagli amici Google Talk online.

Un oggetto friend è costituito da cinque proprietà:

  • name: il nome visibile in Google Talk.
  • user_id: l'ID utente di Google Talk, trasferito sotto forma di parametro contenitore di dati/messaggi ai metodi per l'invio di dati/messaggi.
  • email_address: l'indirizzo email dell'amico.
  • has_sidebar: indicatore booleano che informa se un amico ha installato la Sidebar. Prima di provare a inviare dati a un amico che potrebbe non avere la Sidebar, è necessario verificare questo punto.
  • status: lo stato Google Talk dell'amico, ad esempio online, non disponibile o occupato, rappresentati qui rispettivamente dai valori 0, 1 o 2.

Una volta che lo script possiede l'intero insieme degli amici Google Talk, invia loro dati utilizzando uno dei due seguenti metodi:

  • SendTalkData(friend_id, dati): invia la stringa di dati (con lunghezza massima di 2000 caratteri) all'amico identificato dalla Sidebar dell'friend_id. Più precisamente, invia i dati allo stesso gadget nella Sidebar dell'amico da cui è eseguita la chiamata di metodo.
  • SendTalkText(friend_id, messaggio): invia un messaggio di testo di lunghezza fino a 2000 caratteri all'utente Google Talk con l'friend_id. Questo metodo è utilizzato generalmente quando l'amico non ha installato la Sidebar.

Per poter ricevere dati, devi associare una funzione per gestire i dati con il gestore funzione onReceiveTalkData di googleTalk. La firma della funzione deve essere name(oggetto_amico, stringa_dati). Questa funzione viene chiamata ogni qualvolta il gadget riceve dati. Pertanto, dovrai scriverla in modo tale da poter gestire tutti i tipi di messaggi inviati da un altro gadget.

I gadget basati su script che utilizzano l'API di comunicazione non devono eseguire dati ricevuti, ad esempio chiamando la funzione eval(). Ciò costituisce un problema, in quanto un utente malintenzionato potrebbe modificare il gadget in modo tale da poter inviare uno script da eseguire sul computer di un amico. In questo caso, lo script ricevuto verrebbe eseguito con tutti i privilegi locali dell'utente, avendo quindi accesso a file e risorse locali. Per prevenire questa possibilità, le chiamate eval() vengono controllate per assicurare che esse non analizzino i dati ricevuti.

Per un esempio di comunicazione tra gadget, consulta il codice di esempio del gadget Tic-Tac-Toe incluso nell'SDK.


Interfaccia utente e linee guida sull'usabilità

Quando progetti il tuo gadget, tieni sempre presenti questi principi generali:

  • Mantieni i gadget quanto più possibile semplici e sobri.

    Le dimensioni della Sidebar sono veramente limitate. Pertanto, utilizza solamente lo spazio di cui ha realmente bisogno per visualizzare le tue informazioni. Gli accostamenti di colori più semplici garantiscono un aspetto più chiaro e riducono possibili conflitti estetici con altri gadget.

  • Durante lo sviluppo esegui dei test per verificare il funzionamento.

    Quando sviluppi le funzioni, chiedi ad altri amici o colleghi di testare il tuo gadget. Qualora risultino confusi o difficili da usare, ripensa alcuni aspetti dell'interfaccia utente. In particolare, assicurati che la Guida sia chiara, utile e comprensibile.
    •

Gli utenti si aspettano che l'interazione con i gadget delle Sidebar rimanga uniforme da un gadget all'altro. Nelle seguenti sezioni vengono illustrati alcuni supporti visivi ed azioni più comuni che dovrebbero essere uniformi in tutti i gadget delle Sidebar.


      Struttura generale

Il tuo gadget deve offrire quante più alternative di azione e di informazione possibile. In particolare:

  • offrire la possibilità di selezionare i comandi sia tramite mouse che tramite tastiera, includendo combinazioni di tasti per tutti i comandi del menu.
  • supportare descrizioni dei comandi.
  • All'occorrenza, disporre di un pannello per la visualizzazione dei dettagli e un menu contestuale da aprire con il pulsante destro del mouse con l'elenco delle azioni disponibili.


      Input tramite mouse

Dal momento che gli utenti interagiscono con la maggior parte dei gadget attraverso il mouse, soprattutto l'interfaccia utente basata su input del mouse deve essere uniforme all'interno della Sidebar in modo da evitare confusione. I seguenti supporti visivi indicano agli utenti quale genere di clic supportano i tre principali elementi della finestra.

  • Voci: mostrano il contenuto principale del gadget, ad esempio articoli nel caso di un gadget di news.
    • Un solo clic seleziona una voce e apre la visualizzazione dei dettagli.
    • Un doppio clic apre la voce in una nuova finestra dell'applicazione e seleziona la voce nella Sidebar.
    • Il passaggio del mouse evidenzia temporaneamente la voce.

  • Widget: eseguono qualche tipo di azione quando ricevono un clic (ad esempio, pulsanti, caselle di controllo, stelle ecc.)
    • Un solo clic soltanto! Riserviamo i doppi clic all'apertura delle voci.
    • Gli stati passaggio del mouse e clic del mouse devono presentare un aspetto diverso rispetto allo stato normale.
    • Il loro aspetto deve cambiare nel momento in cui ricevono il clic del mouse (ad esempio un effetto grafico come un'ombreggiatura in tridimensionale).
    • Ciò vale anche per il testo utilizzato come widget, che dovrà differenziarsi dal testo normale.
      • visualizza un'icona accanto al testo selezionabile tramite clic (vedi esempio del pulsante "Rimuovi" di seguito).
      • fa' in modo che lo stato del passaggio del mouse presenti un aspetto "cliccabile" o simile a un pulsante.
    • I widget non sono voci o parti di voci. Facendo clic su un widget, non deve aprirsi la visualizzazione dettagliata di una voce.
    • Crea pulsanti di aspetto identico all'interno della Sidebar utilizzando il parametro supportato DrawItemBackground (impostato con flag diversi) nel testo e nella grafica.
    • Esempi di widget:
        stato normale passaggio del mouse clic del mouse
      casella di controllo
      (gadget elenco attività)      		 casella di controllo allo stato normale casella di controllo al passaggio del mouse casella di controllo al clic del mouse
      pulsante "rimuovi"
      (visualizzazione dettagli)      		 pulsante pulsante pulsante
  • Indicatori di stato: icone o figure che mostrano informazioni secondarie.
    • Se sono parte di una voce, essi ereditano tutti i comportamenti di mouse propri di quella voce
    • La grafica non deve cambiare al passaggio del mouse o al clic del mouse, in quanto questi elementi non sono generalmente selezionabili.
    • Esempi di stato (borsa after-hours, attività di rete, meteo):


Visualizza

      Grafici e icone

  • È necessario fornire un'icona per i gadget di due dimensioni. Il design dell'icona deve essere facilmente comprensibile e appropriato per le funzioni del gadget.

    • 12x12 pixel: viene visualizzata nella barra del titolo del gadget

    • 32x32 pixel: viene visualizzata nella finestra di dialogo Informazioni sul gadget e nell'interfaccia utente (se supportata dal gadget).

  • Le icone del gadget devono essere di 12x12 pixel. Utilizza una forma e una tavolozza di colori semplici per le dimensioni ridotte dell'icona e per aiutare gli utenti a identificare rapidamente il gadget.

  • Il seguente insieme di icone 12x12 viene utilizzato nell'insieme predefinito di gadget della Sidebar. Lo stile delle tue icone devono essere simile a questo, ossia forme arrotondate semplici e gradazioni di un unico colore principale. L'immagine in sé è una rappresentazione in due dimensioni piane del contenuto del gadget. Ogni immagine ha un bordo di 1 pixel in una gradazione del colore principale.

      Colori


  • Utilizza i colori con moderazione. Se ritieni che una tonalità del grigio vada bene, utilizzala.

  • Non utilizzare colori troppo accesi o combinazioni con contrasti molto forti o delicati. Cerca di evitare abbinamenti di colori che possono far insorgere problemi. Ad esempio, nell'immagine di sinistra è stato fatto un buon uso dei colori mentre nell'immagine di destra è difficile distinguere i caratteri.

  • Non affidarti ai colori per indicare le differenze poiché possono causare problemi agli utenti che non distinguono i colori. In questo esempio le variazioni delle quotazioni vengono indicate con colori (rosso/verde) e con testo (+/-).

      Testo

  • Il tipo e le dimensioni del carattere di sistema specificati dall'utente vengono anche utilizzati nella Sidebar per la visualizzazione del testo.

  • Il testo normale è nero, mentre il testo meno importante è blu [#224499 o rgb(34, 68, 153)] o grigio [#666666 o rgb(102, 102, 102)].

  • Se possibile, non utilizzare testo in grassetto poiché spicca troppo rispetto al resto della Sidebar.

Formattazione e layout
I gadget della Sidebar sono disponibili in quattro diverse visualizzazioni: standard, ridotta a icona, estesa e dettagliata.
  • Visualizzazione standard: aspetto normale.

    Se hai un elenco di elementi, quali clip web, puoi utilizzare l'elenco dei layout forniti dall'API. Se visualizzi solo un elemento, ad esempio una foto, utilizza il layout dell'elenco a un elemento. Da una semplice vista al contenuto del gadget dovrebbe essere possibile capirne lo scopo.

    Tieni presente che puoi visualizzare più o meno informazioni a seconda della larghezza della Sidebar. Se possibile, evita di utilizzare le barre di scorrimento e usa una visualizzazione estesa per gli elementi.

    Cerca di rappresentare in modo chiaro e visivo il tipo di elemento. Ad esempio, accanto al nome dei file utilizza l'icona del tipo di file. Per i riepiloghi di testi lunghi, ad esempio email e pagine web, visualizza il titolo nella prima riga insieme ai dettagli sulla data e sull'origine dell'elemento.

    visualizzazione gadget standard

  • Visualizzazione ridotta a icona: solo la barra del titolo.

    Generalmente, nella barra del titolo vengono visualizzati solo il titolo e l'icona del gadget. In luogo del titolo, puoi anche visualizzare a rotazione elementi abbreviati dei gadget, ad esempio titoli e le relative quotazioni.

    visualizzazione gadget ridotta a icona

  • Visualizzazione estesa: visualizzazione completa accanto alla Sidebar.

    Generalmente viene usata per visualizzare un elenco completo degli elementi del gadget, con una barra di scorrimento verticale disponibile in presenza di un numero elevato di elementi.

    visualizzazione gadget estesa

  • Visualizzazione dettagli: dettagli di un elemento del gadget specifico.

    È possibile avviare questa visualizzazione e ottenere il maggior numero di informazioni possibile facendo clic su un elemento nella visualizzazione standard o estesa.

    Se fai clic sul titolo di un elemento viene avviata l'applicazione pertinente, ad esempio una pagina web viene aperta nel browser.

    visualizzazione dettagli elementovisualizzazione dettagli elemento

Internazionalizzazione

Scrivi il tuo gadget da supportare con un testo ed etichette in più lingue, anche se non sei in grado di supportare testi in altre lingue. In futuro, qualcun altro potrebbe essere in grado di farlo. Puoi anche indicare immagini, layout di visualizzazione o addirittura script diversi per utenti di diverse lingue.

Prima di tutto, prendiamo in considerazione le lingue. Per supportare più lingue, tutte le stringhe specifiche delle lingue devono essere visibili nell'interfaccia utente del gadget e devono essere salvate in un file denominato strings.xml disponibile nelle sottodirectory denominate con l'ID lingua appropriato. Il file contiene le assegnazioni delle variabili per le stringhe di una lingua specifica. Invece di utilizzare le stringhe specifiche di una lingua nel codice e nella definizione del gadget, utilizza le variabili. Ad esempio, il file inglese strings.xml di Ciao a tutti contiene:


<strings>

  <strTitle>Ciao a tutti!</strTitle> 
  <strHello>Ciao a tutti!</strHello> 
  <strSnippet>Informazioni relative all'elemento.</strSnippet> 
  <strAboutText>
	Plug-in Ciao a tutti! Inserisci qui il copyright. Inserisci qui altri
	dettagli della descrizione.
	</strAboutText> 
  <strDescription>Dici Ciao a tutti</strDescription> 
  </strings>

Pertanto, nel codice dello script relativo al gadget Ciao a tutti, imposterai la proprietà del caption della visualizzazione su "Ciao a tutti!" come indicato di seguito: view.caption = strTitle;
Nel file XML o .gmanifest imposta il testo delle informazioni nel seguente modo:
<aboutText>&strAboutText</aboutText>

Tieni presente che nel codice utilizzi solo il nome dell'elemento indicato nel file strings.xml. Nel file XML, il nome dell'elemento deve essere preceduto da &.

Se il gadget è stato scritto per le versioni inglese e francese, i file verranno salvati nella seguente sottodirectory:


  <GD dir>/Plugins/YourGadget
                     |
                     |---- gadget.js
                     |
                     |---- gadget.gif
                     |
                     |---- 1033 (ID lingua per l'inglese americano)
                     |      |
                     |      `-- strings.xml
                     |
                     `---- 1036 (ID lingua per il francese)
                            |
                            `-- strings.xml

La Sidebar verifica l'esistenza di una directory con l'ID lingua uguale a quello del sistema corrente. Se ne esiste una, viene caricato il file strings.xml della directory in questione. Se il file non viene trovato, per impostazione predefinita viene caricato il file strings.xml della directory 1033 (inglese americano), se disponibile.

Analogamente, è possibile inserire immagini, markup, script e altro nelle cartelle di localizzazione e la Sidebar cercherà di caricarli utilizzando le regole sopra indicate. Quindi se, ad esempio, disponi di un gadget che richiede un'immagine diversa a seconda della lingua locale, puoi procedere nel seguente modo:
<img src="some_image.png"/>

La Sidebar cercherà prima di tutto di caricare il file some_image.png, quindi se la lingua del sistema è il francese, cercherà il file nella directory di localizzazione francese (1036\some_image.png) e successivamente nella directory inglese (1033\some_image.png).

Puoi anche salvare contenuto nella directory di localizzazione e non nella directory principale, inclusi i seguenti file:

  • main.xml: qualora siano necessari diversi layout in diverse lingue.
  • options.xml: qualora siano necessari diversi layout in diverse lingue.
  • anything.js: qualora siano necessari diversi script in diverse lingue.

Se desideri creare un gadget che supporti il comportamento predefinito nella maggior parte dei casi ma che abbia un comportamento diverso con determinate lingue, puoi:

  • Salvare il file gadget.xml nella cartella principale del file gadget.gg.
  • Salvare il resto del contenuto nella cartella 1033\ del file gadget.gg.
  • Salva il contenuto che deve essere sostituito nelle lingue determinate nella cartella specifica della lingua.

Fai clic qui per un elenco di tutti gli ID lingua.

Riferimento API

Riferimento oggetto

In questa sezione vengono illustrati i vari oggetti associati agli script dell'API di Google Gadgets, inclusi i relativi metodi, proprietà ed eventi associati. Tieni presente che molti oggetti ereditano proprietà, metodi ed eventi da basicElement.

Inoltre, quando un metodo restituisce un element, significa che l'elemento definito nella definizione XML del gadget deriva da basicElement.

gadget.debug
Evidenzia le API utili per lo sviluppo e il debug dei gadget. Per l'esecuzione in modalità debug, decomprimi il gadget e nel file decompresso, fai doppio clic sul file gadget.gmanifest.
Metodi
Nome e argomenti Descrizione Valori restituiti
error (stringa Messaggio) Quando un gadget viene eseguito in modalità debug, nella console di debug viene visualizzata la stringa Messaggio come errore. void
trace (stringa Messaggio) Quando un gadget viene eseguito in modalità debug, nella console di debug viene visualizzata la stringa Messaggio. void
warning (stringa Messaggio) Quando un gadget viene eseguito in modalità debug, nella console di debug viene visualizzata la stringa Messaggio come avviso. void


gadget.storage
Fornisce accesso ai contenuti del pacchetto gadget.
Metodi
Nome e argomenti Descrizione Valori restituiti
extract (stringa nome file) Estrae un file dal pacchetto gadget nella cartella dei file temporanei e restituisce il percorso completo del file estratto. stringa
openStream (stringa nome file) Apre un file del pacchetto gadget e ne restituisce i contenuti come flusso. flusso
openText (stringa nome file) Apre un file del pacchetto gadget e ne restituisce i contenuti come stringa. stringa


visualizza
Nota: diversamente dagli elementi secondari/oggetti del contenuto, view non eredita nulla da basicElement.
È necessario definire un oggetto view in un file distinto per ogni riquadro dell'interfaccia utente del gadget.
Proprietà
Nome Descrizione Tipo Lettura/scrittura
caption Per impostazione predefinita, il sottotitolo di questa visualizzazione è visibile quando un gadget è in modalità mobile o estesa ma non quando appare nella Sidebar. Vedere anche la proprietà showCaptionAlways. stringa Lettura-scrittura
children Restituisce una raccolta contenente gli elementi secondari dell'elemento visualizzazione. Questi elementi secondari sono tutti oggetti derivanti da basicElement. È possibile accedervi tramite script e non tramite definizioni XML. elementi Solo lettura
event Esposizione dell'oggetto event agli script per i gestori degli eventi. evento Lettura
height Imposta o restituisce l'altezza della visualizzazione, espressa in pixel. intero Lettura-scrittura
width Imposta o restituisce la larghezza della visualizzazione, espressa in pixel. intero Lettura-scrittura
resizable Se true, l'utente può ridimensionare la visualizzazione. booleano Lettura-scrittura
showCaptionAlways Se true, la Sidebar mostra sempre il sottotitolo (specificato nella proprietà caption) per questa visualizzazione. Per impostazione predefinita o quando il valore è false, il sottotitolo non viene visualizzato quando il gadget appare nella Sidebar bensì quando è in modalità mobile o estesa. booleano Lettura-scrittura
Metodi
Nome e argomenti Descrizione Valori restituiti
void alert (stringa Messaggio) Visualizza un riquadro messaggi contenente la stringa Messaggio. void
element appendElement (stringa xml) Analizza la definizione dell'elemento fornita in formato XML e aggiunge l'elemento come ultimo elemento figlio della visualizzazione. Il nuovo elemento.
integer beginAnimation (stringa script, intero startValue, intero endValue, intero duration) Avvia il timer dell'animazione. Il timer viene eseguito per duration millisecondi. Gli script vengono eseguiti di tanto in tanto in questo periodo di tempo con un valore compreso tra StartValue ed EndValue. Un identificatore che può essere utilizzato per annullare l'animazione.
Nota: il numero di volte in cui viene eseguita la richiamata dipende dalla prestazione e dal carico corrente del sistema. Il valore massimo può essere 100 fps (fotogrammi al secondo).
void cancelAnimation (intero Token) Annulla un'animazione in fase di esecuzione. Il token è l'identificatore restituito da beginAnimation. void
void clearInterval (intero Token) Annulla un intervallo o un timeout. void
boolean confirm (stringa Messaggio) Visualizza una casella di conferma contenente la stringa Messaggio. Se si preme OK, restituisce true, in caso contrario restituisce false. booleano
element insertElement (stringa xml, elemento InsertBefore) Analizza il file XML fornito e inserisce l'elemento immediatamente sopra l'elemento InsertBefore. Il nuovo elemento.
void removeElement (elemento Item) Rimuove l'elemento specificato. void
void resizeBy (intero width, intero height) Modifica la dimensione della visualizzazione utilizzando la larghezza e l'altezza specificati, in base alla larghezza e all'altezza correnti delle visualizzazione. Le unità sono in pixel. void
void resizeTo (intero width, intero height) Modifica la dimensione della visualizzazione in base alla larghezza e all'altezza specificati in pixel. void
integer setTimeout (stringa Script, intero Duration) Crea un timer per un'unica esecuzione. Lo script verrà eseguito solo una volta, dopo Duration millisecondi. Un token che può essere utilizzato per annullare il timeout.
integer setInterval (stringa Script, intero Duration) Crea un timer per un'esecuzione ricorrente. Lo script verrà eseguito solo ogni Duration millisecondi, fino a quando non verrà annullato. Un token che può essere utilizzato per annullare l'intervallo.
Eventi
Nome Descrizione
onclick Viene eseguito quando si fa clic sul pulsante sinistro del mouse.
onclose Viene eseguito quando la visualizzazione sta per essere chiusa.
ondblclick Viene eseguito quando si fa doppio clic sul pulsante sinistro del mouse.
onkeydown Viene eseguito quando viene premuto un tasto.
onkeypress Viene eseguito quando un tasto viene premuto e rilasciato.
onkeyup Viene eseguito quando viene rilasciato un tasto.
onminimize Viene eseguito quando il gadget viene ridotto a icona.
onmousedown Viene eseguito quando viene premuto il pulsante sinistro del mouse.
onmouseout Viene eseguito quando il cursore del mouse esce dalla visualizzazione.
onmouseover Viene eseguito quando il cursore del mouse entra nella visualizzazione.
onmouseup Viene eseguito quando viene rilasciato il pulsante sinistro del mouse.
onopen Viene eseguito quando la visualizzazione viene aperta per la prima volta.
onoptionchanged Viene eseguito quando una proprietà dell'oggetto options viene aggiunta, modificata o rimossa. event.propertyName indica l'elemento modificato.
onrestore Viene eseguito quando il gadget viene ripristinato dopo essere stato ridotto a icona.
onsizing Viene eseguito quando l'utente ridimensiona il gadget. Viene eseguito solo se resizable è impostato su true. event.width e event.height contengono la nuova larghezza e la nuova altezza richieste dall'utente. Il codice evento può annullare l'evento (event.returnValue = false) in base al quale il gadget mantiene la sua dimensione corrente. Il codice evento può modificare event.width e event.height al fine di sovrascrivere la selezione dell'utente.
onsize Viene eseguito quando viene cambiata la dimensione della visualizzazione per un codice script che modifica la dimensione (ad esempio, impostando view.width o view.height o richiamando view.resizeBy o view.resizeTo), o in seguito all'uso di onsizing e all'indicazione di una nuova dimensione. Questo evento non può essere annullato.


Oggetto basicElement
Definisce le proprietà, i metodi e gli eventi evidenziati in tutti gli elementi, con gli elementi specifici che ereditano quanto definito in questa sezione.
Proprietà
Nome Descrizione Tipo Lettura/scrittura
cursor Imposta o recupera il cursore da visualizzare quando il mouse è su un elemento.

I valori possibili sono: arrow, ibeam, wait, cross, uparrow, size, sizenwse, sizenesw,sizewe, sizens, sizeall, no, hand,busy, help

 stringa Lettura-scrittura
dropTarget Determina se questo elemento è un obiettivo delle operazioni di trascinamento. Se il valore è vero, gli eventi ondrag* si attivano quando l'utente avvia un'operazione di trascinamento. booleano Lettura-scrittura
enabled Determina se questo elemento è stato attivato. Gli elementi disattivati non generano alc