From the documentation of RAVAL, the MIT library of the books: the same as in its repository.

This page is available in Italian only for now.

Log e impostazioni — RAVAL 2.2

Le due cose che ogni programma vero si scrive il primo giorno: un log che dice cosa è successo, anche sul computer del cliente, e un file di impostazioni che ricorda le scelte dell'utente. In RAVAL sono scritte da zero, con licenza MIT come il resto della libreria; le idee vengono dal modo in cui lavorano i programmi dell'autore (livelli, file che ruota, riga di avvio, valori mancanti aggiunti al file).

Spiegazione con un esempio completo: TUTORIAL.md, capitolo 16. Ogni membro, con la sua firma, è nel riferimento API.md. Le prove sono in TEST_RAVAL\ProveApp.cs.

Il log — App\RLog.cs, UI\RLogView.cs

RLog.Start("Astrip", "1.4.0", "log/astrip.log");    // la prima riga: nome, versione, computer, .NET, pid
RLog.CatchUnhandled();                              // anche le eccezioni che nessuno prende
RLog.Info("progetto aperto: " + percorso);
RLog.Error("salvataggio non riuscito", ex);
RLog.Stop();                                        // alla fine: scrive quello che resta

Le impostazioni — App\RSettings.cs, RJsonSettings.cs, RIniSettings.cs

RSettings s = RSettings.Open(RSettings.Folder("Astrip") + "/settings.json");   // .ini per un file INI
int porta = s.GetInt("server.port", 5080);
s.Set("server.port", 5081);                          // il file si salva da solo mezzo secondo dopo
s.Remember(this, "window.main");                     // la finestra riapre dov'era
var recenti = new RRecentFiles(s, "files.recent");   // File → Recenti

Le chiavi sono percorsi con i punti. In JSON «server.port» è il campo port dell'oggetto server; in INI è la chiave port della sezione [server], e la sezione è tutto quello che sta prima dell'ultimo punto («window.main.x» è x in [window.main]). Le stesse chiamate valgono per i due formati.

Il JSON si scrive rientrato e con gli accenti come sono («città», non città): il file è fatto anche per essere aperto e corretto a mano.

Perché è fatto così

• Chi scrive nel log non aspetta il disco. La riga va in una coda e la scrive un thread del log: una chiamata costa uguale sul thread dell'interfaccia e su un thread di lavoro, e le righe di thread diversi non si mescolano mai a metà (la prova scrive 400 righe da quattro thread e le ritrova tutte intere).
• Il file del log ruota. Un programma che resta acceso per mesi non riempie il disco.
• Ogni lettura ha il suo predefinito. Un file mancante o rovinato non ferma mai il programma; un file che non si legge si rinomina «.bad» e si scrive un avviso nel log, così la copia dell'utente non si perde.
• Le chiavi lette vengono scritte nel file (AddMissing): dopo il primo avvio il file elenca tutte le opzioni del programma, e chi lo modifica a mano le vede tutte.
• Il salvataggio aspetta mezzo secondo. Una finestra trascinata manda centinaia di posizioni: il file si scrive una volta sola, alla fine. Si scrive un file temporaneo e poi lo si rinomina, così un arresto a metà lascia il file vecchio, non uno spezzato.
• Il file INI resta quello dell'utente. Commenti, righe vuote e ordine delle chiavi restano dove sono; un valore cambiato riscrive solo la sua riga. Il valore è tutto quello che segue il primo «=»: un «;» dentro un valore (un percorso, una lista) ne fa parte, e i commenti vanno su una riga a sé.
• La finestra ricorda la misura di quando era normale. Chiusa ingrandita, riapre ingrandita, e quando la si riduce torna al suo posto. Se lo schermo su cui stava non c'è più (un portatile senza il monitor), si apre al centro dello schermo principale invece che fuori dalla vista.

Il tema — App\RTheme.cs, UI\RThemes.cs

Le lingue — App\RLang.cs

Inciampi

• Un pennello tenuto in un campo non cambia con il tema (trovato in ASTRIP): un controllo disegnato a mano chiede i colori in Render con ThemeBrush e si ridisegna con OnThemeChanged; preso all'avvio, il pennello resta quello del primo tema. Per fotografare nei due temi, fra il cambio e la foto si fa girare il dispatcher.
• Le righe scritte prima che la vista entri nella finestra andavano perse. RLogView leggeva le righe in memoria quando veniva creata e ascoltava Written solo dopo, quando entrava nella finestra: quello che il programma scriveva in mezzo non compariva da nessuna parte. Ora la vista prima si iscrive a Written e poi legge Recent. Una riga scritta proprio in quel momento sta in tutti e due; il numero progressivo della riga (RLogEntry.Number) fa saltare la seconda copia.
• I numeri delle righe non arrivano in ordine. Il numero si assegna quando la riga nasce, ma due thread possono mettere in coda la 6 prima della 5. Per questo la vista riconosce le copie con l'insieme dei numeri già presi, e non con «numero minore dell'ultimo», che avrebbe scartato la 5.
• Le voci di un ListBox di Fluent sono alte come un bottone (margine interno 12 × 9): un log ne mostra la metà. RLogView le stringe con uno stile messo solo sulla sua lista: RStyles.Apply(controllo), che non tocca il resto dell'applicazione.