Pagine

2026-10-17

Libri, pubblicazioni e formule - 2


Benvenuti a questa seconda parte, che riassumono i problemi incontrati per creare un libro con molte formule matematiche. La prima parte, con le scelte di partenza, la trovate qui:

Pubblicazioni e formule

Quindi, riassumo i punti ottenuti:

  • abbandonato in questo caso LaTeX, non per problemi non risolvibili, ma perché le piattaforme di pubblicazione (e gli utenti) preferiscono il formato ePUB, per i lettori tipo Kindle e altri, mentre i pdf, anche se più belli a vedersi, sono statici, non potendosi adattare a una finestra qualunque;
  • il passaggio da LaTeX ad ePUB non è una trasformazione così semplice e può convenire, anche se con un certo lavoro, a chi ha già una certa mole di roba scritta in LaTeX;
  • ho scelto Quarto, un software basato sul markdown, che accetta le formule in LaTeX; l'uscita può avvenire in contemporanea in più formati dagli stessi file;
  • le formule vengono trasformate in ePUB (html) usando mathml e questo soddisfa le richieste di Apple Books; ma con altri reader più datati, bisogna sostituirle con immagini SVG;
  • a quanto sembra, solo passando da LaTeX si possono ottenere gli SVG, ma non voglio un'intera installazione LaTeX solo per quello, per cui andiamo su un contenitore docker, che contiene tutto il necessario.

Il contenitore

Partiamo col costruire un file chiamato dockerfile che crei una macchina minimale contenente le parti necessarie di LaTeX, per le nostre formule; evitiamo la TeXLive completa, inserendo quello che potrebbe servire. Parto da un Ubuntu:

FROM ubuntu:22.04 ENV DEBIAN_FRONTEND=noninteractive

Ora introduciamo le sezione di LateX che supponiamo utili (possiamo fidarci di quanto ci fornisce il package manager di Ubuntu):

RUN apt-get update && apt-get install -y \ texlive-latex-base \ texlive-latex-extra \ texlive-science \ texlive-extra-utils && rm -rf /var/libe/apt/lists/* WORKDIR /data

Una volta che tutto funzionerà, si potrà provare a togliere qualcosa, per ottenere l'installazione minima. Però mancano ancora due pezzi: il primo è dvisvgm che è il nucleo della trasformazione in SVG e poi gladtex, un pre-processore che fa il passaggio intermedio, evidenziando con il tag <eq> le formule da trasformare e poi le sostituisce con le immagini tornate. Entrambi sono disponibili dal package manager, per cui alla fine il nostro dockerfile è

FROM ubuntu:22.04 ENV DEBIAN_FRONTEND=noninteractive RUN apt-get update && apt-get install -y \ gladtex \ texlive-latex-base \ texlive-latex-extra \ texlive-science \ texlive-extra-utils \ dvisvgm \ && rm -rf /var/lib/apt/lists/* WORKDIR /data ENTRYPOINT ["gladtex"]

La configurazione

La costruzione del container è stata la parte più semplice. Ora però dobbiamo riprendere i file markdown e metterli assieme usando la configurazione del libro, che per Quarto significa costruire il file _quarto.yml (la sottolineatura iniziale è voluta):

project: type: book # tipo di progetto output-dir: _output # cartella di uscita dei vari formati book: title: "Problemi di Fisica" subtitle: "Un sottotilo furbo" cover-image: cover.png author: "Proprio Me Stesso" date: "2026-01-01" language: it # utile in certi casi

Questa parte indica che si tratta di un libro, con il suo titolo, autore, copertina, ecc... Bisogna notare che il file .yml prevede che ogni rientro sia esattamente di 2 spazi e che non vuole i tabulatori.

Segue poi la struttura del libro, suddiviso in capitoli e, volendo, anche parti (la faccio semplice):

# Struttura del libro - ogni file con il suo percorso chapters: - index.qmd # cartella principale, accanto a _quarto.yml - part: "Prima parte" chapters: - cartella/misure.qmd # all'interno di una cartella - cartella/altra_cartella/cinematica.qmd # cartella al secondo livello format:

dove la parola chiave chapter è al livello di language: it.

Ora c'è il bello di Quarto: dopo la parola chiave format: possiamo inserire informazioni relativi ai formati che vogliamo in uscita; l'uscita html è utile per avere un preview rapido praticamente identico all'ePUB (che, abbiamo detto, è in sostanza un html):

html: # metodo matematico da usare - conosciuto da tutti i browser html-math-method: mathml # figura PNG alla stessa risoluzione dell'ePUB fig-format: png fig-dpi: 300 # tema minimo sans-serif, simile a un e-reader, chiaro o scuro theme: light: flatly dark: darkly # Navigazione toc: true # vogliamo l'indice... toc-depth: 3 # ...fino al terzo livello... toc-tutle: "Indice" # ...con questo titolo number-sections: true number-depth: 3 # se necessario inseriamo un foglio di stile aggiuntivo se non piace qualcosa css: stili.css

Il formato html è utile per avere un aggiornamento a colpo d'occhio; in VS Code è possibile tenerlo aperto affiancato al file che sto modificando e si aggiorna ogni volta che viene salvato il file. Se volessimo mostrare il libro su un sito apposito, non dobbiamo preoccuparci dei comandi html: l'uscita è completa di tutto, anche del javascript per l'indice, i passaggi da una sezione all'altra e persino per la ricerca all'interno del sito. Stiamo usando il formato Mathml per le formule perché riconosciuto normalmente da tutti i browser moderni; il più comodo MathJax, che accetterebbe direttamente il LaTeX, avrebbe bisogno di una libreria aggiuntiva.

Potremmo anche volere in uscita un pdf, dove la chiave (al posto di html) è typst: come detto nella prima parte, typst può creare un pdf da solo, usando però un linguaggio diverso da LaTeX, ma pandoc si occupa di tutto. Un pdf può essere utile quando vogliamo rileggere il documento, inserendo annotazioni, sottolineature e altro (sul computer o su un tablet un pdf è più semplice da annotare); è possibile inserire in questo formato anche un eventuale file di preambolo. Ma andiamo a quello che ci serve: passiamo al formato ePUB per i lettori tipo Apple Books o che comunque supportano la matematica con Mathml nativo:

# ------- # ePUB per Apple Books - Mathml # ------- epub: output-file: "Problemi_di_Fisica.epub" # nome del file finale toc: true toc-depth: 3 number-sections: true html-math-method: mathml # questo è importante epub-cover-image: cover.jpg title-page: true fig-format: png dpi: 300 css: stili.css epub-version: 3

Ho inserito gli stessi comandi di prima, così html e ePUB dovrebbero essere molto simili e mi basta vedere il primo mentre scrivo. Questa uscita porta ad un ePUB che, su un Mac, è facilmente controllabile caricandolo su Apple Book oppure su Calibre. Come scritto nella configurazione, ci affidiamo alle formule trasformate da Quarto (in realtà è pandoc a farlo) in formato Mathml e l'e-reader, basandosi su un motore web (WebKit per Apple Books), ci mostra le formule con un buon risultato visivo.

Ora passiamo invece al formato che dobbiamo usare per poter essere letti anche su Kindle piuttosto vecchi, cioè usando immagini SVG delle formule; definiamo un formato apposito, che chiamo epub+kindle cominciando ad inserire i soliti dati comuni:

epub+kindle: output-file: "Problemi_di_Fisica_Kindle.epub" toc: true toc-depth: 3 number-sections: true title-page: true epub-cover-image: cover.jpg fig-format: png dpi: 300 css: math_style.css # usato soprattutto per il posizionamento delle formule epub-version: 3 # html-math-method: plain # pandoc-args: # - "[--gladtex]"

Ho aggiunto le ultime tre righe commentate perché sono quelle consigliate un po' dappertutto, che però non raggiungono il risultato: in pratica, dicono di non usare alcun metodo per le formule e passare l'argomento --gladtex a pandoc, quando viene chiamato da Quarto. In realtà, questo argomento non fa eseguire gladtex: si limita a racchiudere le formule in tag XML del tipo <eq env="math"> o <eq env="displaymath">, a seconda che si tratti di una formula all'interno di una riga di testo o sia una formula centrata sulla propria riga; tutto questo viene inserito nell'output html, lasciando la compilazione vera e propria ad un successivo passaggio.

In teoria, dovremmo ora fare una chiamata al compilatore LaTeX per ogni formula, che tramite dvisvgm ci ritorna la figura in SVG, da richiamare nel codice html. Chiaro che non possiamo farlo a mano per ogni formula! Ecco allora che useremo un filtro scritto in Lua che faccia tutto quello che serve da solo e per tutte le formule. Quindi aggiungiamo la chiamata al filtro nel file di configurazione di Quarto e inseriamo alcune cose utili per tutti i formati:

filters: - math-svg.lua # impostazioni generali fig-width: 6 fig-height: 4 fig-align: center editor: visual crossrefs-hover: true # importante, da non dimenticare

Ma non voglio far diventare troppo lungo questo post: il finale alla prossima puntata, in cui vedremo il filtro da applicare e come chiamare la macchina dentro il contenitore docker, facendogli compilare la formula e trasformandola in SVG.

Alla prossima!

2025-08-26

LaTeX: modificare un ambiente di lista

La modifica o l'introduzione di comandi in LaTeX è abbastanza semplice: in casi elementari basta usare i comandi \renewcommand (nel caso della modifica) e \newcommand (per la creazione di uno nuovo) e siamo a posto. La sintassi è:

\newcommand{nuovo_comando}{testo_da_inserire}

Spesso si ha la necessità di usare la stessa sequenza di comandi, modificando solo alcune parti. Occorre allora utilizzare i parametri, valori che vengono passati al codice, che li sostituisce ai segnaposto inseriti nel punto giusto. La sintassi è del tipo:

\newcommand{nome_comando}[numero_parametri]{codice_con_segnaposto}

ed i segnaposto sono identificati #1 (primo parametro), #2 (secondo parametro) e così via. Per esempio, nell'intestazione di un compito, potremmo inserire il nome dello studente (primo parametro), la classe (secondo parametro) e la data (terzo parametro); il comando potrebbe essere definito nel preambolo del documento come:

\newcommand{\intestazione}[3]{Studente: #1 Classe #2 Data #3}

Notiamo che è importante mantenere l'ordine previsto dei parametri; inoltre, diventano tutti obbligatori (a parte il primo, se forniamo il suo valore tra parentesi quadre.

Usando il pacchetto xparse (sulle installazioni recenti di LaTeX non è più necessario caricare questo pacchetto), è possibile usare un comando più flessibile:

\NewDocumentCommand\DueArgomenti{mm}{Nel testo c'è #1 ma anche #2}

I due caratteri m indicano che dobbiamo inserire due parametri obbligatori (dall'inglese mandatory); come prima, i loro segnaposti sono indicati con #1, #2; essendo obbligatori, la chiamata sarà come al solito:

\DueArgomenti{il primo}{il secondo}

e l'uscita sarà "Nel testo c'è il primo ma anche il secondo". Però questa nuova sintassi ci permette di definire tutti i parametri opzionali che vogliamo, definendo cosa deve succedere se non li forniamo. Mentre m indica un parametro obbligatorio, la sintassi O{valore_default} (vocale 'O' maiuscola) permette di indicare l'esistenza di un parametro e se questo non viene indicato, assume il valore indicato tra parentesi (e tale valore può anche essere vuoto). Per esempio:

\NewDocumentCommand\TreArgomenti{O{}O{Mario}m}{#1 #2 #3} \TreArgomenti{Rossi} % Mario Rossi - nessun parametro opzionale \TreArgomenti[dr]{Rossi} % dr Mario Rossi - solo il primo opzionale \TreArgomenti[dr][]{Rossi} % dr Rossi - il secondo è presente ma vuoto \TreArgomenti[][]{Rossi} % Rossi - opzionali tutti vuoti \TreArgomenti[]{Rossi} % Mario Rossi - il primo è vuoto, manca il secondo

Le stesse cose valgono anche per la definizione di ambienti LaTeX, come liste; la sintassi è la stessa di \newwnvironment, il comando da usare è \NewDocumentEnvironment, la cui sintassi è simile:

\NewDocumentEnvironment{nome_ambiente}{parametri} {codice_iniziale} {codice_finale}

Con queste conoscenze, ora costruirò un esempio un po' più complesso, usato per una mia necessità: volevo usare una lista numerata meno anonima di quella standard, con qualche piccolo inserto colorato, in modo da evidenziare ogni elemento (trattandosi di elementi piuttosto lunghi, mi serviva qualcosa di ben visibile, senza esagerare). Non volevo però ridefinire l'ambiente, per poter usare la lista predefinita in altri punti del documento.

Devo quindi definire un nuovo ambiente; volendo inserire dei colori, meglio caricare il pacchetto xcolor e, dato che dovrò giocare con la lista, inserisco anche il pacchetto enumitem:

\usepackage{enumitem} \usepackage{xcolor} \NewDocumentEnvironment{myenum}{} {}{}

Questo ambiente non fa nulla; facciamo in modo che sia lo stesso dell'ambiente standard, in modo da partire da una base nota:

\NewDocumentEnvironment{myenum}{} {\begin{enumerate}} {\end{enumerate}}

Ora aggiungiamo qualche opzione sulla lista nella parte iniziale:

{\begin{enumerate} [ left=0pt, % il numero parte a inizio testo labelsep=1.0em, % aumento spazio tra numero e testo itemsep=1.5em, % aumento spazio tra gli item label=\textcolor{red}{\fcolorbox{blue}{yellow}{\textbf{\arabic*}}} ] }

L'ultima riga già fornisce quello che cercavo: etichetta numerata in grassetto (\textbf{\arabic*}) e scritta in rosso (\textcolor{red}), all'interno di un riquadro con sfondo giallo e bordo blu (\fcolorbox{blue}{yellow}).

Il risultato non è male:

Mi viene però l'idea di inserire una riga blu all'inizio e alla fine dell'ambiente, per evidenziarlo. Allora, prima dell'apertura dell'ambiente enumerate, inserisco un comando \rule{colore}{spessore}, preceduto da un \color{colore}.
Mi accorgo subito di due cose: devo mettere questi comandi all'interno di parentesi {}, altrimenti il colore si propaga al testo seguente (tutti gli item in blu!); poi, sempre all'interno delle parentesi, devo far precedere il tutto da un nuovo paragrafo \par, in modo da terminare il testo precedente il nuovo ambiente e andare a capo prima di cominciare a numerare i paragrafi; alla fine il comando è

{\par\color{blue}\rule{\textwidth}{2pt}}

Per inserire la riga blu alla fine, devo usare la seconda parte del nuovo ambiente: subito dopo la chiusura \end{enumerate}, aggiungo:

\color{blue}\rule{\textwidth}{2pt}\vspace{1.0em}\par

dove per qualche motivo non servono le parentesi ed il nuovo paragrafo viene messo alla fine, per preparare le condizioni per il nuovo testo. Personalmente, ho preferito aggiungere un \vspace{1em} per allontanare un po' il testo che viene dopo la chiusura dell'ambiente.

L'effetto è ottimo, però sto diventando perfezionista (anche perché così imparo cose nuove!): vorrei che ogni item fosse separato dagli altri da una linea blu, magari più sottile di quelle iniziali/finali. L'unico modo per introdurre una riga per ogni item è di ridefinire il comando \item... e qui le cose si complicano: il comando è piuttosto delicato di suo, basta aggiungere un \par o altri tipi di spazi e la sua struttura non lo accetta, fornendo errori oscuri. Inoltre, tracciare una riga prima di ogni item, porta ad avere due righe all'inizio (una come inizio dell'ambiente, l'altra come inizio dell'item), il che porta a dover definire un contatore, che non tracci la riga se si tratta del primo item. Ancora: se modifichiamo l'item, dobbiamo poi ristabilirlo alla fine, altrimenti tutti gli ambienti enumerate lo useranno.

Il linguaggio TeX non è dei più intuitivi, per cui ho dovuto mischiare ricerche in rete e prove su prove. Dopo un bel po' tentativi infruttuosi (anche chiedendo aiuto all'AI, senza risultati apprezzabili), sono riuscito a mettere su un codice che funziona, anche se non sono sicuro del perché; su questo codice basta modificare qualcosa senza importanza... che subito smette di funzionare! Tuttavia, funziona, per cui lo pubblico. Contemporaneamente ho inserito la possibilità di usare dei parametri per i colori, impostando anche dei valori di default. Il listato finale, da inserire nel preambolo del documento, è il seguente:

\newcounter{colorenumcounter} % definizione di un contatore per evitare la riga sul primo item \NewDocumentEnvironment{myenum}{ O{blue} % colore delle righe di separazione O{red} % colore del testo del numero O{yellow}} % colore dello sfondo del numero { \par % nuova riga / stacca dal testo precedente \setcounter{colorenumcounter}{0} % inizializzo il contatore \let\olditem\item % salvo codice standard per comando \item \renewcommand{\item}{ % definisco nuovo codice per \item % riga vuota necessaria per mandare a capo la linea \stepcounter{colorenumcounter}% % aumento il contatore \ifnum\value{colorenumcounter}>1 % se non è il primo item... {\color{#1}\rule{\linewidth}{1pt}}% % disegno la linea \fi \olditem% % in ogni caso introduco il vecchio \item } {\color{#1}\rule{\textwidth}{2pt}}% % disegno la riga prima dell'inizio dell'ambiente \begin{enumerate} % inizio l'ambiente standard [ left=0pt, label=\textcolor{#2}{\fcolorbox{#1}{#3}{\textbf{\arabic*}}}, labelsep=1.0em, itemsep=1.5em, ] }{ \end{enumerate} % fine ambiente standard \par\vspace{1em}\color{#1}\rule{\textwidth}{2pt}\par % traccio linea colorata dopo l'ambiente \let\item\olditem % ristabilisco il vecchio codice, per gli ambienti successivi } % la chiamata con i valori di default: \begin{myenum} \item Prima riga \end{myenum} % mentre con uso di valori differenti: \begin{myenum}[red][yellow][blue] \item ... \end{myenum}

ed il risultato, con i valori di default è

Nota: Righe dove compaiono due segni di commenti (%): il primo, a fine riga del codice, deve essere mantenuto anche se si elimina quello che segue, per evitare che venga considerato il fine riga, che può portare anche ad errori oscuri.

Sarebbe anche possibile inserire come parametri gli spessori delle linee, oppure separare il colore della riga da quello del bordo del riquadro nel numero: basta aggiungere parametri all'inizio e poi inserirli nel posto giusto con #4, #5,...

--- --- ---

Se sei interessato alla tecnologia in genere, potresti provare a vedere il mio blog blog dove ogni tanto dico la mia su argomenti tecnologici. Se invece ti interessa la fisica, potresti provare la fisica di massimo, dove io e il mio gatto discutiamo di argomenti di Fisica.

2024-12-23

HTML: tag poco noti - sulle traduzioni

L'attributo TRANSLATE

Molti browser sono in grado di riconoscere in che lingua è stato scritto il testo di una pagina; allora, usando qualcuno dei servizi web (il più famoso è ovviamente quello di Google) possono fornire la pagina tradotta nella lingua preferita dall'utente, che avrà inserito questa informazione nelle preferenze del browser stesso.

Bisogna dire che ultimamente, tramite anche l'uso di un po' di AI, queste traduzioni stanno diventando leggibili, talvolta non ci accorgiamo nemmeno che la pagina originale è in una lingua completamente differente dalla nostra.

Però non sempre la traduzione completa è la cosa migliore è nei casi comuni i vari servizi fanno già una buona filtratura: la frase in inglese "pick the mouse and draw something on the screen" viene tradotta, giustamente come "prendi il mouse e disegna qualcosa sullo schermo"; d'altra parte, la frase "the cat caught the mouse" è tradotta come "il gatto ha preso il topo": il traduttore si è accorto che i due contesti sono differenti: nel primo caso ha riconosciuto che si trattava del dispositivo di puntamento di un computer, mentre nel secondo il riferimento indicava proprio l'animale. Allo stesso modo, il traduttore verso il francese sa invece che il mouse viene tradotto con souris, stesso nome dell'animale; quindi anche la lingua può essere importante.

Da notare che fino a poco tempo fa non era così scontato: qualcuno si ricorderà delle istruzioni di pulizia dei mouse, in cui si diceva "pulire la palla del topo"...

Tuttavia non sempre la procedura riesce a comprendere tutto alla perfezione, o addirittura qualche volta siamo noi che vorremmo che certe parole non fossero tradotte: per esempio, in una pagina pubblicitaria non voglio che il nome del prodotto, registrato esattamente in quel modo, venga mai tradotto. Sotto Natale (non so perché solo allora) compaiono pubblicità di profumi, in cui si usa il sostantivo francese parfum nel nome del prodotto anche in italiano. Qui diventa difficile anche per l'AI. Ed è qui che entra in gioco l'attributo translate.

È un attributo che può essere inserito in qualunque tag contenga del testo; se non presente, il valore di default è yes ed il testo contenuto al suo interno viene tradotto normalmente dal browser (o meglio, dal servizio invocato dal browser. Ma se invece viene inserito con valore no, il testo contenuto viene lasciato in originale, non tradotto:

<p translate='no'>Questo testo non viene tradotto</p>

Non è di uso frequente, ma qualche volta può essere utile, anche come indizio di professionalità di chi ha costruito il sito. È supportato da tutti i maggiori browser.

2024-12-09

HTML Tag poco noti...: DETAILS/SUMMARY

Questo è un altro tag (o meglio, una coppia di tag) piuttosto dimenticati, nonostante siano disponibili su tutti i browser da qualche anno.

Supponiamo di voler presentere presentare una pagina piuttosto ordinata, con eventualmente la possibilità di vedere dettagli e annotazioni non necessari ad una prima lettura. Penseremo certamente al famoso triangolino che, cliccato, ruota su se stesso ed apre uno spazio in cui compaiono i dettagli. Si tratta di un'interfaccia a cui ci hanno abituati il Finder del Mac e l'Explorer di Windows, per non parlare di Linux.

In questi casi, bisognava costruire "a mano" quello che serviva: il triangolino (una figura) seguita dal titolo; una funzione javascript si occupava di impostare a visibile la regione nascosta (di solito un <div>) e di sostituire il triangolino con la sua versione "aperta"; un secondo click faceva il contrario, nascondendo la regione e riportando il triangolo nella posizione chiusa. Trattandosi di un click sullo stesso oggetto, la funzione doveva prima stabilire se la condizione iniziale fosse aperta o chiusa. Nulla di trascendentale, però si trattava comunque di un certo numero di righe da scrivere.

Dal 2020 con i maggiori browser conosciuti non è più necessario tutto questo giro: basta inserire il tag <details>, che si occupa di aprire e chiudere il suo contenuto e aggiornare l'immagine del triangolino. Il tag  <summary> al suo interno presenta il titolo che dobbiamo cliccare per aprire e chiudere: il codice più semplice è il seguente:

<details>
<summary>Informazioni</summary>
Questa è l'informazione che viene mostrata.
</details>

Senza necessità di alcun javascript, questo codice porta al seguente effetto (cliccare sul triangolino):

Informazioni Questa è l'informazione che viene mostrata.

Il tag <summary> deve essere il primo a comparire all'interno del <detail>: se non c'è o non è il primo, il browser inserisce un suo default (di solito sarà qualcosa simile a Details).

Naturalmente, si possono poi stilare i componenti:

summary {
font-weight: bold;
color: red;
}

details {
border: 1px solid black;
border-radius: 4px;
padding: 4px;
color: gray;
}

details[open] summary {
color: blue;
}

ottenendo come risultato:

Informazioni Questa è l'informazione che viene mostrata.

Come si vede, è possibile mostrare stili differenti usando il termine [open] per indicare la situazione di aperto. È anche possibile far partire la pagina con i dettagli aperti, introducendo l'attributo open (se si vuole che parta chiuso, non lo si mette e basta: open = false non funziona!).

Ogni volta che un <summary> viene cliccato e quindi viene cambiato lo stato open/close, viene generato un evento toggle, che possiamo usare per aggiungere azioni.

Inoltre, possiamo creare una lista di tag <details> e se tutti hanno lo stesso attributo name="xyz", allora il broser si occupa anche di mostrare aperto solo uno della lista: cliccando su uno chiuso, questo viene aperto ed il precedente viene chiuso, tutto in automatico.

Ultima cosa: il tag <summary> viene preparato come un elemento di una lista (display:list-item), per cui è possibile usare le proprietà conseguenti per esempio per inserire icone diverse dal triangolino. Però non è possibile inserire l'animazione di apertura/chiusura, che col metodo vecchio veniva aggiunta tramite javascript. 

2024-11-24

HTML Tag poco noti...: DIALOG

Oggi esistono molti framework che permettono di costruire un sito o un'app usando linguaggi di alto livello, che quindi prescindono da una conoscenza puntuale di HTML. Tuttavia sapere quali sono le possibilità a propria disposizione è sempre utile ed usare sempre un framework che costruisce le cose significa anche da un lato fidarsi completamente e dall'altro non avere possibilità di introdurre cose nuove.

Con la solito filosofia di scrivere le cose qui allo scopo di ricordarle... riporto alcuni tag poco noti o usati in modo diverso dal solito, cominciando dal primo, di cui fino a poco tempo fa non conoscevo l'esistenza.

Dialog

Per far comparire un dialogo spesso si costruisce un <div> nascosto, cambiandone la visibilità quando necessario, oppure usando l'interfaccia di jQueryUI. È invece possibile fare tutto da HTML + CSS + JS; il codice della pagina si presenta molto semplice; quello che segue mostra un dialogo modale che presenta semplicemente un messaggio:

HTML

<dialog id="dialogo">
<p class="message">Sto avvisando l'utente</p>
<button id="closeButton">Ok, ho capito</button>
</dialog>

Javascript

const dialog = document.getElementById("dialogo");
const openButton = document.getElementById("openButton");
const closeButton = document.getElementById("closeButton");

//evento click di apertura del pulsante esterno al dialogo
openButton.addEventListener("click", () => {
dialog.showModal();
})

//evento click di chiusura del pulsante interno al dialogo
closeButton.addEventListener("click", () => {
dialog.close();
})

Avendo chiamato la .showModal(), il dialogo (alla fine, il browser) impedisce ogni azione sulla pagina sottostante, eliminando la necessità di porre al di sotto uno strato che intercetti il mouse. Se vogliamo che lo sfondo venga in qualche modo nascosto o ridotto in importanza (dato che non è attivo), possiamo usare lo pseudo-elemento ::backdrop; un esempio di foglio di stile minimale:

CSS

#dialogo {
border-radius: 5px;
}
#dialog::backdrop {
opacity: 0.8;
}

Se invece il metodo di apertura fosse stato .show(), allora il dialogo sarebbe stato non modale: la pagina sarebbe stata libera di interagire con l'utente (niente ::backdrop!), con tutti gli eventuali problemi (e soluzioni!) che arrivano in quel modo (tra questi, la necessità di poter individuare bene il dialogo e la possibilità di spostarlo col mouse).

Usare i risultati

Dialoghi con il solo pulsante di chiusura sono utili per comunicare un evento, con la sola necessità di sapere che l'utente l'abbia visto. Ma spesso è necessario avere una risposta dall'utente, per esempio quando ha appena richiesto la cancellazione di un elemento; è allora necessario un ritorno alla chiusura del dialogo.
Questo passaggio avviene tramite la variabile del Dialogo .returnValue: normalmente contiene il pulsante che ha lanciato il metodo .close() del dialogo (cioè il pulsante con cui si è chiuso il dialogo). All'evento di chiusura si otterrà il risultato del dialogo:

Javascript

//evento di chiusura del dialogo
dialog.addEventListener("close", () => {
doSomething(dialog.returnValue) //usiamo il risultato per qualcosa
})

Se abbiamo bisogno di più informazioni oltre al pulsante premuto (magari nel dialogo c'era un campo di testo e un menu) allora all'interno del dialogo dovrà essere previsto un form, che ci aiuterà a riportare indietro tutti i valori che ci servono.

Disponibilità

Il tag dialog e le sue funzionalità sono disponibili dal marzo 2022 e framework non aggiornati non lo usano. Tuttavia, è una funzionalità ormai assodata e accettata da tutti i browser moderni.

2019-08-02

Parametri negli URL

Può capitare di dover conoscere la query presente nell'indirizzo del browser: sono disponibili alcuni plugin di jQuery per questo compito (p.es. jsurl), ma ora è possibile ottenere il tutto tramite javascript puro, usando l'oggetto URLSearchParams e location.search.

var parametriURL = new URLSearchParams(location.search);
// location.search fornisce la stringa di query
// p.es. ?id=200&param=prova

Da questo oggetto posso ottenere un po' di informazioni:

// esiste il parametro id?
parametriURL.has("id") // true

// che valore assume il parametro 'param'?
parametriURL.get("param") // prova

Se invece vogliamo tutta la stringa di query:

parametriURL.toString() // id=200&param=prova

2019-07-30

Esportazione da Postgres in CSV

Talvolta può essere utile ottenere un file da una tabella di database, per esempio quando qualcuno chiede "...mi puoi mandare l'elenco degli oggetti in database in un formato leggibile da un essere umano, così controllo che sia tutto corretto?".
La prima cosa che viene in mente per esportare una tabella di un database è il formato CSV, leggibile da tutti i fogli elettronici dell'universo; ma come costringere il nostro database a copiare i suoi dati in quel formato?

Bene, se stiamo usando Postgres, non c'è nulla di più semplice: accediamo alla console di Postgres e potremo scrivere:

COPY nomeTabella(campo1,campo2) 
TO 'percorso_dove_scrivere.csv' 
DELIMITER ',' 
CSV HEADER

dove la parola chiave DELIMITER indica cosa usare come divisore tra le colonne e CSV HEADER indica che vogliamo i nomi dei campi all'inizio. Questo comando permette di esportare tutta una tabella, scegliendo eventualmente solo alcuni campi.
Alla fine basta andare al percorso che è stato inserito per trovare il file, pronto per essere importato in Excel o Numbers o LibreOffice.

Però talvolta non abbiamo accesso a tutta la macchina su cui gira Postgres, oppure quando siamo costretti ad usare ssh per accedervi; può allora essere utile utilizzare una funzione del comando psql.
Una volta entrati in ssh sulla macchina, diamo questo comando:

psql -d nomeDb -U utente -A -F"," -c "query_per_esportazione" > output.csv

Il comando -U serve se abbiamo accesso al db solo tramite un certo utente e non il root; il comando -F permette di scegliere il divisore tra i campi e dopo il comando -c possiamo inserire tra virgolette la query il cui risultato deve essere esportato. Ovviamente, il file di uscita può essere rappresentato non solo dal nome (output.csv) ma anche dal percorso, se necessario. Sarà il posto dove andremo a cercare il risultato.

NOTA: di solito il formato CSV usa la virgola per separare i campi (Comma Separated Values), ma i fogli elettronici hanno voluto scompaginare le convezioni: per esempio, se usiamo Excel in italiano, le virgole indicano la posizione del punto decimale e non vengono quindi riconosciute come divisori. Al loro posto, Excel usa "punto e virgola", per cui nel comando precedente dovremo usare -F";", altrimenti il foglio elettronico metterà tutto in una colonna unica.

Ricordiamo che se siamo in ssh, il file sarà poi portato sul nostro computer locale tramite il comando scp.

2014-09-01

NSManagedObject, Undo e dealloc

L'allegra compagnia definita nel titolo di questo post normalmente funziona felicemente assieme: anche se non si comprende bene bene perché, tutto va a posto e non c'è n'è dobbiamo preoccupare (per dirla alla Apple: it just works).
Ma la legge di Murphy ci dice che se qualcosa potrebbe non funzionare, certamente lo farà nel momento peggiore... Infatti...
Supponiamo di avere una sottoclasse di un NSManagedObject che ha bisogno di reagire al cambio di una delle sue proprietà; supponiamo di avere un attribute posizione che ad un certo punto viene modificato esternamente e del quale dobbiamo avvisare un'altra parte della nostra app, p.es. per aggiornare alcuni conteggi, tramite una notifica.
Questo sembra essere un compito perfetto per un accessor personalizzato, evitando l'inserimento di un observer dell'oggetto su una proprietà di se stesso:
- (void)setOrdine:(NSNumber *)ordine
{
    [self willChangeValueForKey:@"ordine";
    _ordine = ordine;
    [self didChangeValueForKey:@"ordine"];
    [[NSNotificationCenter defaultCenter] postNotificationName:@"myNotification" object:nil];
}
Ogni volta che il valore di ordine viene modificato, la notifica viene spedita; il tutto senza observer.
Se però eliminiamo l'oggetto dal NSManagedObjectContext (l'interfaccia si aggiorna di conseguenza) e in seguito chiamiamo la voce di Undo del menu Edit, Core Data si premura di rifar comparire l'oggetto stesso, ma l'interfaccia non cambia! Dobbiamo esplicitamente fare azioni per aggiornare lo stato dei conteggi, quali p.es. forzare il ridisegno, tramite una chiamata... che però non sappiamo dove fare (l'Undo non mi avvisa di aver fatto qualcosa e la fa in modo asincrono).

Allora occorre cambiare strategia: introduciamo un observer sulla property e dovremo inserirlo sia in -awakeFromInsert che in -awakeFromFetch. Questi infatti sono i metodi chiamati rispettivamente alla creazione di un NSManagedObject e al suo recupero dallo store:

- (void)awakeFromInsert
{
    [super awakeFromInsert];
    [self setPrimitiveValue:... forKey:@"..."];
    [self addObserver:self forKeyPath:@"posizione" options:0 content:nil];
}

- (void)awakeFromFetch
{
    [super awakeFromFetch];
    [self addObserver:self forKeyPath:@"posizione" options:0 content:nil];
}

- (void)didTurnIntoFault
{
    [self removeObserver:self forKeyPath:@"posizione"];
}

- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context
{
    if ( [keyPath isEqualToString:@"posizione"] ) {
        [[NSNotificationCenter defaultCenter] postNotificationName:@"myNotification" object:nil];
    }
}

Notiamo che abbiamo dovuto togliere l'observer nel metodo -didTurnIntoFault: Apple infatti ci dice che è questo il metodo da usare con i NSManagedObject e che non dobbiamo lasciare in giro degli observer quando l'oggetto non c'è più, poiché potrebbero persino essere attaccati ad altri oggetti. In questo modo, ogni oggetto, che sia creato ex-novo o che sia caricato da disco, avrà un observer sulla property posizione e quando viene cancellato, l'observer viene tolto.
Bene: lanciamo, osserviamo che la notifica viene effettivamente spedita quando la property cambia; proviamo a cancellare l'oggetto: ok. Facciamo un Undo: voilà! L'aggiornamento non sembra funzionare più! Peggio: cancelliamo nuovamente l'oggetto (senza utilizzare il Redo) ed otteniamo una bellissima exception: "ho cercato di togliere un observer ma questo non c'era"!!!

Siamo arrivati al punto del problema: quando abbiamo cancellato l'oggetto la prima volta, è stato chiamato -didTurnIntoFault, che ha giustamente tolto l'observer. Quando però abbiamo fatto l'Undo, il nostro ManagedObject è stato riportato in vita ...artificialmente! Cioè, senza passare dall'-awakeFromFetch! Quindi non ha avuto occasione di rimettere a posto l'observer sulla property e questo spiega perché i conteggi non vengano eseguiti; quando poi cancelliamo di nuovo l'oggetto, il -didTurnIntoFault viene nuovamente chiamato, ma l'observer non esiste ed il codice si lamenta giustamente!
In modo un po' empirico, potremmo pensare di eliminare il -didTurnIntoFault, ma dopo aver cancellato un oggetto, all'uscita dell'applicazione otterremo un alto lamento del codice, che ci dice che abbiamo lasciato un observer vagante e che ciò non è cosa da farsi! Siamo in una strada senza uscita: se lo togliamo si arrabbia, se non lo togliamo si arrabbia lo stesso!

Intanto, dobbiamo capire il perché succeda una cosa simile; dopo averci ragionato un po', eccoci al punto! Quando un oggetto viene cancellato, è in effetti tolto dalla vista, ma viene messo nella coda di Undo e non viene distrutto; quando l'Undo viene chiamato, non fa altro che rimettere l'oggetto al suo posto, senza passare da nessuno dei metodi precedenti. Quindi è corretto non togliere l'observer alla cancellazione: l'oggetto non è cancellato, ma solo messo da parte. Quando l'Undo lo ripresenta, l'oggetto è pronto per continuare a funzionare.
Ma allora dove possiamo togliere l'observer? Quando l'oggetto verrà definitivamente distrutto e anche l'Undo non lo manterrà più! Ok, ma in pratica, dove??? Proprio nel metodo sconsigliato da Apple per i ManagedObject:
- (void)dealloc
{
    [self removeObserver:self forKeyPath:@"posizione"];
}
Lo so, lo so: Apple dice di non usare questo metodo con i ManagedObject, perché probabilmente non verrebbe mai chiamato. Ma questo è proprio uno dei casi in cui è certamente chiamato: noi andiamo a togliere l'observer proprio quando l'oggetto sta per essere distrutto e non quando viene solo tolto dalla vista, con possibilità di essere reinserito.

In questo modo non lasciamo observer vaganti, non cerchiamo di toglierli quando non ci sono e, soprattutto, le notifiche verranno lanciate ogni volta che la property dell'oggetto cambia, proprio come volevamo.

2014-06-12

NSOutlineView, NSTreeController e la gestione della memoria

Quando vogliamo costruire una NSOutlineView cell-based tramite un NSTreeController, anche se le cose non sono così chiare, sappiamo bene cosa fare! Oltre ad implementare il protocollo del delegate dell'Outline, dobbiamo anche usare la classe di convenienza NSTreeNode, che in pratica rappresentano i nodi; questi oggetti, anche se decidiamo di dimenticarli, vengono comunque creati.
Allora, visto che ci sono, tanto vale usarli; spesso è utile farne una sottoclasse per aggiungere variabili a noi interessanti (p.es. per legarli via binding alla cella).

La parte importante è il representedObject, che utilizziamo per riporvi l'oggetto che verrà rappresentato dal nodo. Giusto per non lasciare le cose troppo astratte, ogni nodo viene creato con il suo representedObject e poi aggiunto al NSTreeController. Per la radice dell'OutlineView (indexPath=0); il representedObject è un NSDictionary con le grandezze che ci servono:

NSDictionary *theRootObject = @{kOutlineTitle: kRootTitle, kOutlineCode: @(kCodeHeader)};
ISNode *radice = [ISNode treeNodeWithRepresentedObject:theRootObject];
[self.listController insertObject:radice atArrangedObjectIndexPath:[NSIndexPath indexPathWithIndex:0]];

dove ISNode è la nostra sottoclasse di NSTreeNode e listController è il NSTreeController. Mentre per un qualunque altro nodo, l'unica differenza è l'IndexPath, che ovviamente avrà un indice in più (cioè saranno tutti figli del nodo radice).
Fin qui tutto a posto. Ma supponiamo di cancellare un oggetto mostrato nell'OutlineView... La prima cosa che ci viene in mente è di trovare l'indexPath dell'oggetto e poi usare i metodi del TreeController:

[self.listController removeObjectAtArrangedObjectIndexPath:path];

e in effetti abbiamo ragione! Il problema è che se proviamo ad aggiungere e togliere oggetti, dopo poco ci troveremo un numero interessante di NSTreeNode vaganti per la RAM, che non se ne vogliono andare! Possiamo vederlo facilmente tramite Instruments!

Non mi sono dato la pena di andare a fondo e scoprire il perché: infatti, una volta che un oggetto viene eliminato da un Controller dovrebbe essere libero e quindi deallocato da ARC alla prima occasione. La mia opinione, non dimostrata, è che in qualche modo sia colpa del representedObject (anche se in realtà dovrebbe essere il TreeNode che trattiene il representedObject e non viceversa). Se qualcuno ha un'idea al proposito... si faccia avanti!

In ogni caso, la soluzione è stata semplice: prima di togliere l'oggetto dal TreeController, mi sono registrato il TreeNode che stava per essere eliminato e, subito dopo il metodo -removeObjectAtArrangedObjectIndexPath, non ho fatto altro che imporlo a nil.

ISNode *selezione = [self.listController selectedObjects][0];
[self.listController removeObjectAtArrangedObjectIndexPath:path];
selezione = nil;

Così facendo, Instrument mostra che tutti i TreeNode eliminati scompaiono dalla RAM.

2014-03-24

Creazione e utilizzo dei file package

Può capitare che nella nostra applicazione, che sia basata su NSDocument o meno, ci sia la necessità di registrare dati in file separati, nascondendoli alla vista del normale utente, in modo che nessuno possa modificarli indipendentemente dall'applicazione.
Per questa funzionalità esistono i package! Nel Finder compaiono come normali singoli file, che possono essere copiati, spostati e cancellati normalmente. In realtà sono cartelle, che il Finder presenta come file perché sa che così deve essere! Esempi? Tutta la suite di iWork salva in questo modo. Selezionando uno di questi file, il tasto destro mostra la voce "mostra contenuto pacchetto".

Per prima cosa, il documento deve essere previsto nel progetto Xcode: se la nostra app è document-based non c'è bisogno di fare nulla, ma se non lo è dobbiamo cliccare sull'icona del progetto e scegliere il tab Info: ci viene mostrata la rappresentazione semplificata del file info.plist della nostra applicazione. Subito sotto, clicchiamo su Document Types e aggiungiamo un documento: è necessario inserire almeno il nome (di nostra scelta) e l'estensione (anche qui siamo liberi, ma non deve essere un'estensione già nota al sistema - l'estensione può essere di qualunque lunghezza - di solito è qualcosa che ricorda il nome del nostro software). Dobbiamo poi scegliere come ruolo (role) Editor e mettiamo la spunta su 'Document is distributed as bundle', che è proprio quello che vogliamo.

Questo è tutto: Xcode porterà nell'Info.plist dell'applicazione questi dati e, dopo averla lanciata la prima volta, le cartelle con questa estensione verranno trattate dal Finder come file singoli. Nella figura sono riportate le impostazioni per la libreria esportata da InerziaThings.

Scrittura

Ora però dobbiamo costruirli. Il tutto viene fatto attraverso l'oggetto NSFileWrapper.
Come esempio, supponiamo di voler inserire in un package alcune immagini e informazioni collegate: l'idea è di scrivere le informazioni in un file plist (già costruito e di nome xmlDoc) e le relative immagini in una cartella, il tutto all'interno del package.
Per prima cosa, trasformiamo il plist in un NSData:

NSData *xmlData = [xmlDoc XMLDataWithOptions:NSXMLNodePrettyPrint];
NSFileWrapper *mainDirectory = [[NSFileWrapper alloc] initDirectoryWithFileWrappers:nil];
[mainDirectory addRegularFileWithContents:xmlData preferredFilename:nomeFile];

Il preferredFileName è proprio il nome con cui comparirà il file plist all'interno del package, a meno che il nome non esista già: ma dato che siamo noi a crearlo, sappiamo cosa ci stiamo mettendo!)
Notiamo che al momento stiamo solo costruendo una struttura in memoria, nulla finora è stato scritto realmente sul disco.
Ora creiamo la cartella che conterrà le immagini con lo stesso metodo di prima, definiamo il nome di questa cartella (imageFolderName) e la aggiungiamo alla struttura del package:

NSFileWrapper *imageDirectory = [[NSFileWrapper alloc] initDirectoryWithFileWrappers:nil];
[imageDirectory setPreferredFilename:imageFolderName];
[mainDirectory addFileWrapper:imageDirectory];

Supponiamo di avere i riferimenti (URL) alle varie immagini in un array imageURLs; creiamo quindi un loop che legga i singoli URL e li aggiunga all'interno della cartella:

for (NSURL *theImage in imageURLs)
{
    NSFileWrapper *wrapImage = [[NSFileWrapper alloc] initWithURL:theImage options:0 error:nil];
  [imageDirectory addFileWrapper:wrapImage];
}

Si è trattato di creare un NSFileWrapper per ogni immagine, partendo dall'URL e aggiungere ognuno di essi al wrapper che rappresenta la cartella.
Ora non ci resta che scrivere effettivamente la struttura su disco e questo viene fatto utilizzando il metodo writeToURL di NSFileWrapper:

NSError *error;
BOOL finito = [mainDirectory writeToURL:exportURL options:0 originalContentsURL:nil error:&error];

dove exportURL rappresenta la locazione sul file system dove andremo a scrivere e sarà stato ottenuto in precedenza tramite un NSSavePanel. È buona norma controllare che non ci siano stati errori, guardando il valore del booleano finito ed eventualmente andando a leggere la descrizione dell'errore contenuta in error.

Lettura

Quando si tratta di leggere un package, dovremo fare lo stesso cammino ma a ritroso: dovremo perciò inizializzare un NSFileWrapper che punti all'URL richiesto (ottenuto da un NSOpenPanel) e chiedere allo stesso oggetto i file wrapper contenuti, tramite il metodo fileWrappers, che fornisce un NSDictionary contenente i riferimenti:

NSError *error;
NSFileWrapper *mainWrapper = [[NSFileWrapper alloc] initWithURL:theURL options:NSFileWrapperReadingImmediate error:&error];
NSDictionary *rootWrappers = [mainWrapper fileWrappers];

Alla fine, dentro rootWrappers avremo i dati necessari per ricostruire la struttura; per prima cosa otteniamo il wrapper della cartella con le immagini, utilizzando come chiave nel NSDictionary quella che avevamo usato durante la sua creazione (cioè il nome) e da questi i wrapper relativi alle immagini; poi da rootWrappers ricaviamo il nome del file plist in cui sono riportati i dati delle immagini:

NSFileWrapper *imagesDir = [rootWrappers objectForKey:imageFolderName];
NSDictionary *allImages = [imagesDir fileWrappers];
NSFileWrapper *imageListWrapper = [rootWrappers objectForKey:nomeFile];
NSData *theData = [imageListWrapper regularFileContents];
NSError *error;
NSXMLDocument *xmlDocument = [[NSXMLDocument alloc] initWithData:theData options:NSXMLDocumentTidyXML error:&error];


//loop sui nodi XML per ottenere i dati delle immagini
//poi per ogni immagine, questa viene costruita leggendo il wrapper:
//nomeImmagine: il nome originale; theURL: la posizione in cui salvare l'immagine
    NSFileWrapper *theImageWrapper = [dict objectForKey:nomeImmagine];
    NSData *theImageData = [theImageWrapper regularFileContents];
    [theImageData writeToURL:theURL atomically:NO];

In questo spezzone abbiamo ottenuto l'oggetto NSData utilizzando il metodo regularFileContents, da cui si ricava il documento XML. Da questo si potranno leggere i dati in esso memorizzati ed utilizzarli per ricreare le immagini originali con i loro dati. Infatti, con le ultime tre righe (che sono all'interno di un loop), ricaviamo il wrapper per ogni immagine, da questo otteniamo i dati come oggetto NSData, che verrà scritto su disco nella posizione voluta tramite l'ultima riga.

A questo punto abbiamo ricostruito tutta la struttura ed ottenuto i dati di partenza.

2014-01-01

La NSWindow che non voleva ilFrame...

Quanti di voi, amici sviluppatori, cambiano posizione e dimensioni ad una NSWindow usando il suo bravo metodo

[mainWindow setFrame:presentWindowRect display:YES];

oppure il metodo esteso con l'animazione

[mainWindow setFrame:presentWindowRect display:YES animate:YES];

per esempio per aggiungere in modo elegante una NSView per determinati scopi? Siete in molti? Bene.
E quanti di voi pensano ai propri utenti e salvano in automatico la posizione delle finestre, inserendo un nome a piacere nel campo Autosave di Interface Builder? Sempre molti, direi.
Ancora una domanda: quanti cercano di mantenere la compatibilità con Lion? Suppongo una buona parte.
Ok, ora che abbiamo selezionato l'uditorio, partiamo!

In questi giorni, sto mettendo a punto una nuova versione di InerziaTimer, passando ad una interfaccia più moderna e semplice, magari utilizzando una finestra NSBorderlessWindow costruita ad hoc ed ovviamente sviluppando con SDK 10.9 (ma la compatibilità deve andare indietro fino al 10.6).
Decido di mostrare in ogni momento solo gli elementi necessari alla funzione selezionata: quindi la solita trafila della NSView caricata da uno xib aggiuntivo tramite un NSViewController, con la finestra principale che si allunga per far posto alla nuova vista.
Dato che OS X calcola le coordinate dello schermo partendo dal basso, mentre l’utente si aspetta che la finestra mantenga fissa la parte superiore, bisogna fare un po’ di calcoli; in pratica:

NSRect presentWindowRect = [mainWindow frame]; //frame della NSWindow
NSRect viewRect = [accessoryView frame]; //frame della nuova vista da aggiungere
presentWindowRect.size.height = presentWindowRect.size.height + viewRect.size.height;
presentWindowRect.origin.y = presentWindowRect.origin.y - viewRect.size.height;
[mainWindow setFrame:presentWindowRect display:YES animate:YES];
[[mainWindow contentView] addSubview:accessoryView];

Questo codice funziona già per la finestra delle preferenze, dove ogni pannello ha altezze diverse e la finestra aggiusta la propria in conseguenza.

La prima implementazione aveva un problema: la finestra principale viene caricata all'inizio senza vista, mentre alla chiusura dell’app laNSView era presente. Per cui la posizione salvata all'uscita dall'app era relativa ad una finestra allungata, non a quella senza la NSView aggiuntiva che veniva caricata nella sessione successiva; il risultato era che ad ogni chiusura e riapertura, la finestra principale si posizionava sempre più in basso sullo schermo, fino ad uscirne! Ok, colpa mia (è sempre così); prima di chiudere l’app bisogna togliere la NSView, in modo che venga salvata la posizione della NSWindow da sola. È semplice: nel metodo -applicationShouldTerminate basta togliere la NSView e accorciare la finestra, sempre tenendo conto che l’origine del frame è in basso a sinistra:

NSRect presentWindowRect = [mainWindow frame]; //frame attuale della finestra con vista
CGFloat altezzaVista = [accessoryView frame].size.height;  //altezza della NSView
presentWindowRect.origin.y += altezzaVista;            //spostiamo la NSWindow in su..
presentWindowRect.size.height -= altezzaVista;            //e la accorciamo di conseguenza
[mainWindow setFrame:presentWindowRect display:NO];        //nessun display tanto la stiamo chiudendo

Il risultato è che la parte superiore resta fissa, si accorcia l’altezza e la finestra si presenta pronta per la chiusura.
Bene. Effettuo la modifica e lancio il tutto: perfetto, come aspettavo! Poi, dopo un altro po’ di sviluppo, provo il funzionamento di una nuova caratteristica sul 10.7 e... scopro che ad ogni riavvio la finestra si sposta in alto, fin quasi a scomparire! Penso si tratti di un baco: lo correggo su Lion, torno su Mavericks e.. qui la finestra si sposta ogni volta verso il basso!
Ok, riassumo: se lo correggo per Lion, non va su Mavericks e viceversa! Non potevo credere di dover fare un IF per poter mantenere una finestra allo stesso posto...
Allora ho cominciato a fare delle prove: inserimento di NSLog un po’ dovunque ed ho scoperto che su Lion il mio codice veniva seguito alla lettera ma, prima di presentarla a video, la finestra ritornava alla posizione iniziale, come se il mio codice non fosse mai stato eseguito! Ho provato ad inserire observer un po’ ovunque per catturare il momento in cui veniva rimodificato il frame, ma senza risultato: la finestra andava a posizionarsi dove voleva lei!
Anche San Google non sembrava aiutarmi, finché alla fine non trovo un problema simile sul solito StackOverflow: anche lì la finestra ribelle non voleva onorare il setFrame su Lion.
Il consiglio era di togliere il check alla caratteristica Restorable in Interface Builder; dato che la mia finestra è costruita da codice in una sottoclasse di NSWindow, ho inserito nel codice della sottoclasse:

- (BOOL)isRestorable
{
  return NO;
}

che da Lion in poi rappresenta un override, mentre per il 10.6 Snow Leopard sarà un semplice metodo aggiuntivo non utilizzato.
Compilato e lanciato: perfetto su Lion e perfetto su Mavericks!

Ho poi consultato la documentazione Apple sulla User Interface Preservation. Si tratta del meccanismo secondo il quale le finestre di una app sono riportate, ad una successiva riapertura, nello stato in cui erano alla chiusura, sempre che nelle Preferenze di Sistema l’utente abbia così scelto. Il risultato è stato:
  1. non c’è scritto da nessuna parte che il comportamento sia cambiato in qualche momento tra Lion e Mavericks (non ho provato su Mountain Lion, ma non mi aspetto differenze).
  2. il Restore richiede di definire un oggetto che faccia questo lavoro tramite un completionHandler; non conoscendo questa funzionalità, non avevo fatto nulla per implementarla.
  3. su entrambi i Mac utilizzati, questa funzione era disabilitata.
  4. la documentazione della classe NSWindow afferma che il metodo standard ritorna YES solo se lo styleMask della NSWindow comprende NSTitledWindow, mentre nel mio caso si trattava di una NSBorderlessWindow.
Risultato: ho risolto il problema attuale; ma forse qualcosa mi sfugge ancora nel generale...

2013-12-15

Test della ricevuta e Mavericks

È cosa normale che durante lo sviluppo di una nuova versione si facciano test intermedi sulla ricevuta; dato che la versione deve essere la stessa definita in iTunesConnect, mi succede sempre di fare questi primi test utilizzando la versione presente in quel momento sullo Store (una app non può restare un tempo indefinito nello stato Waiting for upload e all'inizio non si ha ancora una stima precisa di quando si finirà lo sviluppo).
Per cui, si effettua il solito procedimento per scaricare la ricevuta dall'AppStore per l'utente di test, fino ad arrivare a quando siamo molto vicini al rilascio della versione finale.

In quel momento, si entra in iTunesConnect, si crea la nuova versione e la si porta nello stato di attesa dei binary. Poi si modifica la versione in Xcode, si esporta l'eseguibile e si esce dall'utenza normale dell'AppStore.

Bene. Prima dell'avvento di Mavericks, il procedimento andava a buon fine senza problemi: all'avvio dell'app c'era un attimo di attesa, poi compariva la richiesta di utente/password; una volta forniti, la ricevuta era scaricata, l'app veniva riavviata, il check della receipt effettuato e, a scanso di bachi inattesi, alla fine si otteneva all'interno del bundle l'attesa cartella _MASReceipt.
La stessa cosa dovrebbe succedere con Mavericks.

Invece, dopo aver cambiato la versione in Xcode e aggiunta su iTunesConnect, il lancio dell'app esportata terminava con un bel dialogo con cui il Finder mi avvisava che l'app era danneggiata e che non poteva essere lanciata (se non nel cestino...).
Dato che la procedura seguita era la stessa, l'unico modo era di andare in debug e osservare cosa accidenti stava succedendo. Risposta: la versione dell'app era diversa da quella registrata nella receipt! Cioè, la ricevuta riguardava la versione vecchia, mentre l'Info.plist conteneva la nuova!
Ma in iTunesConnect la versione era proprio la nuova!

Il caso ha voluto che il giorno successivo prevedessi di non usare il Mac: invece del solito Stop ho dato il comando Spegni. Quando, due giorni dopo, l'ho riacceso, il problema era scomparso: la ricevuta veniva scaricata e la versione era quella giusta!

Dopo qualche giro sulla rete e dopo aver fatto una prova simile su un'altra app, sono arrivato alla soluzione: senza dire nulla (o per lo meno, io non ho trovato indicazioni), Apple ha aggiunto in Mavericks la possibilità di tenere in cache una ricevuta e di riutilizzarla se la stessa applicazione la richiede (fino a quando questa cache è disponibile). Di solito questa è una cosa buona, poiché si evita di fare una nuova richiesta, una nuova attesa e un nuovo download. In questo caso invece crea questo problema.

La soluzione (oltre al riavvio, ma è esagerato!) è di killare lo StoreAgent:

$ killall -KILL storeagent

e dopo mettere l'app nel cestino e svuotarlo. A questo punto, esportiamo una nuova copia dell'app da Xcode, lanciamola, lo StoreAgent viene rilanciato da zero, forniamo utente test/password e... magicamente tutto torna a posto!

2013-12-07

Firmare app e framework

Una delle novità di Mavericks è che non sia più possibile firmare un'applicazione con il proprio certificato sviluppatore se all'interno si trova un framework non firmato.
Ho scoperto questa "bella" novità quando ho deciso di re-introdurre l'utilizzo dell'utilissimo Sparkle per l'aggiornamento automatico delle applicazioni, per rilasci fuori Mac App Store. Giusto per completezza, la stessa situazione si trova comunque ogni volta che utilizziamo un framework esterno o mini-applicazioni per estendere le funzionalità della nostra app.
A pensarci, è anche giusto che sia stata introdotta questa sicurezza aggiuntiva: in effetti un framework potrebbe effettuare azioni potenzialmente dannose e nascondersi dentro alla nostra app; tuttavia, avrei preferito un bel banner che avvisasse di questo problema, prima di sbatterci il naso per un po' di tempo...

Il sintomo del problema compare quando tentiamo di compilare con il nostro bravo framework importato; il passaggio della firma fornisce un errore del genere:

codesign build/release.../myApp.app: code object is not signed at all
in subcomponent build/release..../Sparkle.framework 
codesign failed with exit code 1

La parte "in subcomponent" ci indica anche quale framework (o app) è responsabile della mancata firma.
Il suggerimento di alcuni siti di inserire il comando --deep non risolve: purtroppo questa opzione provoca sì la firma di tutti i bundle ai vari livelli, ma applicando le stesse proprietà richieste dall'app principale. Il risultato è che il procedimento di firma va a buon fine, ma quando un utente lancia la nostra applicazione, il Finder gli mostra un bel messaggio che lo invita a cestinarla, perché danneggiata. Il problema viene mostrato anche tramite il comando da Terminale spctl:

spctl --verbose=4 --assess myApp.app 
myApp.app: a sealed resource is missing or invalid

La soluzione, tutto sommato, è abbastanza semplice (una volta che la si conosce): basta infatti firmare, con lo stesso certificato dell'App, anche il framework, dopo che questo è stato copiato durante i passaggi della compilazione.
Per far questo, si seleziona il progetto e si va nella pagina delle Build Phases, dove avremo già aggiunto in precedenza una Copy Phase, per fare in modo che il framework sia copiato nel bundle dell'applicazione (precisamente, nella cartella Framework, che verrà quindi creata se non esiste). Dal menu Editor, scegliere Add Build Phase → Add Run Script Build Phase; lasciando la shell di default, scriviamo nel riquadro dedicato il seguente script (riferendosi al framework Sparkle):

LOCATION="${BUILT_PRODUCTS_DIR}"/"${FRAMEWORKS_FOLDER_PATH}" 
IDENTITY="Mac Developer: abcdef ghijk" 
codesign --verbose --force --sign "$IDENTITY" "$LOCATION/Sparkle.framework/Versions/A"

dove nella variabile IDENTITY andiamo ad inserire il nome del certificato da utilizzare (che dovrà essere lo stesso utilizzato per l'applicazione, altrimenti l'app verrà vista come danneggiata).
A questo punto il problema è risolto! Da notare che se avessimo altri framework o applicazioni da inserire nel bundle, avremo script aggiuntivi, uno per ciascuno di essi, da eseguire dopo la copia nel percorso adatto.

Per comodità, aggiungo a questo post anche i comandi shell per il controllo della firma.
Per verificare che tutto è a posto:

codesign --verify --verbose=4 myApp.app

Per essere sicuri che Gatekeeper accetti la nostra app (fuori dal Mac App Store):

spctl --verbose=4 --assess --type execute myApp.app

Per esaminare i requirement di una app:

codesign --display --requirements - myApp.app

2013-08-15

Il 'locale' personalizzato

Mac OS X (e ovviamente iOS) ha un'ottima gestione della internazionalizzazione delle applicazioni: basta usare le cartelle magiche per ogni lingua che vogliamo supportare, un paio di macro di compilazione e siamo a posto. Il risultato è un'applicazione che si presenta differente a seconda della lingua scelta nel sistema dall'utente; la documentazione Apple al proposito è sufficientemente chiara: per l'interfaccia usiamo degli xib differenti (ciascuno nella propria cartella della lingua) e per le stringhe nel codice usiamo sempre la macro NSLocalizedString, che andrà a pescare dal file localizableString della lingua giusta.

C'è però una cosa più sottile ed è rappresentata da tutte le varie convenzioni tipiche di ogni lingua; ciò che fa si che la data 5/4/2013 significhi '5 aprile 2013' in Italia, mentre negli Stati Uniti stia per '4 maggio 2013'. Oppure che il le cifre 1,234 indichino un numero appena più grande di 1 in Francia, ma per gli inglesi superi il migliaio.
Per vederle tutte basta aprire Preferenze di Sistema e cliccare su Lingua e Testo e poi scegliere il tab Regione.
Quindi l'utente è abituato (p.es. in Italia) a leggere e scrivere numeri con la virgola per indicare i decimali e così via; quindi la nostra app deve metterlo a suo agio, altrimenti dopo pochi minuti finirà nel cestino, seguita da alcune maledizioni al nostro riguardo...

Per fortuna è molto semplice tenerne conto: di solito è sufficiente impostare nello xib un formatter legato al campo che riceverà il numero e impostare il formatter come ci interessa: in automatico le impostazioni saranno quelle usate nel sistema.

Ci sono però dei momenti in cui è utile conoscere da codice p.es. cosa viene usato come separatore decimale in una certa lingua: nulla di più facile! Per questa operazione ci viene in aiuto l'oggetto NSLocale: basta prima ottenere la lingua impostata sul computer dell'utente usando currentLocale e poi utilizzare l'oggetto così ottenuto per ricavare il carattere usato e molte altre cose. Detto in 'codicese':
NSLocale *myPresentLocale = [NSLocale currentLocale];
//ricaviamo il separatore decimale della lingua dell'utente
NSString *punto = [myPresentLocale objectForKey:NSLocaleDecimalSeparator];
//oppure otteniamo il simbolo di valuta in uso
NSString *valuta = [myPresentLocale objectForKey:NSLocaleCurrencySymbol];
//o per esempio il nome della lingua dell'utente
NSString *lingua = [myPresentLocale objectForKey:NSLocaleIdentifier];
//se vogliamo strafare, questo è il codice della lingua
NSString *codice = [myPresentLocale objectForKey:NSLocaleLanguageCode];
//questa invece è il nome di una lingua... nella lingua dell'utente!
NSString *nome = [myPresentLocale displayNameForKey:NSLocaleIdentifier value:@"fr_FR"];
//se siamo in italiano, il risultato sarà 'Francese'
In questo modo possiamo ottenere tutte le informazioni che ci servono ed utilizzarle per mettere l'utente a proprio agio.
Tuttavia, il nostro caro utente ha molta più libertà che la sola scelta della lingua: p.es. qualcuno potrebbe preferire l'utilizzo del punto decimale al posto della virgola, ma continuare a tenersi il sistema in italiano per avere le date nel formato corretto. Se guardiamo quanto disponibile nelle Preferenze di Sistema, vediamo che l'utente può personalizzare tutto (e non chiediamoci perché dovrebbe farlo: dato che può, qualcuno lo farà certamente!) e questo sarebbe un bel guaio per il povero programmatore. Però... ci viene in aiuto di nuovo il NSLocale: possiamo infatti ottenere un oggetto NSLocale che contiene tutti i valori del locale attuale ma corretti con le eventuali personalizzazioni che il nostro caro utente ha ritenuto opportuno inserire:
NSLocale *actualLocale = [NSLocale autoupdatingCurrentLocale];
NSString *punto = [actualLocale objectForKey:NSLocaleDecimalSeparator];
//se l'utente è un italiano che usa il punto al posto della virgola, otterremo '.'
Da notare che la stessa funzione esiste anche nella Foundation (se dovessimo per qualche motivo lavorare in quel modo); il codice diventerebbe:
CFLocaleRef userLocale = CFLocaleCopyCurrent();
CFTypeRef decimalPoint = CFLocaleGetValue(userLocale, kCFLocaleDecimalSeparator);
//più difficile da leggere, ma con lo stesso risultato!
Quindi, da oggi i nostri utenti saranno felici e contenti di poter usare le loro impostazioni anche nelle nostre app!

2013-07-06

Controllo della receipt Mac App Store

Pur non essendo obbligatorio per pubblicare applicazioni sul Mac App Store (MAS), Apple consiglia di effettuare un controllo sulla ricevuta (receipt) per evitare che tramite una semplice copia da un Mac all'altro la nostra applicazione si trovi ad avere 2 copie vendute e 500 utenti!
Si tratta quindi di una sicurezza aggiuntiva per lo sviluppatore (l'utente è già al sicuro: firma del codice e registro degli acquisti sullo Store permettono di identificare lo sviluppatore - che quindi non inserirà codice cattivo - e di essere sicuri che l'app sul proprio Mac è proprio la stessa rilasciata sul MAS).
Allora, meglio procedere!

Ma come si fa a controllare un documento che esisterà solo sul Mac dell'utente dopo l'acquisto e non su quello dello sviluppatore?

Tempo fa Apple forniva un certificato campione per i test, ma ora la procedura è cambiata: una volta terminato lo sviluppo, si aggiunge il codice di controllo, si lancia l'applicazione, il codice nota l'assenza di ricevuta e ne richiede una apposita al MAS. Una volta ottenuta, la usiamo per testare a fondo il codice di controllo.

Bene, lineare, facile a dirsi... non a farsi!
Dopo vari tentativi, tripla lettura della documentazione ufficiale, ricerche su Google... sono arrivato al procedimento corretto, o per lo meno, quello che funziona! Occorre seguire passo passo le seguenti istruzioni.
  • Per prima cosa, andiamo su iTunes Connect, entriamo con le credenziali di sviluppatore e andiamo nella sezione di gestione degli utenti. Vedremo due grandi pulsanti: uno è per gli utenti normali, l'altro per gli utenti di test; entriamo su quest'ultimo e generiamo un utente di test. La creazione è simile a quella di un utente normale: dovremo fornire una mail apposita (deve essere vera, perchè ci verrà richiesto di validarla) con password e tutti i vari dati. Per sicurezza li ho messi uguali al mio utente standard (a parte la mail, ovviamente!). Naturalmente, questo utente è collegato quello di sviluppatore: in questo modo, saranno disponibili tutte le nostre applicazioni registrate.
  • Mentre siamo su iTunes Connect, registriamo la nostra applicazione come se stessimo per farne l'upload; cioé, il sistema deve avere in pancia il bundleID e la versione dell'app su cui stiamo lavorando. Questo è indispensabile se la nostra app è nuova e non è mai stata registrata; se invece abbiamo già una versione precedente registrata, non c'è bisogno di fare nulla: basta usare per le nostre prove la versione registrata
  • Usciamo da iTunes Connect, apriamo l'applicazione App Store e, dal menu Store, usciamo dal nostro utente; così, quando necessario, il sistema ci chiederà utente e password per accedere. Questo è un punto critico: occorre infatti che Mac OS cerchi di chiamare l'AppStore e si trovi disconnesso: solo così potremo usare l'utente di test.
  • Chiudiamo l'App Store e torniamo a Xcode. Inseriamo una bozza del codice che controllerà la presenza della ricevuta. Come, non serve che sia completo: è sufficiente che controlli la presenza della ricevuta e, in caso manchi, effettui un'uscita immediata con il codice exit(173), come dice la documentazione Apple. Anzi, meglio che si tratti di un codice molto semplice: sarà così più facile evitare gli errori e quindi di dover ripetere la procedura.
  • Apriamo i Build Settings del progetto, cerchiamo la voce Code Signing Identity e impostiamola a Mac Developer. Controlliamo che l'impostazione sia sul target della nostra applicazione e non sul progetto. Questa selezione è un punto critico: se ne scegliamo un'altra, non funzionerà! Notiamo che quando faremo l'upload definitivo su iTunesConnect dovremo riportarla a 3rd Party Developer, altrimenti ci verrà segnalato un errore e l'upload non sarà accettato.
  • Verifichiamo nel Info.plist della nostra applicazione che il BundleID (CFBundleIdentifier) e la versione (CFBundleShortVersionString) siano proprio quelli registrati ufficialmente sull'App Store; se non lo sono, non otterremo alcun risultato.
  • Ora dobbiamo esportare l'applicazione, poiché il tutto funziona solo se l'applicazione è lanciata dal Finder, non da Xcode. Quindi eseguiamo un Archive (menu Product) e verremo portati nella schermata Archive dell'Organizer.
  • Selezioniamo l'archivio e clicchiamo sul pulsante Distribute. Selezioniamo Export As - Application, click Ok.

  • Nella scheda successiva (Code Signing Identity) dobbiamo scegliere la firma indicata con Mac Development (di solito è quella selezionata di default). Dimentichiamoci del triangolino giallo che ci comunica che stiamo sbagliando... e clicchiamo Next. Anche questo è un punto critico: un altro tipo di firma non scatenerebbe l'evento corretto, ma ci ritroveremmo solo con un triste messaggio in Console (App not signed), per di più fuorviante.


  • Ci verrà chiesto dove salvare l'app così esportata e su Xcode abbiamo finito.
  • Ora passiamo al Finder: troviamo la nostra app appena esportata e lanciamola! Se abbiamo fatto tutto correttamente, entro qualche secondo ci comparirà il dialogo standard di accesso all'App Store con richiesta di utente (mail) e password. Inseriamo la coppia, usando le credenziali dell'utente di test. Senza che ce ne accorgiamo, il Finder avrà scaricato una ricevuta, l'avrà inserita nel percorso <miaApp.app/Content/_MAS/> e avrà rilanciato l'applicazione. Questa volta, il codice verificherà che la ricevuta esiste, quindi la nostra app partirà normalmente! Infatti, usciamo dall'app, entriamo dal Finder nel pacchetto e vedremo che nel Content è comparsa la cartella _MAS, contenente la ricevuta!
  • Da Finder, prendiamo questa cartella e mettiamola in salvo da qualche parte (anche se poi potremmo scaricarla quante volte vogliamo).
  • Da Xcode, facciamo una compilazione normale (basta dare un Run oppure Build for Running).
  • Da Finder troviamo l'app appena costruita (è al percorso DerivedData/<nomeApp>/Build/Products/Debug), apriamo il bundle e copiamo dentro Content la cartella _MAS: da ora in poi potremo costruire il nostro codice finale per il controllo della ricevuta e ad ogni Run la ricevuta sarà trovata al suo posto, per cui possiamo inserire tutti i controlli che vogliamo!
Attenzione: se per qualche motivo faremo un Clean del progetto, anche la ricevuta sarà eliminata! Ecco il motivo per cui conviene farne una copia in zona sicura, per riprenderla ogni volta che serve (altrimenti dovremo rifare il processo di esportazione e lancio dal Finder).
Un consiglio: Apple fornisce codice solo per il controllo del GUID del Mac (e conviene utilizzarlo così come è, senza modifiche), ma nulla sugli altri controlli. Non è pigrizia da parte di Apple: il controllo della ricevuta è proprio dove un eventuale pirata va a fare reverse engineering per introdurre del codice che salti i controlli. Se tutte le applicazioni usassero lo stesso codice, trovata una soluzione, sarebbero craccabili tutte le applicazioni con quel codice; per cui è consigliabile che ciascuno trovi la propria soluzione.
Per lo stesso motivo, conviene usare codice di Foundation in C puro e non metodi Objective-C, che si portano nel codice compilato una messe di informazioni in chiaro. Volendo si può procedere a offuscare il codice, in modo che anche un reverse engineering diventi difficile. In ogni caso, un pirata motivato e con tempo a disposizione prima o poi riuscirà nel proprio intento...

Informazioni: la documentazione Apple si trova a questo link; come esempi, consiglio Roddi, AlanQuatermain e Sazameki. Colgo l'occasione per ringraziarli tutti e tre: lo studio del loro codice mi ha fatto imparare molto!