Istruzioni.txt ---------------------------------------------------------------------------------
 
ExcelXML.py

  Modulo scritto in python per creare da programma file Excel formato Foglio XML (Excel 2003)

------------------------------------------------------------------------------------------------
 
Istallazione

Unzippare dove si vuole e provare a lanciare i programmi di test.

Il modulo ExcelXML.py non ha prerequisiti e pu essere usato in qualunque ambiente (anche Linux, 
MacOSX) in cui sia presente una versione recente di Python, senza che sia necessaria la presenza 
del prodotto Excel.

Lanciare i programmi di prova TestExcel1.py e TestExcel2.py cos come sono e vedere il risultato
Prova1.xml e Prova2.xml in Excel.

TestSQLExelExport.py richiede PythonWin, e va adattato per fare una Query sul database
relazionale che si ha a disposizione, cambiando nel sorgente la stringa di connessione e la Select.

Query2Excel.py  un programma di utilit che usa una interfaccia GUI per richiedere all'utente
i parametri di connessione al DB e la Select, il cui risultato  da trasformare in Excel.
Deve essere gi definito un Driver ODBC per la connessione al proprio database.
Richiede l'installazione aggiuntiva di: PythonWin (per l'uso di ADO) e wxPython 
(per l'interfaccia GUI).
L'interfaccia GUI  stata sviluppata con wxGlade 0.6.3 e Query2Excel.wxg  il file relativo.

Se il modulo ExcelXML.py  soddisfacente, pu essere copiato nella directory Lib di Python
in modo da poter essere usato da qualunque applicazione.


------------------------------------------------------------------------------------------------
 
Uso

  Il modulo ExcelXML.py pu essere usato per creare un file completamente nuovo o per aggiungere 
  WorkSheet o Stili ad un file Excel precedentemente salvato nello stesso formato (ottenendo un 
  nuovo file).

  La logica d'uso  la seguente:

  Istanziare se necessario una o pi strutture di tipo
    xlsSheetStruct            per definire uno o pi fogli con caratteristiche diverse dal default
                              (qui vi sono i margini, l'intestazione, il pi di pagina, ecc.)
    xlsStyleStruct            per definire uno o pi stili di cella diversi dal default
                              (qui vi sono colori, bordatura, font, ecc. della cella con questo stile)
  e variarne le propiet, da usare successivamente


La Struttura di definizione di un foglio (istanza di xlsSheetStruct) pu essere personalizzata 
  cambiando le seguenti property: (il valore dato qui  il valore di default)

      SheetName    = ""            # nome breve senza spazi in mezzo
      Description  = ""            #
      FootPage     = ""            #
      HeaderMargin = 0.5           # in Inch, default = "0.5"
      FooterMargin = 0.5           # in Inch, default = "0.5"
      MarginTop    = 1             # in Inch, default = "1", anche numero decimale
      MarginBottom = 1             # in Inch
      MarginLeft   = 1             # in Inch
      MarginRight  = 1             # in Inch
      PrintGrid    = True          # se vero, in stampa visualizza la griglia (default = "1")
      Protected    = False         # se vero, protegge il Foglio, altrimenti = "0" (default)
      RowHeight    = 0             # altezza di default delle righe (0 = non gestita, 16 = normale)
      Layout       = "L"           # pu essere 'P' (portrait) o 'L' (landscape)

La Struttura di definizione di uno stile di cella (istanza di xlsStyleStruct) pu essere personalizzata 
  cambiando le seguenti property: (il valore dato qui  il valore di default)

      ID           = ""              # ID, ossia stringa senza spazi in mezzo, che identifica lo Stile
      # Allineamento del testo contenuto nella cella
      Align        = "Left"          # "Left" (default), "Right", "Center"
      VAlign       = "Bottom"        # "Top", "Bottom" (default), "Center"
      Indent       = 0               # numero di caratteri di rientro del testo
      # Bordo della cella
      BorderType   = "Continuous"    # (=LineStyle) di default  "Continuous", pu essere anche:
                                     #  "Double", "Dot", "Dash", "DashDot"
      BorderColor  = ""              # di default  "#000000" = nero
      BorderTop    = 0               # 0 = nessun bordo in alto, altrimenti valore da 1 a 3 (= Weight)
      BorderBottom = 0               # 0 = nessun bordo in basso, altrimenti da 1 a 3
      BorderLeft   = 0               # 0 = nessun bordo a sinistra, altrimenti da 1 a 3
      BorderRight  = 0               # 0 = nessun bordo a destra, altrimenti da 1 a 3
      # Caratteristiche del Font usato nella cella
      FontName     = ""              # nome del font, se nessuno,  il font di default
      FontBold     = False
      FontItalic   = False
      FontSize     = 0		     # grandezza font in punti (default 10?)
      FontColor    = ""              # di default  "#000000" = nero
      # Caratteristiche dello sfondo della cella (Interior)
      BGcolor      = ""              # di default nessuna colorazione (bianco) 
      BGpattern    = "Solid"         # nome del pattern di colorazione, di default "Solid", pu essere anche, tra gli altri:
                                     # "Gray50", "Gray25", "Gray125", "Gray0625", "ThinDiagStripe", "ThinReverseDiagStripe",
                                     # "ThinDiagCross", "ThinHorzCross", "ThinHorzStripe", "ThinVertStripe", ecc.
      BGpatternColor  = ""           #
      NumberFormat = ""              # di default niente, pu essere "Fixed", "Scientific", "Short Date", ecc.
      WrapText     = False           # di default niente, pu essere "1" per andare a capo nella stessa cella
      VerticalText = False           # di default niente, pu essere "1" per testo scritto verticalmente
      Rotate       = 0               # di default nessuna rotazione, altrimenti  l'angolo in gradi, anche negativo
      Protected    = False           # se = "1" protegge la cella, altrimenti = "0",
      # i colori vanno usati come stringhe RGB esadecimali, del tipo "#rrggbb", oppure usando
      # il nome del colore inglese in minuscolo



  Poi istanziare:

  - xlsExcel([NomeFile], [Autore], [SheetStruct])

    per inizializzare il file e preparare i tre stili di default (txt, num e date)
    Se il nome file manca, il file xml viene creato in memoria e (dopo xlsClose) pu
    essere recuperato con la propiet xlsOut (che  una lista di stringhe che compongono
    il file Excel in formato XML nella sua completezza) 
    SheetStruct  una variabile precedentemente istanziata di tipo xlsSheetStruct che rappresenta
    il foglio di default, che verr usato nelle successive aggiunte di Worksheet.

  Richiamare i metodi (in quest'ordine):

  - xlsAddStyle(StyleStruct, [IDstile])

    lanciata opzionalmente (anche pi volte) per aggiungere gli stili aggiuntivi voluti delle celle
    StyleStruct  una variabile precedentemente istanziata di tipo xlsStyleStruct
    IDstile  l'ID della struttura, che viene richiamato alla scrittura dei dati; se non  presente
    deve essere assegnato all'interno della struttura stessa

  - xlsAddSheet([nomeFoglio], [SheetStruct])

    inizializza la scrittura di un nuovo foglio
    SheetStruct  una variabile precedentemente istanziata di tipo xlsSheetStruct
    Se nomeFoglio non  fornito, deve essere presente all'interno della struttura
    (Pi chiamate permetteranno di scrivere pi fogli Excel nello stesso file)

    A questa funzione devono seguire una o pi chiamate alla funzione xlsColumn() (se si vogliono
    differenziare le colonne tra loro) e poi
       xlsWriteCell() che scrive materialmente i dati del foglio in esame, in sequenza da sinistra
    a destra e dall'alto al basso, finch
     - o si richiama nuovamente xlsAddSheet per chiudere il precedente e aprire un nuovo foglio
     - o si chiude tutto con xlsClose()

  - xlsColumn(numColonna, Larghezza, [IDstile])

    imposta la Larghezza in visualizzazione di ciascuna colonna ed eventualmente lo stile;
    deve seguire immediatamente la funzione xlsAddSheet()
    le colonne specificate devono essere in ordine crescente a partire da 1, eventualmente
    saltando quelle in cui si vuole lasciare i default
    La Larghezza da impostare  circa uguale al numero di caratteri * 4 (con i caratteri di default)

  - xlsWriteCell(Valore, [Tipo, IDstile, formula, skipCol, MergeAcross, MergeDown])

    scrittura del dato nella cella; le celle devono essere in ordine crescente dentro la stessa riga
    Tipo pu essere "S" (Stringa, di default), "N" (Numero) e "D" (Data, non ancora gestito);
    Valore in input pu essere un unico valore o una lista di valori, nel qual caso ciascuno
    andr in una cella distinta della stessa riga
    IDstile deve essere tra quelli definiti, altrimenti avr uno stile di default; se  = None non gli
    verr assegnato alcun stile e quindi prender lo stile della riga, della colonna o del tipo di dato.
    Se MergeAcross > 0, indica che la cella si estende anche ad una o pi celle successive a destra
    Se MergeDown > 0, indica che la cella si estende anche ad una o pi celle successive in basso

  - xlsNewLine([skip], [RowWidth], [IDStile])

    passa alla riga successiva (o alla successiva + skip); la nuova riga pu avere la
    larghezza impostata a RowWidth e lo stile = IDStile

  - PosizioneCella = xlsGetPosition()

    restituisce le coordinate assolute della cella relativa attuale come stringa (per l'uso nelle formule):
    PosizioneCella  la posizione nella forma Excel "Lettera" + "numRiga" (ossia colonna + riga)
    Riga, Colonna attuali (in formato numerico) si possono ottenere dalle variabili di istanza:
       ActualRow, ActualCol

  - Rettangolo = xlsGetRectangle(R1, C1, R2, C2)

    date in input le posizioni assolute Riga1+Colonna1, Riga2+Colonna2, che definiscono un rettangolo di celle,
    viene restituita la stringa che definisce la posizione relativa del rettangolo rispetto la cella attuale
    Serve come aiuto per definire le formule

  - xlsClose()

    deve essere l'ultima istruzione che chiude il file



  Se si vuole fare il Merge con un altro file Excel esistente in formato Foglio XML:

  Istanziare xlsExcel con parametri differenti:

  - xlsExcel([NomeFile], OldExcelFile="NomeFileOld")

    Viene generato un file che contiene i fogli vecchi presi dal file "NomeFileOld" pi quelli nuovi generati.
    A questa funzione seguono le altre nel solito modo, in cui gli stili che sono gi presenti con lo stesso ID
    non vengono aggiunti se scritti da programma e gli sheet generati vengono aggiunti in fondo a quelli gi presenti

  Richiamare, prima di aggiungere qualunque worksheet:

  - xlsSheetDelete(nomeFoglio)

    nel caso di Merge, nel file generato cancella il foglio indicato; deve essere usata (anche pi volte)
    prima di generare il primo sheet
    Deve essere richiamata subito dopo xlsExcel e prima di xlsAddSheet


  Con questo modulo, non  possibile leggere o cambiare i dati di un foglio Excel esistente.

