OGGETTO FORM

Descrizione

Eventi specifici del form

 I principali eventi sul form sono:

• CambiaForm: evento attivato al cambiamento del valore di un qualsiasi campo del form. Può essere utilizzato ad esempio per
  – modificare i valori di uno o più campi in base al valore inserito in uno o più campi
  – fornire all’utente messaggi di avviso in base al valore inserito in uno o più campi.
• Caricamento: evento attivato al caricamento di un form (sia esso esistente o nuovo). Può essere utilizzato ad esempio per assegnare valori a campi che non corrispondono a campi del database ma sono la combinazione di uno o più di essi (campi calcolati).
• Render: evento attivato alla prima visualizzazione del form e in tutti i successivi postback. Può essere utilizzato ad esempio per riassegnare proprietà degli oggetti ad ogni aggiornamento del form.
• RenderClient: evento lato client attivato alla prima visualizzazione del form e in tutti i successivi postback. Deve essere scritto in linguaggio Javascript e può essere utilizzato, ad esempio, per effettuare aggiornamenti che richiedono l’uso di codice Javascript.
• Salva: evento attivato al salvataggio del form. Può essere utilizzato per validare i dati: è possibile infatti inibire il salvataggio nel caso i dati inseriti non rispettino regole specifiche che possono essere inserite nel codice di gestione dell’evento, il quale dovrà ritornare il valore false nel caso il salvataggio debba essere inibito. NOTA: al momento della creazione di un documento, all’interno di una categoria di tipo file, l’evento di salvataggio del form si attiva solamente dopo che l’utente ha scelto il file da allegare.

Per maggiori informazioni sugli eventi leggi qui.

Proprietà utilizzabili da codice

Metodi utilizzabili da codice lato Server (VB.NET/C#)

• Alert(<message>,<optional caption>): consente di visualizzare una finestra popup che visualizza la stringa passata come primo parametro e, solo per la versione desktop, ha opzionalmente come titolo la stringa passata come secondo parametro;
• ChooseOption(<postback procedure>,<options array>): visualizza una richiesta popup che consente all’utente di scegliere fra una serie di opzioni specificate nel parametro <options array>.  In caso di pressione del pulsante di conferma, viene richiamato l’evento EventoEsegui dell’oggetto Procedura specificato nel parametro <postback procedure>. All’interno del codice dell’evento è utilizzabile il parametro Parameter1 al quale viene passato l’indice dell’opzione scelta.
  Esempio di utilizzo:

  form.ChooseOption(form.findcontrol("RitornoSceltaOpzioni"),new dbarray("Opzione1","Opzione2","Opzione3"))

• ChooseRecords(<postback procedure>,<table>,<title>,<multiple>,<columns format>): visualizza una richiesta popup che consente all’utente di scegliere uno o più records da una lista. Nel parametro <table> deve essere passato l’oggetto QWTable contente i records da mostrare. Il parametro <title> (opzionale) contiene il titolo della finestra popup, mentre il parametro <multiple> assegnato a true consente la selezione di più di un record (opzionale, default false).
  Attraverso il parametro opzionale <columns format> è possibile specificare il layout delle colonne da visualizzare, attraverso un array di elementi array con con i seguenti elementi: <nome campo>,<larghezza in pixel>,<intestazione colonna,<formato numerico>. Quest’ultimo parametro è opzionale ed è del tipo “999,999.99”.
  Alla conferma della scelta, viene richiamato l’evento EventoEsegui dell’oggetto Procedura specificato nel parametro <postback procedure>. All’interno del codice dell’evento è utilizzabile il parametro Parameter1 al quale viene passato un array contenente i records selezionati, a loro volta costituiti da array contenenti i valori dei campi.
  Esempio di utilizzo:
  Attivazione della lista

  Dim errorMsg As String 
  Dim personale As QWTable 
  personale = OpenTable(form, "SELECT CODICE,NOME FROM PERSON", Nothing, True, False, errorMsg)
  
  If String.IsNullOrEmpty(errorMsg) Then 
      form.ChooseRecords(form.findcontrol("RitornoChooseRecords"), personale, "Scegliere una persona", False, new DBArray(new DBArray("CODICE",40,"Codice"),new DBArray("NOME",200,"Nome"))) 
  Else
      form.Alert("Errore: " & errorMsg) 
  End if
  
  ' Non chiudere la tabella!

  Esame dei risultati nell’evento EventoEsegui dell’oggetto RitornoChooseRecords

  ' crea un elenco testuale dei records (codice e nome delle persone)
  
  Dim rows As DBArray = Parameter1
  Dim columns As DBarray
  Dim stampa As String = ""
  
  For i As Integer = 1 To rows.Size
      columns = rows(i)
      stampa = columns(1) & " " & columns(2) & "<br>"
  Next

• Close(): chiude il form senza salvare i dati.
• Confirm(<postback procedure>,<message>,<title>,<oklabel>,<cancellabel>): visualizza una richiesta popup di conferma all’utente. Il parametro <message> rappresenta il messaggio da visualizzare, <title> (opzionale) il titolo del popup, <oklabel> (opzionale) l’etichetta del pulsante di conferma, <cancellabel> (opzionale) l’etichetta del pulsante di rifiuto. In caso di pressione del pulsante di conferma, viene richiamato l’evento EventoEsegui dell’oggetto Procedura specificato nel parametro <postback procedure>.
  Su piattaforma mobile i parametri <title>, <oklabel> e <cancellabel> non sono presenti.
  Esempio di utilizzo:

  form.Confirm(form.findcontrol("RitornoConferma"),"Confermi l'esecuzione della procedura?","Confermare","Sì","No")

• ExecuteQuery(): valido solo per i form relativi a query SQL. Riesegue la query principale.
• FileDownload(<path>,<name>): esegue il download del file il cui percorso è specificato nel parametro <path>. Opzionalmente, è possibile specificare nel parametro <name> il nome che dovrà avere il file scaricato.
• FilePreview(<path>,<name>)**: visualizza l’anteprima del file il cui percorso è specificato nel parametro <path>. Opzionalmente, è possibile specificare nel parametro <name> il nome che dovrà essere visualizzato nel titolo della pagina di anteprima.
• GetAssigned(<object>): restituisce true se l’oggetto del form passato come parametro ammette solo valori scelti da una lista, ed il valore contenuto al momento risulta scelto dalla lista, false altrimenti.
• GetCurrentGPSCoordinates(<postback procedure>): legge la posizione GPS del dispositivo e richiama EventoEsegui dell’oggetto Procedura specificato nel parametro <postback procedure> assegnando a Parameter1 la latitudine e a Parameter2 la longitudine
• GetDataBase(): restituisce l’oggetto DataBase
• GetDocumentPath(): restituisce il percorso del documento collegato al form
• GetCategoryID(): restituisce il codice della categoria documentale
• GetIdDoc(): restituisce l’ID del documento (vale sempre “DW”)
• GetCodDoc(): restituisce il codice univoco del documento
• GetUserCode(): restituisce il codice dell’utente nell’anagrafica
• GetUserMail(): restituisce l’e-mail dell’utente
• GetUserName(): restituisce il nome dell’utente
• GetSession(): restituisce l’oggetto sessione
• IsNew(): restituisce true se è in corso la creazione di un nuovo documento/modulo, false se sono caricati i dati di un documento/modulo già precedentemente salvato
• IsPublished(): restituisce true se il documento/modulo è pubblicato, false altrimenti
• Notification(<message>,<type (optional)>,<auto close (optional)>,<auto close delay msec (optional)>): mostra una notifica all’utente in basso a destra, visualizzando il testo contenuto nel parametro <message>. Il parametro opzionale <type> consente di definire il tipo di notifica in termini di colore e icona. I possibili valori sono quelli mostrati dalla figura seguente, che illustra anche l’aspetto.
  
  Opzionalmente, è possibile definire la chiusura automatica della notifica dopo un determinato periodo di tempo, assegnando il parametro opzionale <auto close> a true e il parametro <auto close delay> al tempo, in millisecondi, trascorso il quale si desidera che la notifica venga chiusa automaticamente.
• ClearNotifications(): cancella tutte le notifiche presenti sulla pagina.
• PhoneCall(<number>): consente di effettuare una chiamata telefonica al numero specificato nel parametro <number>. Su piattaforma desktop è necessario installare l’app “Il mio telefono” disponibile con Windows 10 versione 20H2 (ottobre 2020).
• RefreshList(<object>): consente di aggiornare le tendine degli oggetti “Casella a discesa” per i quali nella query specificata nella proprietà QueryLista è presente un riferimento all’oggetto passato nel parametro <object>.
• RefreshLinkdoc(): forza l’aggiornamento del riquadro dei documenti collegati, rileggendo i dati dal database;
• Save(): salva i dati (equivale alla pressione del tasto “Salva” o “Conferma”).
• SetAssigned(<object>,<bool>): consente di marcare l’oggetto passato nel primo parametro come assegnato se nel secondo parametro viene passato il valore true.
• SetDocumentToLoad(<path>): valido solo per form legati a categorie di tipo “file”, permette di definire il file da caricare quando il documento è nuovo (form.isNew=true). Non ha effetto se il documento non è nuovo.
• SetEnabled(<object>,<bool>): abilita o disabilita l’oggetto passato nel primo parametro, in base al valore del secondo parametro. Se true abilita, se false disabilita.
• SetFocus(<object>): rende l’oggetto <object> quello attivo per l’input
• SetNumber(): assegna il campo “numero” come progressivo in base al campo “tipo”
• SetVisible(<object>,<bool>): visualizza o nasconde l’oggetto passato nel primo parametro, in base al valore del secondo parametro. Se true visualizza, se false nasconde.
• ShowOnlyForm(): Mostra all’utente solo il form, sopprimendo i campi relativi al numero e al titolo del documento, e la griglia dei risultati nel caso delle query.
• TranslateString(<string>): Traduce una stringa nella lingua corrente. La stringa può essere in una qualsiasi delle lingue supportate, e viene tradotta nella lingua correntemente impostata nell’interfaccia di QualiWare. La traduzione avviene utilizzando la tabella impostata nella proprietà TraduzioneStringhe.
  Esempio di utilizzo:

  form.alert(form.TranslateString("Operazione completata"))

• UpdateContainer(<object>): consente di aggiornare il contenuto di un oggetto contenitore che ha la proprietà ContenitoreAggiornamento a true. Può essere richiamato da oggetti che si trovano in altri contenitori che hanno la proprietà a true, oppure dagli eventi degli oggetti Gantt, Calendario e Kanban. Se il parametro <object> è lasciato a Nothing, verrà aggiornato l’intero form. Questo può essere utile per aggiornare anche il titolo da un evento che è attivato da un oggetto all’interno di un contenitore con la proprietà ContenitoreAggiornamento a true.
• UploadFile(<postback procedure>,<allowed extensions>,<multiple>)**: visualizza una maschera per il caricamento di un file sul server. Alla pressione del tasto di conferma viene richiamato l’evento EventoEsegui dell’oggetto Procedura specificato nel parametro <postback procedure>. Nel parametro opzionale <allowed extensions> è possibile specificare le estensioni di file consentite, separate da “,” (es.: “.jpg,.png”). Il parametro opzionale <multiple> può essere posto a false nel caso si voglia consentire il caricamento di un solo file.
  All’interno del codice dell’evento sono utilizzabili il parametro Parameter1 cui viene passato il percorso fisico del file caricato sul server, e il parametro Parameter2 cui viene passato il nome originale del file caricato dall’utente. Nel caso di caricamento di più file è possibile utilizzare l’oggetto DBArray restituito nel parametro ParameterAll per recuperare tutti i percorsi, che vengono assegnati agli indici dispari, e i nomi, che vengono assegnati agli indici pari successivi (es. nell’elemento ParameterAll(1) è contenuto il percorso del file e nell’elemento ParameterAll(2) il relativo nome, ecc.).
  Esempio di utilizzo:

  form.UploadFile(form.findcontrol("RitornoUpload"),".jpg,.png")

Solo Form Desktop :

• AcquireBarcode (<postback procedure>, <title>): consente di acquisire un codice a barre dalla fotocamera. Il codice a barre letto verrà restituito come parametro1 alla procedura collegata all’oggetto indicato nel parametro <postback procedure>.
  Nel parametro <title> può essere opzionalmente specificato il titolo da visualizzare nella finestra di acquisizione del codice a barre.
  Esempio di utilizzo (da inserire nel codice dell’evento Click di un pulsante):

  form.AcquireBarcode(form.findcontrol("ReadBarcode"),"Leggere il codice a barre")

• AcquirePicture (<postback procedure>, <format>, <quality>, <title>): consente di scattare una foto dalla fotocamera. L’immagine verrà salvata su file il cui percorso verrà restituito nella variabile Parameter1 alla procedura collegata all’oggetto indicato nel parametro <postback procedure>.
  Nel parametro <format> può essere opzionalmente specificato il formato del file, che può essere “JPG” o “PNG”. Di default è “PNG”.
  Nel parametro <quality> può essere opzionalmente specificata la qualità dell’immagine, che va da 0 a 100 ed è applicabile solo se il formato è “JPG”. Il valore di default è 95.
  Nel parametro <title> può essere opzionalmente specificato il titolo da visualizzare nella finestra di acquisizione dell’immagine.
  Esempio di utilizzo (da inserire nel codice dell’evento Click di un pulsante):

  form.AcquirePicture(form.findcontrol("ReadPicture"),"JPG",90,"Scattare una foto")

• AcquireSignature(<postback procedure>,<title>,<width>,<height>): consente di acquisire una firma scritta a mano visualizzando l’apposita maschera. La firma acquisita verrà salvata su file in formato png il cui percorso verrà restituito come parametro1 alla procedura collegata all’oggetto indicato nel parametro <postback procedure>. Nel parametro <title> è possibile specificare un titolo per la finestra di richiesta di firma, mentre nei parametri <width> e <height> ne può essere specificata rispettivamente la larghezza e l’altezza in pixel. E’ possibile scaricare un esempio di categoria documentale con la gestione della firma da qui.
• AcquireSignatureWACOM(<filename>): consente di acquisire tramite i Cloud Components una firma scritta a mano su dispositivo WACOM STU-430 o STU-530. La firma acquisita verrà salvata sul server in un file in formato png il cui percorso verrà restituito nel parametro <filename>. Viene anche restituito un file con lo stesso nome ma estensione JSON contenente i dettagli della firma, in termini di coordinate e pressione della penna. Da notare che l’operazione è asincrona, e quindi il form dovrà prevedere un polling per verificare quando il file sarà stato generato. E’ possibile scaricare un esempio di categoria documentale con la gestione della firma da qui.
• AcquireDigitalSignature(<filename>,<signPDF>,<signedFilename>,<IdDoc>,<CodDoc>): consente di firmare digitalmente il file il cui percorso è specificato nel parametro <filename>. Se il formato del file è PDF, con il flag <signPDF> è possibile specificare se firmare direttamente il PDF o generare un file P7M. Il file risultante verrà memorizzato nel percorso specificato nel parametro <signedFilename>, che, se lasciato a nothing, viene assegnato dal metodo. Nel caso si desideri collegare il file firmato ad un documento, è possibile specificarne il codice nei parametri <IdDoc> e <CodDoc>. E’ possibile scaricare un esempio di categoria documentale con la gestione della firma digitale qualificata da qui.
• ChooseOptionMultiple(<postback procedure>,<options array>,<atleastone>): visualizza una richiesta popup che consente all’utente di scegliere fra una o più fra le opzioni specificate nel parametro <options array>.  Se il parametro <alteastone> è passato a “true”, l’utente deve scegliere almeno una opzione. In caso di pressione del pulsante di conferma, viene richiamato l’evento EventoEsegui dell’oggetto Procedura specificato nel parametro <postback procedure>. All’interno del codice dell’evento è utilizzabile il parametro Parameter1 al quale viene passata una stringa contenente gli indici delle opzioni scelte separate da “,”. Tale stringa può essere trasformata in un DBArray usando la funzione String2Array.
  Esempio di utilizzo:

  form.ChooseOptionMultiple(form.findcontrol("RitornoSceltaOpzioni"),new dbarray("Opzione1","Opzione2","Opzione3"),true)

• OpenInIFrame(<client>,<URL>): consente l’apertura della <URL> specificata all’interno di un IFRAME creato nell’oggetto client specificato nel primo parametro.
• OpenChatInIFrame(<client>,<IDDoc>,<CodDoc>,<recipients>): consente l’apertura della chat relativa al documento identificato dai parametri <IDDoc> e <CodDoc> all’interno di un IFRAME creato nell’oggetto client specificato nel primo parametro. Il parametro <recipients> di tipo DBArray contiene i codici dei possibili destinatari.
• OpenLinkDocInIFrame(<client>,<IDDoc>,<CodDoc>,<optional readOnly>,<optional refresh>): consente l’apertura dei documenti collegati relativi al documento identificato dai parametri <IDDoc> e <CodDoc> all’interno di un IFRAME creato nell’oggetto client specificato nel primo parametro. Il parametro opzionale <readOnly>, se assegnato a true, consente di inibire la modifica ai documenti collegati, mentre il parametro <refresh>, se assegnato a true, consente di aggiornare i collegamenti virtuali.E’ possibile scaricare un esempio di utilizzo dei metodi Open*InIFrame a qui.

Solo Form Designer Mobile:

• AcquirePicture (<postback button>, <type>,<file name>): consente di scattare una foto dalla fotocamera o acquisirla dalla galleria. L’immagine verrà inserita nei documenti collegati con il nome specificato.
  Nel primo parametro può essere passato un “oggetto Button”, il cui ClickEvent sarà invocato al momento la conferma della foto. Potrebbe anche essere lasciata a nothing se non è richiesto postback. Nel secondo parametro deve essere specificato il tipo di immagine:
  1 = bassa risoluzione
  2 = media risoluzione
  3 = alta risoluzione
  4 = altissima risoluzione
  5 = Acquisisci dalla galleria
  Nel terzo parametro può essere opzionalmente specificato il nome da assegnare al file, che verrà mostrato nella finestra dei documento collegati. Può essere lasciato a nothing o stringa vuota. Esempio di utilizzo (da inserire nel “Codice EventoClick” di un tasto):

  form.AcquirePicture(form.findcontrol("POSTBACK"),1,"picture")

  N.B. questa versione è utilizzabile solo sui form collegati a categorie documentali

• AcquirePicture (<postback procedure>, <type>): consente di scattare una foto dalla fotocamera o acquisirla dalla galleria. L’immagine verrà salvata su file il cui percorso verrà restituito come parametro1 alla procedura collegata all’oggetto indicato nel parametro <postback procedure>.
  Nel parametro <type> deve essere specificato il tipo di immagine:
  1 = bassa risoluzione
  2 = media risoluzione
  3 = alta risoluzione
  4 = altissima risoluzione
  5 = Acquisisci dalla galleriaUn esempio di applicazione di questo metodo è disponibile qui.
• AcquireSignature(<postback button>,<default name>): consente di acquisire una firma scritta a mano visualizzando l’apposita maschera. La firma acquisita verrà inserita nei documenti collegati come immagine in formato Jpeg. Entrambi i parametri possono essere lasciati a nothing. Nel primo parametro può essere passato un oggetto di tipo Pulsante, il cui evento Click verrà richiamato al momento della conferma della firma. Nel secondo parametro può essere passato il nome dell’utente che apporrà la firma.
  Esempio di utilizzo (da inserire nel codice dell’evento Click di un pulsante):

  form.AcquireSignature(form.findcontrol("POSTBACK"),"Pier Alberto Guidotti")

  N.B. questa versione è utilizzabile solo sui form collegati a categorie documentali

• AcquireSignature(<postback procedure>,<default name>): consente di acquisire una firma scritta a mano visualizzando l’apposita maschera. La firma acquisita verrà salvata su file in formato png il cui percorso verrà restituito come parametro1 alla procedura collegata all’oggetto indicato nel parametro <postback procedure>. Nel parametro <default name> è possibile specificare il nome di default della persona che effettuerà la firma. E’ possibile scaricare un esempio di categoria documentale con la gestione della firma su dispositivo mobile da qui. Un esempio di form è inoltre disponibile qui.
• AddStyle(<stylename>,<styledefinition>): consente di aggiungere uno stile CSS che potrà essere assegnato agli oggetti. Di seguito un esempio di utilizzo:

  form.AddStyle(".Critical","background-color:red !important")

Metodi utilizzabili da codice lato Client (Javascript)

• $.QualiWare.alert(<text>,<title>): consente di visualizzare una finestra popup che mostra il testo e il titolo passati come parametro
• $.QualiWare.confirm(<text>, <title>, <okLabel>, <okCallBack>, <cancelLabel>, <cancelCallBack>): visualizza una richiesta popup di conferma all’utente. Il parametro <text> rappresenta il messaggio da visualizzare, <title> il titolo del popup, <okLabel> l’etichetta del pulsante di conferma, <cancelLabel> l’etichetta del pulsante di rifiuto. In caso di pressione del pulsante di conferma, viene eseguita la funzione specificata nel parametro <okCallBack>, mentre in caso di pressione del tasto di annullamento viene eseguita la funzione specificata nel parametro <cancelCallBack>, che è opzionale.
  Esempio di utilizzo di “alert” e “confirm”:

  $.QualiWare.confirm("Confermi?","Confermare","Confermo",function() {
  	$.QualiWare.alert("Confermato","Attenzione")
  },
  "Non confermo")
  

• $.QualiWare.executeQuery(<sql>, <callback>): esegue in modo asincrono la query contenuta nel parametro <sql> e, ad esecuzione completata, richiama la funzione contenuta nel parametro <callback> restituendo nel parametro <data> l’array dei record ritornati e nel parametro <error> l’eventuale messaggio d’errore.
  Esempio:
  

  $.QualiWare.executeQuery('Select * from ENTI',
  				function(data,error) {
  					if (error) 
  					    $.QualiWare.alert(error,"Errore")
  					else
  					    $('#<oggetto>').setValue(data[0]["CODICE"])
  				}
  )

  NOTA: la query deve essere preventivamente abilitata nell’EventoCarica del form utilizzando il metodo AllowClientQuery dell’oggetto QWSession. Dal momento che la query stessa può essere modificata dinamicamente nell’evento Javascript, ad esempio aggiungendo i filtri nella clausola WHERE, non è necessario specificarla completamente nel parametro <query> del metodo, ma è sufficiente inserire la parte costante, ad esempio la parte SELECT.
  Esempio:

  form.GetSession().AllowClientQuery("Select RAGSOC from CLIFOR")

   

• $.QualiWare.getUserCode(): restituisce le iniziali dell’utente
• $.QualiWare.getUserName(): restituisce il nome dell’utente
• $.QualiWare.setFocus(<object>): rende l’oggetto <object> quello attivo per l’input
• $.QualiWare.Notification(<message>,<type (optional)>,<auto close (optional)>,<auto close delay msec (optional)>): mostra una notifica all’utente in basso a destra, visualizzando il testo contenuto nel parametro <message>. Il parametro opzionale <type> consente di definire il tipo di notifica in termini di colore e icona. I possibili valori sono quelli mostrati dalla figura seguente, che illustra anche l’aspetto.
  
  Opzionalmente, è possibile definire la chiusura automatica della notifica dopo un determinato periodo di tempo, assegnando il parametro opzionale <auto close> a true e il parametro <auto close delay> al tempo, in millisecondi, trascorso il quale si desidera che la notifica venga chiusa automaticamente.
• $.QualiWare.ClearNotifications(): cancella tutte le notifiche presenti sulla pagina.