nsis-plugin-nssplashpng/docs/QUICK_REFERENCE.md

nsSplashPNG Quick Reference

Basic Syntax

nsSplashPNG::show [/NOUNLOAD] <timeout> [/FADEIN [step]] [/FADEOUT [step]] [/NOCANCEL] <image_path>
nsSplashPNG::stop [/FADEOUT [step]]

Critical Requirements

⚠️ ALWAYS use /NOUNLOAD when calling stop() manually

Without /NOUNLOAD, the plugin unloads after show() and loses all state, causing stop() to fail.

Common Use Cases

Auto-Close Only (No /NOUNLOAD needed)

; Splash closes automatically after 3 seconds
nssplashpng::show 3000 "$TEMP\splash.png"

Manual Close (Requires /NOUNLOAD)

; Show splash, no auto-close
nssplashpng::show /NOUNLOAD 0 "$TEMP\splash.png"

; ... do work ...

; Close manually
nssplashpng::stop

With Fade Effects (Auto-close)

; Fade in, wait 3 seconds, fade out
nssplashpng::show 3000 /FADEIN /FADEOUT "$TEMP\splash.png"

With Fade Effects (Manual close - Requires /NOUNLOAD)

; Fade in, no auto-close
nssplashpng::show /NOUNLOAD 0 /FADEIN "$TEMP\splash.png"

; ... do work ...

; Fade out when closing
nssplashpng::stop /FADEOUT

Prevent User Closing

; User cannot click to close, must wait for timer or stop()
nssplashpng::show /NOUNLOAD 0 /NOCANCEL "$TEMP\splash.png"
nssplashpng::stop

Custom Fade Speed

; Fast fade (step 51, ~150ms)
nssplashpng::show /NOUNLOAD 0 /FADEIN 51 "$TEMP\splash.png"
nssplashpng::stop /FADEOUT 51

; Slow fade (step 5, ~1530ms)
nssplashpng::show /NOUNLOAD 0 /FADEIN 5 "$TEMP\splash.png"
nssplashpng::stop /FADEOUT 5

; Instant (step 255, ~30ms)
nssplashpng::show /NOUNLOAD 0 /FADEIN 255 "$TEMP\splash.png"
nssplashpng::stop /FADEOUT 255

Fade Speed Reference

Step Value	Duration	Description
1	~7650ms	Very slow
5	~1530ms	Slow
15	~510ms	Default, smooth
51	~150ms	Fast
85	~90ms	Very fast
255	~30ms	Instant

Formula: Duration = (255 / step) × 30ms

Parameter Order

The order matters! Parameters must appear in this sequence:

nssplashpng::show [flags] <timeout> [more_flags] <image_path>

Correct:

nssplashpng::show /NOUNLOAD 5000 /FADEIN /FADEOUT "$TEMP\splash.png"

Wrong (image_path must be last):

nssplashpng::show /FADEIN "$TEMP\splash.png" 5000 /FADEOUT

Supported Image Formats

• PNG - Full alpha transparency ✅
• JPEG/JPG - Opaque (no transparency)
• BMP - Alpha if 32-bit, otherwise opaque
• GIF - Basic transparency support
• TIFF - Alpha if supported by variant
• ICO - Icon format with alpha
• WMP - Windows Media Photo

Troubleshooting

Problem: stop() doesn't close the splash

Solution: Add /NOUNLOAD to the show() call

Problem: Splash closes too quickly/slowly

Solution: Adjust the step parameter:

• Faster: Increase step value (e.g., 51, 85, 255)
• Slower: Decrease step value (e.g., 5, 3, 1)

Problem: User can close splash during installation

Solution: Add /NOCANCEL flag

Problem: Script waits at show() forever

Solution: Either:

• Use a timeout value > 0 for auto-close, OR
• Use timeout = 0 and call stop() manually (requires /NOUNLOAD)

Non-Blocking Behavior

The show() function returns control to your script after the fade-in completes, allowing you to:

1. Show the splash
2. Continue executing your script
3. Close the splash when ready

nssplashpng::show /NOUNLOAD 0 /FADEIN "$TEMP\splash.png"
; Control returns here after fade-in
DetailPrint "Installing..."
; Splash is still visible while we work
Sleep 2000
nssplashpng::stop /FADEOUT
; Control returns here after fade-out

Examples

See the examples/ directory for complete working examples:

• example_basic.nsi - Simple usage patterns
• example_advanced.nsi - Real installer with progress
• example_formats.nsi - Multi-format demonstrations
• example_fade_speed.nsi - All fade speed options
• example_nonblocking.nsi - Non-blocking execution pattern