' Rapid-Q by William Yu (c)1999-2000                                             .
' ================================================================================
' Upload_il_tuo_script_su_Rapidq.it

' Capitolo_3._Guida_al_linguaggio_Rapid-Q

In questo capitolo descriverò il linguaggio Basic, in particolare Rapid-Q. Dal momento che Rapid-Q deriva dal linguaggio Basic,
i programmatori con esperienza di Basic possono decidere di saltare questa sezione. Ci sono alcuni nuovi concetti che non fanno
parte del linguaggio Basic come il passaggio di parametri infiniti e l'utilizzo dell'operatore '-' nelle stringhe.

Direttive di Rapid-Q
Le direttive vengono utilizzate in Rapid-Q per indicare al compilatore come e che tipo di codice debba essere generato. Rapid-
Q supporta le seguenti direttive, che generalmente vengono inserite all'inizio dei programmi.

 $APPTYPE      [ CGI | CONSOLE | GUI ]    Default è GUI
               $APPTYPE è utilizzato per indicare al compilatore che genere di applicazione deve generare. Nonostante i default sia GUI, se
               non viene impiegata la direttiva $APPTYPE Rapid-Q dedurrà il tipo di applicazione dal codice sorgente. Per non utilizzare
               questa possibilità , includere la direttiva $APPTYPE all'inizio del vostro codice sorgente.
               Uso: $APPTYPE CONSOLE
 $TYPECHECK    [ OFF | ON ]    Default è OFF
               $TYPECHECK è utilizzato per indicare al compilatore se volete che il codice sorgente sia esaminato utilizzando un controllo
               accurato ON (bisogna dichiarare tutte le variabili), oppure un controllo superficiale OFF come nel Basic tradizionale dove non
               è necessario dichiarare le variabili. Notate che potete cambiare il livello di controllo in qualsiasi momento, cosicché potrete
               avere un controllo più accurato solo su una parte del vostro codice.
               Uso: $TYPECHECK ON
 $INCLUDE      [ NomeFile ]
               Utilizzare $INCLUDE ha lo stesso effetto di importare il vostro file direttamente nel programma nel punto di chiamata. Potete
               utilizzare $INCLUDE in qualunque punto del vostro programma, tranne che in un SUB o FUNCTION, ma generalmente viene incluso
               all'inizio del codice. Se il nome file è fra virgolette esso verrà ricercato nella directory corrente, e nei percorsi
               specificati. Se il nome file è fra < e > esso verrà ricercato nella directory corrente, nei percorsi specificati e nei percorsi
               di ricerca del sistema.
               Uso:
                   $INCLUDE 'RAPIDQ.INC'
                   $INCLUDE INC>
 $RESOURCE     Handle AS FileName
               La maggior parte dei linguaggi di programmazione Windows prevedono il supporto per file di risorse. In Rapid-Q è diverso. In
               Rapid-Q, i file di risorse sono solo una serie di file grafici. Non esistono risorse in forma di stringa in Rapid-Q. Comunque,
               i file di risorse sono compresi nelle vostre applicazioni. In questo modo, se state utilizzando dieci diverse bitmap non è
               necessario includerle nel vostro pacchetto .ZIP in quanto sono già inglobate nel .EXE. Se il nome file è fra virgolette esso
               verrà ricercato nella directory corrente, e nei percorsi specificati. Se il nome file è fra < e > esso verrà ricercato nella
               directory corrente, nei percorsi specificati e nei percorsi di ricerca del sistema.
               Uso:
                   $RESOURCE RES_BMP1 AS 'CLOUDS.BMP'
                   $RESOURCE RES_BMP1 AS BMP>
 $DEFINE       NewDefinition   [OldDefinition]
               Quando avete bisogno di ridefinire o creare nuove parole chiave o simboli, utilizzate questa direttiva. Non è possibile creare
               una serie di simboli per poi ridefinirli. Non si possono ridefinire operatori o punteggiatura. $DEFINE non può essere
               utilizzato per definire una funzione (come in C). Il parametro OldDefinition è opzionale, si può usare anche: $DEFINE NEWDEF
               Uso: $DEFINE INT16 SHORT
 $UNDEF        DefName [, DefName]
               Per annullare una definizione precedente, utilizzare $UNDEF. È possibile specificare più istanze nella stessa riga, separate da
               virgole.
               Uso: $UNDEF INT16, INT32
 $IFDEF        Definition
               Questa direttiva e utilizzata per indicare se una parte del codice debba essere compilata oppure no. È utilizzata assieme a
               $DEFINE. Se la Definizione è stata definita, il codice fra $IFDEF..$ENDIF verrà compilato, altrimenti verrà saltato
               interamente.
               Uso:
                   $IFDEF INT16
                   ' se INT16 è stato definito
                   ' compila questa parte
                   $ELSE
                   ' se INT16 non è stato definito
                   ' compila questa parte
                   $ENDIF
 $IFNDEF       Definition
               $IFNDEF ha l'effetto contrario di $IFDEF.
               Uso:
                   $IFNDEF INT16
                   ' se INT16 non è stato definito
                   ' compila questa parte
                   $ELSE
                   ' se INT16 è stato definito
                   ' compila questa parte
                   $ENDIF
 $OPTION       OptionName [Parametri]
               BYREF, BYTECODE, DECIMAL, DIM, EXPLICIT, GTK, ICON, INKEY$, e WEAKTYPE sono nomi opzione validi.
               Uso:
                   $OPTION BYREF
                   Questo cambia il modo in cui vengono passate le variabili.
                   Per default, Rapid-Q passa le variabili per valore.
                   Questa opzione fa il contrario.
                   Utilizzare con cautela.

                   $OPTION BYTECODE
                   Compila come bytecode solamente.

                   $OPTION DECIMAL ','
                   $OPTION DECIMAL 64
                   Questo cambia il carattere decimale di default
                   per l'utilizzo in VAL.
                   Il carattere decimale di default è il punto.

                   $OPTION DIM BYTE
                   $OPTION DIM WORD
                   $OPTION DIM DWORD
                   $OPTION DIM SHORT
                   $OPTION DIM INTEGER
                   $OPTION DIM LONG
                   $OPTION DIM SINGLE
                   $OPTION DIM DOUBLE
                   $OPTION DIM STRING
                   $OPTION DIM VARIANT
                   Questo cambia il tipo di default
                   delle variabili non dichiarate.
                   Per default, le variabili non dichiarate sono
                   considerate di tipo DOUBLE
                   se non viene fornito un suffisso.

                   $OPTION EXPLICIT
                   È lo stesso che usare TYPECHECK ON
                   Mantenuto per compatibilità con VB

                   $OPTION GTK
                   Usa GTK invece di XFORMS
                   Assicurarsi di avere i file relativi.

                   $OPTION ICON 'path\file.ico'
                   Questo cambia l'icona di default
                   del vostro file eseguibile.

                   $OPTION INKEY$ DEFAULT
                   $OPTION INKEY$ TRAPALL
                   Questo permette ad INKEY$ di accettare o rifiutare
                   determinati caratteri estesi.
                   TRAPALL bloccherà Shift/Ctrl/Alt/Menu,
                   come anche Caps/Num/Scroll lock lock.

                   $OPTION VBDLL ON
                   $OPTION VBDLL OFF
                   Questo determina come vengono trattate le DLL.
                   Se VBDLL è ON, le dichiarazioni delle DLL
                   in Rapid-Q saranno simili a quelle di VB,
                   cosicché il vostro codice potrà essere utilizzato
                   allo stesso modo in entrambi i linguaggi.
                   Questa opzione è OFF per default.

                   $OPTION WEAKTYPE ON
                   $OPTION WEAKTYPE OFF
                   WeakType è disabilitato (OFF) per default.
                   WeakType permette un controllo più veloce
                   e può aiutare ad importare del codice VB.
                   Non dovrebbe essere utilizzato
                   a meno che non siate sicuri che il codice va bene.

 $OPTIMIZE     [ OFF | ON ]    Default is OFF
               $OPTIMIZE può essere utilizzato per ridurre le dimensioni del codice eliminando istruzioni non necessarie. Se utilizzate questa
               opzione, accertatevi che sia la prima cosa che chiamate.
               Uso: $OPTIMIZE ON
 $ESCAPECHARS  [ OFF | ON ]    Default è OFF
               Se $ESCAPECHARS è ON, è possibile utilizzare sequenze speciali nelle vostre stringhe. Le sequenze speciali possono essere alfa
               numeriche. Notare che le maiuscole sono rilevanti. Uso: $ESCAPECHARS ON
               Uso: $ESCAPECHARS ON
                ____________________________________________________
               |Sequenze_speciali|Dettagli__________________________|
               |\a               |Campanello d'allarme              |
               |\b               |Backspace                         |
               |\f               |Nuova pagina                      |
               |\n               |Nuova riga                        |
               |\r               |A capo                            |
               |\t               |Tabulazione orizzontale           |
               |\v               |Tabulazione verticale             |
               |\\               |Barra rovescia                    |
               |\'               |Doppie virgolette                 |
               |\###             |### è qualsiasi numero 0..255    |
               |\xHH_____________|HH_è_un_valore_esadecimale_00..FF|
               Examples:
                   PRINT '\''
                   Output è '

                   PRINT '\x41'
                   Output è A

                   PRINT '\t\65\66\67\t\68\69\70
                   Output è ABC       DEF

                   PRINT 'Hey\r\n';
                   Output è Hey con caporiga

 $MACRO        MacroName[(Parametri, ...)] MacroDefinition
               Una macro sostituisce semplicemente una definizione con un'altra. Può essere trattata con una funzione se vengono forniti dei
               parametri. Rapid-Q consente di inserire una macro all'interno di un'altra macro (facendo attenzione ad evitare ricorsività ),
               l'unione di simboli usando ##, e perfino il sovraccarico di macro. È possibile inoltre ridefinire operatori i caratteri
               speciali tranne le virgolette. Una definizione può essere estesa a più righe utilizzando i due punti come separatore di riga.
               Una direttiva $MACRO è globale se precede qualunque direttiva $INCLUDE, cioè se i file inclusi hanno accesso alle definizioni
               della macro. Una direttiva $MACRO ha effetto soltanto a livello di modulo (il file corrente) se utilizzata in un file $INCLUDE.
               Così se A dipende da B e B ha delle direttive $MACRO, quelle direttive $MACRO hanno effetto solo su B e A non ha accesso ad
               esse se non sono ridichiarate nel modulo A.
               Note:
               MACRO, obbligate a preprocessare vostro codice, che prolungherà il compilazione. Rapid-Q normalmente esegue processo
               compilazione in un passaggio singolo. < FONT>
               Uso:
                   $MACRO ~ ,
                   Questo ridefinisce il carattere virgola
                   Provare: ? STRING$(10 ~ 'A')

                   $MACRO strcat(a,b) a=a+b
                   Implementa una funzione STRCAT
                  strcat(a$,'abc') si traduce in a$=a$+'abc'

                   $MACRO VARID(x) V##x
                   Un esempio di unione di simboli
                   DEFINT VARID(1) si traduce in DEFINT V1

                   $MACRO TWO_PI (2*PI)
                   $MACRO PI 3.14159
                   Macros incassate (solo in avanti).
                   Non può incassare se stesso come parametro.
                   Ciò evita controlli e ricorsività .

                   $MACRO ADD(a,b,c,d) ADD(a,b)+ADD(c,d)
                   $MACRO ADD(x,y) x+y
                   $MACRO ADD(x,y,z) x+y+z
                   Un esempio di sovraccarico di macro



3.2 Variabili ed assegnazioni
Le variabili sono immagazzinate nella memoria principale, e vi restano per l'intera durata del vostro programma. In Rapid-Q il
controllo di tipo è molto superficiale. Ciò significa che si può assegnare una stringa ad una variabile di tipo integer. Il
risultato è indefinito, ma molto probabilmente sarà 0. Lo stesso discorso vale per l'assegnazione di un numero ad una variabile
stringa, il risultato è una stringa vuota. Il controllo di tipo in realtà è effettuato a livello di interprete in Rapid-Q, ma
per evitare messaggi di errore continui, ho disabilitato il controllo completamente. In definitiva ciò significa che bisogna
essere estremamente accurati nell'assegnazione di valori alle variabili, in quanto Rapid-Q non segnalerà alcun errore. L'unico
caso in cui il tipo è controllato accuratamente è nei QObjects. Non è possibile assegnare un numero o una stringa ad una
variabile che ammetta come valore un Oggetto. Alcuni esempi di assegnazioni valide:
         A% = 'Hello' > 'World'
         A$ = 'Hi World!'
         A# = 34 + 34 - 324 * 3 / (34 / 5 + 5)
Se non avete mai programmato in Basic prima, vi sarete probabilmente chiedendo cosa significano tutti quei simboli prima della
A. Siccome la maggior parte delle implementazioni di Basic non obbligano a definire le variabili prima di utilizzarle, esse
possono essere definite utilizzando questi simboli:
         ?, ??, ???, %, &, !, #, $
Essi rappresentano rispettivamente BYTE, WORD, DWORD, SHORT, LONG or INTEGER, SINGLE, DOUBLE, e STRING. Ovviamente, se non viene
indicato alcun simbolo all'inizio di una variabile non dichiarata, essa viene automaticamente considerata DOUBLE. Questa è una
caratteristica di Rapid-Q; per altri linguaggi il default può essere SINGLE, LONG o quant'altro. Eccovi la relativa tabella:
    Tipo       ID  Dimen.  Valore
    --------- ---- ---- -------------
    Byte        ?   1   0..255
    Word       ??   2   0..65535
    Dword     ???   4   Per ora solo per la versione linux...
    Short       %   2   -32768..32767
    Integer     &   4   -2147483648..2147483647
    Long        &   4   -2147483648..2147483647
    Single      !   4   1.5 x 1045..3.4 x 1038
    Double      #   8   5.0 x 10324..1.7 x 10308
Se non vi è piaciuto questo sistema, potete sempre utilizzare DIM per dichiarare le vostre variabili, in questo modo:
            DIM Number AS INTEGER
            DIM S AS STRING
            DIM B AS BYTE
Spero di aver reso l'idea. Se $TYPECHECK è ON, sarete obbligati a dichiarare le vostre variabili in questo modo. È una buona
abitudine, soprattutto se intendete passare a linguaggi come C o Pascal. Sarete obbligati a dichiarare tutte le vostre variabili
prima di utilizzarle. Ecco una cosa che è accettabile in Rapid-Q, ma può sembrare confusa:
            DIM Num$ AS INTEGER
È meglio evitare codice fuorviante come questo.

3.3 Componenti e oggetti di Rapid-Q
Rapid-Q offre componenti (o oggetti) riutilizzabili che aiutano il programmatore nello sviluppo di applicazioni Windows. La
maggior parte dei linguaggi di programmazione RAD (Rapid Application Development) fanno lo stesso. Per Visual C++ si chiama MFC
e per Java si chiama JFC Swing. Che cosa sono i componenti visuali? Sostanzialmente sono contenitori di codice che utilizzano le
caratteristiche dei controlli Windows API (o in linux, qualunque API GUI stiate utilizzando) senza tutte le preoccupazioni
derivanti dall'utilizzo diretto delle API. Per esempio, è possibile creare finestre utilizzando chiamate API Windows soltanto,
ma questo può richiedere intere pagine. In Rapid-Q, tutto ciò è stato confezionato in un componente chiamato QFORM. Così invece
di dover registrare la vostra classe e poi visualizzarla e gestire tutte le chiamate, tutto ciò che dovete fare in Rapid-Q è:
             DIM Form AS QFORM
             Form.ShowModal
Al confronto di un programma C/C++, è molto più ordinato e facile da capire. Esistono parecchi componenti supportati da Rapid-Q,
come QBUTTON, QIMAGE, QFILESTREAM, ecc. Ne esistono anche alcuni che non sono supportati, e questa è una restrizione per chi usa
Rapid-Q. I componenti sono creati esattamente come le variabili, utilizzando DIM. Ciascun componente possiede proprietà , metodi
ed eventi. Le Proprieta sono gli attributi del componente. Per esempio, Left, Top, Width, e Height sono proprietà comuni a tutti
i controlli visibili, che definiscono la loro posizione all'interno del form o della finestra. Caption è una proprietà di tipo
STRING. Per un componente QFORM la proprieta Caption definisce il titolo del form. Caption per un QBUTTON definisce il testo del
pulsante. Caption per qualcosa come QFILESTREAM non esiste, dal momento che QFILESTREAM non è un componente visibile. Ha
comunque delle proprietà . Per una guida completa delle proprietà , metodi ed eventi di tutti i componenti, consultate la sezione
Appendice. Ecco ora per esempio di come assegnare proprietà ai vostri componenti:
                 DIM Form AS QFORM
                 Form.Caption = 'My Application'
                 Form.Left = 100
                 Form.Top = 100
Prestate attenzione a quali proprietà sono di sola lettura e quali di sola scrittura. Un esempio di proprietà di sola lettura è
la proprietà ITEMCOUNT del componente QLISTBOX. Un esempio di proprietà di sola scrittura è la proprietà ICON di un QFORM,
utilizzata per specificare la posizione di un'icona da utilizzare come default. Non ha senso leggere valori di sola scrittura o
scrivere valori di sola lettura, e ciò può portare ad errori nella compilazione o, peggio, al blocco del programma.

3.4 Metodi ed eventi dei componenti
Fino ad ora abbiamo trattato solo delle proprietà , ma i metodi non sono molto diversi da esse. Cos'è esattamente un metodo? In
realtà si tratta solo di una SUBROUTINE o FUNCTION. È chiamato metodo in quanto è riferito esclusivamente a quel componente. È
più difficile spiegarlo che capirlo. Ecco un esempio di metodo:
              DIM Form AS QFORM
              Form.Center
              Form.ShowModal
Abbiamo utilizzato in due metodi, Center, e ShowModal. Il metodo Center è una SUBROUTINE che non accetta parametri. La sua
funzione è quella di centrare il form nel desktop. ShowModal è in realtà una funzione, ma in questo caso il valore di ritorno è
ignorato. È un metodo utilizzato per visualizzare il vostro form, ed attendere che l'utente lo chiuda. Nota: A differenza di
alcune implementazioni Basic, in Rapid-Q una funzione può essere chiamata come una SUBROUTINE, ignorando il valore di ritorno.
Questo è simile a C/C++. Altri metodi possono richiedere altri parametri, ed alcuni anche accettare un numero infinito di
parametri. È inoltre possibile scriverli voi stessi in Rapid-Q, ma ne parleremo più avanti. Concludendo, i metodi sono funzioni
che svolgono una determinata azione in un determinato componente. Nell'esempio precedente, abbiamo centrato il form e
successivamente lo abbiamo visualizzato.
Bene, e gli eventi? Questo sarebbe un argomento complicato se parlassimo in termini di passaggio di messaggi e chiamate.
Fortunatamente, possiamo considerare la cosa da un livello molto più alto. Un evento si verifica quando succede qualcosa. Questo
è molto vago, il succedere qualcosa può essere il decorrere di un certo tempo, il click del mouse da parte dell'utente, la
pressione di un tasto ecc. Rapid-Q non è in grado di gestire tutti gli eventi, ma solo i più importanti. Per esempio, se
l'utente clicca su un pulsante dovrete scrivere del codice per eseguire quella determinata operazione. Dobbiamo definire una
funzione di CALLBACK che lo gestisca. Per ogni evento che si verifica, si deve indirizzare l'evento ad una subroutine scritta
per gestire l'evento. Ecco come fare:
       SUB ButtonClicked
          PRINT 'Il pulsante è stato premuto'
       END SUB

       DIM Button AS QBUTTON
       DIM Form AS QFORM

       Button.Parent = Form            '' Proprietà 
       Button.OnClick = ButtonClicked  '' Evento
       Form.ShowModal                  '' Metodo
Sembra piuttosto facile, vero? Lo è realmente. Ogni volta che si verifica un messaggio/evento 'OnClick', il programma passa alla
vostra subroutine ButtonClicked ed esegue il codice in essa contenuto. Il programma qui sopra è completo, e potete provarlo voi
stessi. Per la lista di tutti gli eventi relativi ad un particolare componente, consultare la sezione Appendice.

3.5 Subroutine e funzioni di Rapid-Q
Ci sono alcuni particolari che riguardano le funzioni e le sub di Rapid-Q che è necessario conoscere. Il primo, e più
importante, è che tutti i valori passati sono passati per VALORE (tranne che per oggetti, varianti, udt, e matrici). Per passare
una variabile per riferimento, è necessario farla precedere da simbolo @. Il secondo particolare è che si possono accettare fino
ad un massimo di 10 parametri (tranne quando si chiama una funzione API, nel qual caso il limite è di 25). Non c'è differenza
nel modo in cui si creano sub o funzioni in Rapid-Q (contrariamente ad altri linguaggi Basic come QBasic/PB):
    FUNCTION FindMax (X AS INTEGER, Y AS INTEGER) AS INTEGER
      IF X > Y THEN
        FindMax = X      '' Il valore restituito è X
      ELSE
        FindMax = Y      '' Il valore restituito è Y
      END IF
    END FUNCTION
Il codice sopra indicato è valido, come pure il seguente:
    FUNCTION FindMax (X%, Y%) AS INTEGER
      IF X% > Y% THEN
        FindMax = X%      '' Il valore restituito è X
      ELSE
        FindMax = Y%      '' Il valore restituito è Y
      END IF
    END FUNCTION
Comunque, come potete notare, non si può avere FindMax% senza specificare AS INTEGER alla fine della funzione. Per passare una
variabile per riferimento, inserire un simbolo @ all'inizio della vostra variabile:
    SUB StrCat (Source AS STRING, Text AS STRING)
        Source = Source + Text
    END SUB

    A$ = 'Hello'
    StrCat(@A$, ' World!')
    PRINT A$                '--Dovrebbe dare: Hello World!
Oppure, se lo preferite, potete inserire la parola chiave BYREF nella lista dei parametri in questo modo:
    SUB StrCat (BYREF Source AS STRING, Text AS STRING)
        Source = Source + Text
    END SUB

    A$ = 'Hello'
    StrCat(A$, ' World!')
    PRINT A$                '-- Dovrebbe dare: Hello World!
Un altro possibile approccio può essere questo (notare che questo è il 'vecchio' sistema, mantenuto per motivi di
compatibilità ):
    SUB Strcat (A$, B$)
       A$ = A$ + B$
    END SUB

    A$ = 'Hello'
    Strcat(A$, ' world!')
    A$ = STACK.STR(0)
    PRINT A$
Lo stack contiene una matrice di numeri interi e stringhe; per accedere al parametro corretto, bisogna specificare il numero (da
sinistra a destra). Il primo elemento è 0. È possibile anche passare oggetti, ma non è possibile utilizzarli come un valore di
ritorno.
    SUB (Button AS QButton)
        Button.Left = 100
    END SUB
Tutti i componenti/oggetti sono passati per riferimento.

3.6 Area di validità 
In questo caso Rapid-Q non è come Basic. Dal momento che Rapid-Q è un semplice compilatore dall'alto verso il basso in una
passata, l'area di validità è molto simile a quella di Pascal. Ecco un esempio:

       SUB Test
          DIM I AS INTEGER
          I = 100
          PRINT I
       END SUB

       DIM I AS INTEGER
       I = 10

       SUB Test2
         PRINT I
       END SUB

       Test    '' Chiama  Subroutine
       Test2
Ecco come funziona la validità ; per la SUB Test, la variabile LOCALE I si estende fino alla fine del blocco di quella SUB. La
variabile I nel programma principale è valida fino alla fine del programma. Ciò significa che la SUB Test2 può utilizzare la
variabile globale I in quanto è all'interno della sua area di validità . È anche possibile ridichiarare la variabile I nella SUB
Test2, nel quale caso è utilizzata la variabile locale I invece della variabile globale I. Ecco un'altra situazione per
illustrare l'area di validità delle variabili:
       DIM I AS INTEGER

       SUB Scope (I AS INTEGER)
         DIM I AS INTEGER
         PRINT I
       END SUB

       PRINT I
In effetti, la riga DIM I AS INTEGER è inutile, in quanto la variabile I è superata dal nome di parametro I. Rapid-Q vi
avvertirà di questo, ma non segnalerà errori.



' ===============================================================================
'                      2003 Holyguard.net - 2007_Abruzzoweb