Simone/nsis-plugin-nssplashpng
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
Files
v1.0.0
nsis-plugin-nssplashpng/README_IT.md
T

8.1 KiB
Raw Permalink Blame History

nsSplashPNG - Plugin NSIS per Splash Screen PNG

Plugin NSIS moderno che visualizza splash screen con supporto completo alla trasparenza alfa tramite WIC (Windows Imaging Component).

Funzionalità

  • Formati Immagine Multipli: PNG, JPEG, BMP, GIF, TIFF, ICO tramite WIC decoder
  • Trasparenza Alfa Completa: Supporto canale alfa per PNG/GIF tramite WIC e layered windows
  • Velocità Fade Configurabile: Velocità fade in/out personalizzabile (1-255 step, durata 30ms-7650ms)
  • Esecuzione Non Bloccante: Lo script continua dopo il fade-in mentre lo splash rimane visibile
  • Timer Auto-Close: Chiusura automatica configurabile dopo un numero specificato di millisecondi
  • Click per Chiudere: Interazione utente opzionale per chiudere lo splash
  • No Cancel: Impedisce all'utente di chiudere lo splash durante operazioni critiche
  • Controllo Manuale: Show/stop programmabile con effetti fade
  • Supporto Multi-Monitor: Centra lo splash sul monitor primario, corrente (mouse), per indice, o il più vicino a una coordinata
  • Zero Warning: Compilazione pulita con Visual Studio 2022

Installazione

  1. Copia nssplashpng.dll nella cartella dei plugin NSIS:

    • x86-unicode: Per build NSIS Unicode a 32-bit
    • x64-unicode: Per build NSIS Unicode a 64-bit
    • x86-ansi: Per build NSIS ANSI a 32-bit

  2. Includi la cartella del plugin nello script:

    !addplugindir "path\to\plugins\x86-unicode"

Compilazione dai Sorgenti

Prerequisiti

  • Visual Studio 2022 o successivo con strumenti C++
  • Python 3.x

Passaggi

cd nsSplashPNG
python build_plugin.py                            # Compila tutte le architetture
python build_plugin.py --config x86-unicode       # Solo un'architettura (x86-ansi|x86-unicode|x64-unicode|all)
python build_plugin.py --vs-version 2026          # Versione VS specifica (2022|2026|auto)
python build_plugin.py --clean                    # Pulizia dist/ prima della build
python build_plugin.py --install-dir "C:\NSIS\Plugins"  # Copia in directory NSIS aggiuntiva
python build_plugin.py --verbosity minimal        # Verbosita MSBuild (quiet|minimal|normal|detailed|diagnostic)

Lo script:

  • Compila per x86-unicode, x64-unicode e x86-ansi
  • Copia le DLL in dist/{x86-unicode|amd64-unicode|x86-ansi}/
  • Pulisce i file intermedi dalla cartella src/Build/
  • Supporta build parallele con ottimizzazione automatica CPU

Utilizzo

Importante: Gestione Memoria del Plugin

CRITICO: Usare sempre il flag /NOUNLOAD alla prima chiamata a show per mantenere il plugin caricato in memoria. Senza questo, NSIS scarica il plugin dopo ogni chiamata, perdendo tutto lo stato (handle finestra, thread, ecc.), causando il fallimento di stop.

; Corretto - mantiene il plugin caricato
nssplashpng::show /NOUNLOAD 5000 /FADEIN /FADEOUT "$TEMP\splash.png"
nssplashpng::stop /FADEOUT

; Sbagliato - plugin scaricato dopo show, stop fallirà
nssplashpng::show 5000 /FADEIN /FADEOUT "$TEMP\splash.png"
nssplashpng::stop /FADEOUT

Sintassi

nsSplashPNG::show [/NOUNLOAD] <millisecondi> [/FADEIN [step]] [/FADEOUT [step]] [/NOCANCEL] [/MONITOR <target>] <percorso_immagine>
nsSplashPNG::stop [/FADEOUT [step]]

Nota: Il timeout deve essere specificato subito dopo /NOUNLOAD (se presente), seguito da flag opzionali, con il percorso immagine come ultimo parametro.

Parametri

Funzione show

  • /NOUNLOAD - Richiesto perché stop() funzioni: Mantiene il plugin in memoria tra le chiamate
  • /FADEIN [step] - Abilita effetto fade in. Step opzionale (1-255) controlla la velocità (default: 15)
    • Step più alto = fade più veloce (255=istantaneo, 51=veloce, 15=normale, 5=lento)
    • Formula durata: (255 / step) × 30ms
  • /FADEOUT [step] - Abilita effetto fade out alla chiusura automatica tramite timer (step opzionale)
  • /NOCANCEL - Disabilita click per chiudere (lo splash può essere chiuso solo programmaticamente o dal timer)
  • /MONITOR <target> - Seleziona il monitor su cui centrare lo splash (default: monitor primario)
    • PRIMARY - Monitor primario (default)
    • CURRENT o MOUSE - Monitor dove si trova il cursore del mouse
    • 1, 2, 3, ... - Monitor per indice 1-based (ordine di enumerazione)
    • POINT x y - Monitor più vicino alle coordinate schermo fornite
  • <millisecondi> - Timer auto-close in millisecondi (0 = solo chiusura manuale)
  • <percorso_immagine> - Percorso al file immagine (PNG, JPEG, BMP, GIF, TIFF, ICO)

Funzione stop

  • /FADEOUT [step] - Abilita effetto fade out alla chiusura. Step opzionale (1-255) controlla la velocità (default: 15)

Esempi

Utilizzo Base

; Mostra splash per 3 secondi (PNG con alfa) - /NOUNLOAD non necessario per solo auto-close
nsSplashPNG::show 3000 "$EXEDIR\splash.png"

; Mostra splash JPEG (opaco, senza trasparenza)
nsSplashPNG::show 3000 "$EXEDIR\splash.jpg"

Effetti Fade

; Velocità fade default (step 15, ~510ms)
nsSplashPNG::show 3000 /FADEIN /FADEOUT "$EXEDIR\splash.png"

; Fade veloce (step 51, ~150ms)
nsSplashPNG::show 3000 /FADEIN 51 /FADEOUT 51 "$EXEDIR\splash.png"

; Fade lento (step 5, ~1530ms)
nsSplashPNG::show 5000 /FADEIN 5 /FADEOUT 5 "$EXEDIR\splash.png"

Controllo Manuale

; CRITICO: Usare /NOUNLOAD quando si usa stop() per chiudere manualmente
nsSplashPNG::show /NOUNLOAD 0 /NOCANCEL "$EXEDIR\splash.png"

; ... operazioni di installazione ...

; Chiudi con fade out
nsSplashPNG::stop /FADEOUT

Dettagli Tecnici

Implementazione

  • Libreria Grafica: WIC (Windows Imaging Component) tramite windowscodecs.lib
  • Formato Immagine: 32bppPBGRA (alfa pre-moltiplicato) per corretta trasparenza
  • Tipo Finestra: Layered window con WS_EX_LAYERED | WS_EX_TOPMOST | WS_EX_TOOLWINDOW
  • Trasparenza: UpdateLayeredWindow con blending alfa per pixel
  • Rendering: Accelerato hardware tramite UpdateLayeredWindow con ULW_ALPHA
  • Animazione: Timer da 30ms per fade fluido (range alfa 0-255)
  • Threading: Thread finestra in background per esecuzione non bloccante

Confronto con nsAdvsplash

Funzionalità nsAdvsplash nsSplashPNG
Supporto Alfa PNG Parziale Completo
Effetti Fade Sì Sì
Metodo Trasparenza Color key Alfa per pixel
API Grafica GDI WIC
Tipo Finestra Standard Layered
Click per Chiudere Sì Sì
Warning Compilazione Alcuni Nessuno

Formati Immagine Supportati

WIC rileva e decodifica automaticamente i seguenti formati:

  • PNG - Supporto completo trasparenza alfa
  • JPEG/JPG - Senza trasparenza (opaco)
  • BMP - Trasparenza alfa se a 32-bit, altrimenti opaco
  • GIF - Supporto trasparenza base
  • TIFF - Trasparenza alfa se supportata dalla variante
  • ICO - Formato icona con alfa
  • WMP - Windows Media Photo

Requisiti di Sistema

  • Windows Vista o successivo (per supporto layered window)
  • WIC - Windows Imaging Component (incluso da Windows Vista in poi)

Risoluzione Problemi

Immagine non visibile

  • Verificare che il percorso del file immagine sia corretto e accessibile
  • Controllare che il file sia in un formato supportato
  • Verificare che WIC possa decodificare il file immagine specifico

Nessuna trasparenza

  • Confermare che il PNG abbia canale alfa (non solo RGB)
  • Verificare di usare la DLL plugin corretta per la versione NSIS

Effetti fade non fluidi

  • Comportamento normale - il fade usa timer 30ms con incrementi alfa di 15 step
  • Durata totale fade ≈ 450-500ms

Licenza

Creato per il sistema di installazione NSIS.

Crediti

  • NSIS Plugin API
  • WIC - Windows Imaging Component
  • Windows Layered Windows API (UpdateLayeredWindow)
  • Sistema di build ispirato al plugin nsProcess

Cronologia Versioni

1.0.0 (Corrente)

  • Supporto trasparenza alfa PNG completo tramite WIC
  • Blending alfa per pixel con UpdateLayeredWindow
  • Effetti fade in/out (30ms, 15 step)
  • Timer auto-close con timeout configurabile
  • Click per chiudere con disabilitazione opzionale (/NOCANCEL)
  • Build x86-unicode, x64-unicode e x86-ansi
  • Zero warning di compilazione
  • Sistema di build ottimizzato con compilazione parallela

See README.md for the English version.

Reference in New Issue View Git Blame Copy Permalink