158 lines
3.9 KiB
Markdown
158 lines
3.9 KiB
Markdown
# nsSplashPNG Quick Reference
|
||
|
||
## Basic Syntax
|
||
|
||
```nsis
|
||
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)
|
||
```nsis
|
||
; Splash closes automatically after 3 seconds
|
||
nssplashpng::show 3000 "$TEMP\splash.png"
|
||
```
|
||
|
||
### Manual Close (Requires /NOUNLOAD)
|
||
```nsis
|
||
; Show splash, no auto-close
|
||
nssplashpng::show /NOUNLOAD 0 "$TEMP\splash.png"
|
||
|
||
; ... do work ...
|
||
|
||
; Close manually
|
||
nssplashpng::stop
|
||
```
|
||
|
||
### With Fade Effects (Auto-close)
|
||
```nsis
|
||
; Fade in, wait 3 seconds, fade out
|
||
nssplashpng::show 3000 /FADEIN /FADEOUT "$TEMP\splash.png"
|
||
```
|
||
|
||
### With Fade Effects (Manual close - Requires /NOUNLOAD)
|
||
```nsis
|
||
; 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
|
||
```nsis
|
||
; User cannot click to close, must wait for timer or stop()
|
||
nssplashpng::show /NOUNLOAD 0 /NOCANCEL "$TEMP\splash.png"
|
||
nssplashpng::stop
|
||
```
|
||
|
||
### Custom Fade Speed
|
||
```nsis
|
||
; 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:
|
||
|
||
```nsis
|
||
nssplashpng::show [flags] <timeout> [more_flags] <image_path>
|
||
```
|
||
|
||
**Correct**:
|
||
```nsis
|
||
nssplashpng::show /NOUNLOAD 5000 /FADEIN /FADEOUT "$TEMP\splash.png"
|
||
```
|
||
|
||
**Wrong** (image_path must be last):
|
||
```nsis
|
||
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
|
||
|
||
```nsis
|
||
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
|