SplashImage
Creates or updates a window containing an image.
SplashImage ImageFile, Options, SubText, MainText, WinTitle, FontName SplashImage, Off
Command Example: SplashImage "C:\My Pictures\Company Logo.gif"
Function Example: SplashImage("C:\My Pictures\Company Logo.gif")
Parameters
- ImageFile
If this is the word OFF, the window is destroyed. If this is the word SHOW, the window is shown if it is currently hidden.
Otherwise, this is the file name of the BMP, GIF, or JPG image to display (to display other file formats such as PNG, TIF, and ICO, consider using the Gui command to create a window containing a picture control).
[AHK_L 59+]: Any image format supported by Gui may be used with SplashImage.
ImageFile is assumed to be in %A_WorkingDir% if an absolute path isn't specified. If ImageFile and Options are blank and the window already exists, its image will be unchanged but its text will be updated to reflect any new strings provided in SubText, MainText, and WinTitle.
For newly created windows, if ImageFile is blank or there is a problem loading the image, the window will be displayed without the picture.
- Options
A string of zero or more options from the list further below.
- SubText
The text to display below the image or bar indicator. Although word-wrapping will occur, to begin a new line explicitly, use linefeed (`n). To set an existing window's text to be blank, specify %A_Space%. For the purpose of auto-calculating the window's height, blank lines can be reserved in a way similar to MainText below.
- MainText
The text to display above the image or bar indicator (its font is semi-bold). Although word-wrapping will occur, to begin a new line explicitly, use linefeed (`n).
If blank or omitted, no space will be reserved in the window for MainText. To reserve space for single line to be added later, or to set an existing window's text to be blank, specify %A_Space%. To reserve extra lines beyond the first, append one or more linefeeds (`n).
Once the height of MainText's control area has been set, it cannot be changed without recreating the window.
- WinTitle
The title of the window. If omitted and the window is being newly created, the title defaults to the name of the script (without path). If the B (borderless) option has been specified, there will be no visible title bar but the window can still be referred to by this title in commands such as WinMove.
- FontName
The name of the font to use for both MainText and SubText. The font table lists the fonts included with the various versions of Windows. If unspecified or if the font cannot be found, the system's default GUI font will be used.
See the options section below for how to change the size, weight, and color of the font.
Window Size, Position, and Behavior
A: The window will not be always-on-top.
B: Borderless: The window will have no border and no title bar. To have a border but no title bar, use B1 for a thin border or B2 for a dialog style border.
M: The window will be movable by the user (except if borderless). To additionally make the window resizable (by means of dragging its borders), specify M1. To additionally include a system menu and a set of minimize/maximize/close buttons in the title bar, specify M2.
T: The window will be given a button in the task bar and it will be unowned. Normally, there is no button because the window is owned by the script's main window. This setting also prevents a GUI window's Gui +OwnDialogs setting from taking ownership of a Splash window.
Hn: Specify for n the height of the window's client area (which is the area not including title bar and borders). If unspecified, the height will be calculated automatically based on the height of the image/bar and text in the window.
Wn: Specify for n the width of the window's client area. If unspecified, the width will be calculated automatically for SplashImage if there is an image. Otherwise, it will default to 300.
Xn: Specify for n the x-coordinate of the window's upper left corner. If unspecified, the window will be horizontally centered on the screen.
Yn: Specify for n the y-coordinate of the window's upper left corner. If unspecified, the window will be vertically centered on the screen.
Hide: The window will be initially hidden. Use SplashImage Show to show it later.
Layout of Objects in the Window
Cxy: Centered: If this option is absent, both SubText and MainText will be centered inside the window. Specify 0 for x to make SubText left-justified. Specify a 1 to keep it centered. The same is true for y except that it applies to MainText (y can be omitted). For example: c10.
ZHn: Height of object: Specify for n the height to which to scale image. Specify -1 to make the height proportional to the width specified in ZWn (i.e. "keep aspect ratio"). If unspecified, the actual image height will be used. In either case, a value of 0 can be specified to omit the object entirely, which allows the window to be used to display only text in custom fonts, sizes, and colors.
ZWn: Width of object: Specify for n the width to which to scale the image. Specify -1 to make the width proportional to the height specified in ZHn (i.e. "keep aspect ratio"). If unspecified, the actual image width will be used.
ZXn: Specify for n the amount of margin space to leave on the left/right sides of the window. The default is 0.
ZYn: Specify for n the amount of vertical blank space to leave at the top and bottom of the window and between each control. The default is 0.
Font Size and Weight
FMn: Specify for n the font size for MainText. Default 0, which causes 10 to be used on most systems. This default is not affected by the system's selected font size in Control Panel > Display settings.
FSn: Specify for n the font size for SubText. Default 0, which causes 8 to be used on most systems.
WMn: Specify for n the font weight of MainText. The weight should be between 1 and 1000. If unspecified, 600 (semi-bold) will be used.
WSn: Specify for n the font weight of SubText. The weight should be between 1 and 1000 (700 is traditionally considered to be "bold"). If unspecified, 400 (normal) will be used.
Object Colors
A color can be one of the names from the list below or a 6-digit hexadecimal RGB value. For example, specifying cw1A00FF would set a window background color with red component 1A, green component 00, and blue component FF.
Add a space after each color option if there are any more options that follow it. For example: cbRed ct900000 cwBlue.
CTn: Color of text: Specify for n one of the 16 primary HTML color names or a 6-digit RGB color value. If unspecified, the system's default text color (usually black) will be used. Specify the word Default to return to the system's default text color.
CWn: Color of window (background): Specify for n one of the 16 primary HTML color names or a 6-digit RGB color value. If unspecified, the system's color for the face of buttons will be used (specify the word Default to later return to this color). To make the background transparent, use WinSetTransColor.
Remarks
If the first parameter is the word OFF, the window is destroyed.
Each script can display up to 10 SplashImage windows. Each window has a number assigned to it at the time it is created. If unspecified, that number is 1 (the first). Otherwise, precede the first parameter with the number of the window followed by a colon. For example, the SplashImage command with 2:Off would turn off the number-2 SplashImage window, 2: would change one or more of its text fields, and 2:C:\My Images\Picture1.jpg would create a new number-2 SplashImage window.
Upon creation, a window that would be larger than the desktop is automatically shrunk to fit.
A naked image can be displayed the same way except that only the B option is needed.
Use decimal (not hexadecimal) numbers for option letters that need them, except where noted.
Commands such as WinSetAlwaysOnTop and WinMove can be used to change the attributes of an existing window without having to recreate it.
A GUI window may take ownership of a Splash window by means of Gui +OwnDialogs. This causes the SplashImage to stay always on top of its owner. In addition, the SplashImage is automatically destroyed when its GUI window is destroyed.
Related
GUI, Progress, SplashTextOn, ToolTip
Examples
; Create a simple SplashImage window:
SplashImage, C:\My Pictures\Company Logo.gif
; Create a borderless SplashImage window with some large text beneath the image:
SplashImage, C:\My Pictures\Company Logo.gif, b fs18, This is our company logo.
Sleep, 4000
SplashImage, Off
; Here is a working example that demonstrates how a Progress window can be
; overlayed on a SplashImage to make a professional looking Installer screen:
IfExist, C:\WINDOWS\system32\ntimage.gif, SplashImage, %A_WinDir%\system32\ntimage.gif, A,,, Installation
Loop, %A_WinDir%\system32\*.*
{
Progress, %a_index%, %a_loopfilename%, Installing..., Draft Installation
Sleep, 50
if a_index = 100
break
}
; There is similar example at the bottom of the GUI page. Its advantage is that it uses only a single
; window and it gives you more control over window layout.