[Function] SplashText

Post your working scripts, libraries and tools
iPhilip
Posts: 293
Joined: 02 Oct 2013, 12:21

[Function] SplashText

08 May 2018, 17:43

Hi folks,

I would like to share with you a function that I use to splash text on the screen. The function SplashText uses an unnamed/unnumbered GUI window to show a text control. The goal was to create a simple but customizable function to replace SplashTextOn/SplashTextOff, especially given that those commands are no longer available in AutoHotkey v2 [link].

Here is the function:

Code: Select all

; ===============================================================================================================================
; SplashText(ByRef Text:="", ByRef Title:="", Options:="")
; Function:       Creates a customizable GUI window with text in it. Use SplashText() to destroy the window. Calling the
;                 function with any text while a SplashText window is being displayed, destroys the previous window and creates a
;                 new one. The window is "always on top", meaning that it stays above all other normal windows. To change this,
;                 use WinSet, AlwaysOnTop, Off, <insert title of splash window>. The window and the text in it can be customized
;                 through the Options parameter (see below). The current thread's default GUI window name or number is not
;                 changed.
; Parameters:     Text    - (Optional) The text to be displayed in the window. If omitted, the GUI window will be destroyed.
;                 Title   - (Optional) The title of the GUI window. If omitted, the file name of the script will be used.
;                 Options - (Optional) An associative array with any of the following keys:
;                    Font - font options separated by spaces (https://autohotkey.com/docs/commands/Gui.htm#Font)
;                    FontName - the name of the font (https://autohotkey.com/docs/misc/FontsStandard.htm)
;                    BackColor - the background color of the window (https://autohotkey.com/docs/commands/Gui.htm#Color)
;                    Text - text options separated by spaces (https://autohotkey.com/docs/commands/Gui.htm#OtherOptions)
;                    Show - Gui, Show options separated by spaces (https://autohotkey.com/docs/commands/Gui.htm#Show)
;                    Note: If any of the keys are omitted, the value associated with that same key in the static array
;                          DefaultOptions will be used. If Options is omitted, the function generates a window similar to the
;                          window created using the SplashTextOn command.
; Return values:  Handle of the GUI window if one was created.
;                 Blank if the GUI window was destroyed.
; Global vars:    None
; Depenencies:    None
; Tested with:    AHK 1.1.28.00 (A32/U32/U64)
; Tested on:      Win 7 (x64)
; Written by:     iPhilip
; ===============================================================================================================================

SplashText(ByRef Text:="", ByRef Title:="", Options:="")
{
   static GuiHwnd
        , DefaultOptions := {Font:"s11", FontName:"Segoe UI", Text:"Center"}
   
   if Text
   {
      if WinExist("ahk_id " GuiHwnd)  ; If a SplashText window already exists, close it before creating a new one.
         WinClose
      DefaultGui := A_DefaultGui  ; Remember the current thread's default GUI window name or number.
      Options := IsObject(Options) ? Options : {}
      Gui, New, +AlwaysOnTop +Owner -SysMenu +HwndGuiHwnd, % Title
      Gui, Font, % Options.Font     ? Options.Font     : DefaultOptions.Font
               , % Options.FontName ? Options.FontName : DefaultOptions.FontName
      Gui, Color, % Options.BackColor ? Options.BackColor : DefaultOptions.BackColor
      Gui, Add, Text, % Options.Text ? Options.Text : DefaultOptions.Text, % Text
      Gui, Show, % Options.Show ? Options.Show : DefaultOptions.Show
      Gui, %DefaultGui%:Default  ; Restore the current thread's default GUI window name or number.
      Return GuiHwnd
   }
   else if GuiHwnd
   {
      Gui, %GuiHwnd%:Destroy
      GuiHwnd := ""
   }
}
Here is a self-contained example:

Code: Select all

;
; Simple example
;
Text := "Hello world!`nHow are you?"
MsgBox,
(
First, let's create a simple window using the SplashText function.
The window will automatically close after 3 seconds.

Click OK to continue.
)
SplashText(Text)
Sleep, 3000
SplashText()
;
; Comparison of SplashTextOn and SplashText
;
MsgBox,
(
Now, let's compare two windows: one generated using the SplashTextOn command and another one generated using the SplashText function.

Click OK to continue.
)
y := A_ScreenHeight//2 - 275
SplashTextOn, 140, 70, SplashTextOn, % Text
WinMove, SplashTextOn, , A_ScreenWidth//2 - 152, y
SplashText(Text, "SplashText()", {Show:"x" (A_ScreenWidth//2 + 6) " y" y})
MsgBox,
(
Note the two windows above.
The one on the left was generated using the SplashTextOn command.
The one on the right was generated using the SplashText function.
Notice the differences and similarities.

Click OK to continue.
)
SplashTextOff
SplashText()
;
; Countdown timer
;
Seconds := 5
Text := "Hello world!`nThis window will close`nin " Seconds " seconds."
MsgBox,
(
Finally, let's demonstrate the use of GuiControl to modify the text in the SplashText window.

Click OK to continue.
)
GuiHwnd := SplashText(Text)
SetTimer, Timer, 1000
Return

Timer:
if (Seconds = 1)
   ExitApp
Text := StrReplace(Text, Seconds, Seconds-1)
Text := --Seconds = 1 ? StrReplace(Text, "seconds", "second") : Text
GuiControl, %GuiHwnd%:, Static1, % Text
Return

; ===============================================================================================================================
; SplashText(ByRef Text:="", ByRef Title:="", Options:="")
; Function:       Creates a customizable GUI window with text in it. Use SplashText() to destroy the window. Calling the
;                 function with any text while a SplashText window is being displayed, destroys the previous window and creates a
;                 new one. The window is "always on top", meaning that it stays above all other normal windows. To change this,
;                 use WinSet, AlwaysOnTop, Off, <insert title of splash window>. The window and the text in it can be customized
;                 through the Options parameter (see below). The current thread's default GUI window name or number is not
;                 changed.
; Parameters:     Text    - (Optional) The text to be displayed in the window. If omitted, the GUI window will be destroyed.
;                 Title   - (Optional) The title of the GUI window. If omitted, the file name of the script will be used.
;                 Options - (Optional) An associative array with any of the following keys:
;                    Font - font options separated by spaces (https://autohotkey.com/docs/commands/Gui.htm#Font)
;                    FontName - the name of the font (https://autohotkey.com/docs/misc/FontsStandard.htm)
;                    BackColor - the background color of the window (https://autohotkey.com/docs/commands/Gui.htm#Color)
;                    Text - text options separated by spaces (https://autohotkey.com/docs/commands/Gui.htm#OtherOptions)
;                    Show - Gui, Show options separated by spaces (https://autohotkey.com/docs/commands/Gui.htm#Show)
;                    Note: If any of the keys are omitted, the value associated with that same key in the static array
;                          DefaultOptions will be used. If Options is omitted, the function generates a window similar to the
;                          window created using the SplashTextOn command.
; Return values:  Handle of the GUI window if one was created.
;                 Blank if the GUI window was destroyed.
; Global vars:    None
; Depenencies:    None
; Tested with:    AHK 1.1.28.00 (A32/U32/U64)
; Tested on:      Win 7 (x64)
; Written by:     iPhilip
; ===============================================================================================================================

SplashText(ByRef Text:="", ByRef Title:="", Options:="")
{
   static GuiHwnd
        , DefaultOptions := {Font:"s11", FontName:"Segoe UI", Text:"Center"}
   
   if Text
   {
      if WinExist("ahk_id " GuiHwnd)  ; If a SplashText window already exists, close it before creating a new one.
         WinClose
      DefaultGui := A_DefaultGui  ; Remember the current thread's default GUI window name or number.
      Options := IsObject(Options) ? Options : {}
      Gui, New, +AlwaysOnTop +Owner -SysMenu +HwndGuiHwnd, % Title
      Gui, Font, % Options.Font     ? Options.Font     : DefaultOptions.Font
               , % Options.FontName ? Options.FontName : DefaultOptions.FontName
      Gui, Color, % Options.BackColor ? Options.BackColor : DefaultOptions.BackColor
      Gui, Add, Text, % Options.Text ? Options.Text : DefaultOptions.Text, % Text
      Gui, Show, % Options.Show ? Options.Show : DefaultOptions.Show
      Gui, %DefaultGui%:Default  ; Restore the current thread's default GUI window name or number.
      Return GuiHwnd
   }
   else if GuiHwnd
   {
      Gui, %GuiHwnd%:Destroy
      GuiHwnd := ""
   }
}
AHK v2 version
I hope you find it useful.

- iPhilip
Windows 7 Pro (64 bit) - AutoHotkey v1.1+ (Unicode 32-bit)
User avatar
kczx3
Posts: 640
Joined: 06 Oct 2015, 21:39

Re: [Function] SplashText

08 May 2018, 19:27

Why are the first two parameters passed ByRef?
iPhilip
Posts: 293
Joined: 02 Oct 2013, 12:21

Re: [Function] SplashText

08 May 2018, 19:37

kczx3 wrote:Why are the first two parameters passed ByRef?
From the ByRef documentation page:
When passing large strings to a function, ByRef enhances performance and conserves memory by avoiding the need to make a copy of the string.
Windows 7 Pro (64 bit) - AutoHotkey v1.1+ (Unicode 32-bit)
burque505
Posts: 585
Joined: 22 Jan 2017, 19:37

Re: [Function] SplashText

08 May 2018, 20:15

Thank you for sharing this, iPhilip, it will certainly come in handy.
The code is really well documented, by the way.
Regards,
burque505
ozzii
Posts: 310
Joined: 30 Oct 2013, 06:04

Re: [Function] SplashText

09 May 2018, 03:51

This can be useful and like said burque505 well documented.
Helgef
Posts: 3199
Joined: 17 Jul 2016, 01:02
Contact:

Re: [Function] SplashText

12 May 2018, 03:41

Very nice, v2 version works well, 2.0-a096-2ad11cb. Maybe intentional, but DefaultOptions has no show key.

Thanks for sharing, cheers.
iPhilip
Posts: 293
Joined: 02 Oct 2013, 12:21

Re: [Function] SplashText

12 May 2018, 15:23

burque505 wrote:Thank you for sharing this, iPhilip, it will certainly come in handy.
The code is really well documented, by the way.
Regards,
burque505
You are welcome, burque505. I hope the effort I put into the documentation will make it easier for people to use.
ozzii wrote:This can be useful and like said burque505 well documented.
Glad you like it, ozzii. :)
Helgef wrote:Very nice, v2 version works well, 2.0-a096-2ad11cb. Maybe intentional, but DefaultOptions has no show key.

Thanks for sharing, cheers.
Thank you, Helgef. Glad you were able to test the v2 version. Yes, I intentionally left out the Show and BackColor keys from the definition of DefaultOptions so as to use the default settings for the placement and color of the GUI window. I would encourage people to modify DefaultOptions to suit their preferences.
Windows 7 Pro (64 bit) - AutoHotkey v1.1+ (Unicode 32-bit)
guest2

Re: [Function] SplashText

13 May 2018, 10:13

I wanted to change back color, but cannot instructions in Help manual that pertains to thus Function and parameters. You did not give an example. Perhaps AHK is only for those that already know how?
iPhilip
Posts: 293
Joined: 02 Oct 2013, 12:21

Re: [Function] SplashText

13 May 2018, 16:08

guest2 wrote:I wanted to change back color, but cannot instructions in Help manual that pertains to thus Function and parameters. You did not give an example. Perhaps AHK is only for those that already know how?
Thank you for trying out the function. I put this link in the function documentation so that you could see what's needed to change the background color but the issue might have to do with arrays so here's a self-contained example for you to try that specifies every option:

Code: Select all

Text := "Hello world!`nHow are you?"
Title := "My Title"
Options := {Font:"s12 cWhite", FontName:"Segoe UI", BackColor:"Black", Text:"Center", Show:"Center"}
SplashText(Text, Title, Options)
Sleep, 3000
SplashText()
ExitApp

; ===============================================================================================================================
; SplashText(ByRef Text:="", ByRef Title:="", Options:="")
; Function:       Creates a customizable GUI window with text in it. Use SplashText() to destroy the window. Calling the
;                 function with any text while a SplashText window is being displayed, destroys the previous window and creates a
;                 new one. The window is "always on top", meaning that it stays above all other normal windows. To change this,
;                 use WinSet, AlwaysOnTop, Off, <insert title of splash window>. The window and the text in it can be customized
;                 through the Options parameter (see below). The current thread's default GUI window name or number is not
;                 changed.
; Parameters:     Text    - (Optional) The text to be displayed in the window. If omitted, the GUI window will be destroyed.
;                 Title   - (Optional) The title of the GUI window. If omitted, the file name of the script will be used.
;                 Options - (Optional) An associative array with any of the following keys:
;                    Font - font options separated by spaces (https://autohotkey.com/docs/commands/Gui.htm#Font)
;                    FontName - the name of the font (https://autohotkey.com/docs/misc/FontsStandard.htm)
;                    BackColor - the background color of the window (https://autohotkey.com/docs/commands/Gui.htm#Color)
;                    Text - text options separated by spaces (https://autohotkey.com/docs/commands/Gui.htm#OtherOptions)
;                    Show - Gui, Show options separated by spaces (https://autohotkey.com/docs/commands/Gui.htm#Show)
;                    Note: If any of the keys are omitted, the value associated with that same key in the static array
;                          DefaultOptions will be used. If Options is omitted, the function generates a window similar to the
;                          window created using the SplashTextOn command.
; Return values:  Handle of the GUI window if one was created.
;                 Blank if the GUI window was destroyed.
; Global vars:    None
; Depenencies:    None
; Tested with:    AHK 1.1.28.00 (A32/U32/U64)
; Tested on:      Win 7 (x64)
; Written by:     iPhilip
; ===============================================================================================================================

SplashText(ByRef Text:="", ByRef Title:="", Options:="")
{
   static GuiHwnd
        , DefaultOptions := {Font:"s11", FontName:"Segoe UI", Text:"Center"}
   
   if Text
   {
      if WinExist("ahk_id " GuiHwnd)  ; If a SplashText window already exists, close it before creating a new one.
         WinClose
      DefaultGui := A_DefaultGui  ; Remember the current thread's default GUI window name or number.
      Options := IsObject(Options) ? Options : {}
      Gui, New, +AlwaysOnTop +Owner -SysMenu +HwndGuiHwnd, % Title
      Gui, Font, % Options.Font     ? Options.Font     : DefaultOptions.Font
               , % Options.FontName ? Options.FontName : DefaultOptions.FontName
      Gui, Color, % Options.BackColor ? Options.BackColor : DefaultOptions.BackColor
      Gui, Add, Text, % Options.Text ? Options.Text : DefaultOptions.Text, % Text
      Gui, Show, % Options.Show ? Options.Show : DefaultOptions.Show
      Gui, %DefaultGui%:Default  ; Restore the current thread's default GUI window name or number.
      Return GuiHwnd
   }
   else if GuiHwnd
   {
      Gui, %GuiHwnd%:Destroy
      GuiHwnd := ""
   }
}
Let me know how this works out for you.
Windows 7 Pro (64 bit) - AutoHotkey v1.1+ (Unicode 32-bit)
guest2

Re: [Function] SplashText

13 May 2018, 17:34

wrt "Let me know how this works out for you."

It works absolutely wonderful and what a perfect and complete response. You have made me (maybe others a great fan). Thank you.
iPhilip
Posts: 293
Joined: 02 Oct 2013, 12:21

Re: [Function] SplashText

13 May 2018, 18:01

You are welcome. :)
Windows 7 Pro (64 bit) - AutoHotkey v1.1+ (Unicode 32-bit)

Return to “Scripts and Functions”

Who is online

Users browsing this forum: CyL0N, gwarble, skribb, swagfag and 28 guests