nsis-plugin-nsadvsplash/README.md

NewAdvSplash NSIS Plugin

Personal modified version

---

Original Description

NewAdvSplash.dll - plug-in that lets you throw up a splash screen in NSIS installers with fading effects (win2k/xp) and transparency. At the same time can play wav-mp3 sound file.

Usage

1) Show splash screen

newadvsplash::show [/NOUNLOAD] Delay FadeIn FadeOut KeyColor [/BANNER] [/PASSIVE] [/NOCANCEL] FileName

Parameters:

• Delay - time (milliseconds) to show image
• FadeIn - time to show the fadein scene
• FadeOut - time to show the fadeout scene
• KeyColor - color used for transparency, could be any RGB value (for ex. R=255 G=100 B=16 -> KeyColor=0xFF6410). Use KeyColor=-1 if there is no transparent color at your image. If KeyColor=-2 and image type is gif, plug-in attempts to extract transparency color value from the file header. For gif images transparency on the static background works even if KeyColor=-1.
• /BANNER - returns control to installer immediately after plug-in activation. Not depends on installer page - parent window NULL.
• /NOCANCEL - disables 'exit on user click' default behaviour.
• /PASSIVE - not forces splash window to foreground.
• FileName - splash image filename (with extension!). Bmp, gif and jpg image types are supported.

Examples:

newadvsplash::show 3000 0 0 -2 "$PLUGINSDIR\catch.gif"

newadvsplash::show /NOUNLOAD 1000 600 400 0xFF6410 /BANNER "$TEMP\spltmp.bmp"

Use /NOUNLOAD with /BANNER key - this case plug-in not waits for the end of 'show' and returns control to installer. If used in .onInit function, /BANNER key requires 'ShowWindow $HWNDPARENT 2' in .onGUIInit

2) Stop splash

newadvsplash::stop [/WAIT | /FADEOUT]

• Without options terminates banner.
• With /WAIT option waits for the end.
• With /FADEOUT option forces banner close with fade out effect ('Delay' -> 0).

3) Play sound

newadvsplash::play /NOUNLOAD [/LOOP] FileName

• FileName - sound filename to play (with extension, wav, mp3 ...).
• Empty Filename string "" stops sound.

Example:

newadvsplash::play /NOUNLOAD /LOOP "$PLUGINSDIR\snd.mp3"
newadvsplash::show 2000 1000 500 -1 "$PLUGINSDIR\iamfat.jpg"

4) Get window handle

newadvsplash::hwnd /NOUNLOAD
Pop $0 ; $0 is window handle now

Compatibility

• Basic - Win95 and later.
• Fadein/fadeout - win2k/winxp.

Credits

• Original code - Justin
• Converted to a plugin DLL by Amir Szekely (kichik)
• Fading and transparency by Nik Medved (brainsucker)
• Gif and jpeg support, /BANNER and /CANCEL, mp3 support - Takhir Bedertdinov

---

⚠️ Differences in the Personal Version

New supported architecture: x64 (amd64-unicode)

The original supported only:

• x86-ansi (Plugins\newadvsplash.dll)
• x86-unicode (Unicode\plugins\newadvsplash.dll)

The personal version adds support for:

• amd64-unicode (x64)

Added Files

• build_plugin.py - Python script to compile the plugin for all architectures
• src/exdll.h - Header for the NSIS extern DLL API
• src/NewAdvSplash.vcxproj - Visual Studio project updated for VS2022 and x64

Removed Files

Pre-compiled DLL files have been removed from the distribution as they are generated by the build:

• Plugins/newadvsplash.dll
• Unicode/plugins/newadvsplash.dll

Build

cd nsAdvsplash
python build_plugin.py

DLLs are copied to dist/{platform}/newadvsplash.dll.

Build Options

python build_plugin.py --config x86-unicode      # Single architecture (x86-ansi|x86-unicode|x64-unicode|all)
python build_plugin.py --vs-version 2026         # Specific VS version (2022|2026|auto)
python build_plugin.py --clean                   # Clean dist/ before build
python build_plugin.py --install-dir "C:\NSIS\Plugins"  # Copy to additional NSIS directory
python build_plugin.py --verbosity minimal       # MSBuild verbosity (quiet|minimal|normal|detailed|diagnostic)

Functional Changes

No functional changes compared to the original. Modifications are limited to the build infrastructure and x64 support.

---

See README_IT.md for the Italian version.