MagicBox Factory

================
MagicBox Factory is a development tool to assist in the creation of message boxe
s.
"Message boxes provide a simple, standardised method to display information, war
nings and errors to the user. They can also be used to ask simple questions and
to request confirmation of actions."
The Windows API has many message box functions, MessageBox being the most common
ly used, and MagicBox Factory is able to generate the code for a variety of such
functions, including task dialogs.
===============================================================================
MagicBox
--------
Custom message box function. It offers custom buttons and icon, support for hype
rlinks, verification text, font and color, callback and the look and feel of a r
egular message box.
Parameters: Text, [Title, Buttons, Icon, ByRef CheckText, Styles, Timeout, Owner
, FontOptions, FontName, BGColor, Callback]
===============================================================================
MsgBox
------
The MsgBox function displays a message box and waits for the user to click a but
ton and then an action is performed based on the button clicked by the user. Thi
s is a generic description valid for any type of message box.
Parameters:
MsgBox, Text
MsgBox [, Options, Title, Text, Timeout]
Extended options: custom button text, icons and position.
===============================================================================
SHMessageBoxCheck
-----------------
Displays a message box that gives the user the option of suppressing further occ
urrences. If the user has already opted to suppress the message box, the functio
n does not display a dialog box and instead simply returns the default value.
This function supports only a subset of the flags supported by MessageBox. The q
uestion mark icon and the "always on top" option are not available on Windows Vi
sta and higher.
The unique ID is stored in a registry key.
Parameters: Text, [Title, Options, RegVal, Owner]
===============================================================================
MessageBoxIndirect
------------------
Creates, displays, and operates a message box. The message box contains applicat
ion-defined message text and title, any icon, and any combination of predefined
push buttons.
Parameters: Text, [Title, Options, IconRes, IconID, Owner]
===============================================================================
SoftModalMessageBox
-------------------
SoftModalMessageBox encompasses functions like MessageBox, MessageBoxTimeout and
MessageBoxIndirect. Up to 10 buttons can be defined.
Parameters: Text, Title, Buttons, [DefBtn, Options, IconRes, IconID, Timeout, Ow
ner, Callback]
===============================================================================
MsiMessageBox
-------------
Little is known about this function.
Parameters: Text, [Title, Options, Owner]
===============================================================================
WTSSendMessage (WinStationSendMessage)
--------------------------------------
This function can be used to display a message box from a service or on the clie
nt desktop of a specified Remote Desktop Services session. Always on top, no own
er, no focus and no theme.
Parameters: Text, [Title, Options, Timeout, Wait, Session, Server, ByRef Respons
e]
===============================================================================
TaskDialog
----------
Displays a simple task dialog that contains application-defined message text and
title, an icon, and any combination of predefined push buttons.
Parameters: Instruction, [Content, Title, Buttons, IconID, IconRes, Owner]
===============================================================================
TaskDialogIndirect
------------------
The TaskDialogIndirect function creates, displays, and operates a task dialog. T
he task dialog contains application-defined icons, messages, title, verification
check box, command links, push buttons, and radio buttons. This function can re
gister a callback function to receive notification messages.
The code for this function is generated "on demand": only the necessary members
of the TASKDIALOGCONFIG structure are defined.
Sample scripts demonstrating TaskDialogIndirect and MagicBox can be found in the
Examples folder.
===============================================================================
More functions
--------------
The following functions are included in the functions folder, but MagicBox Facto
ry does not generate the code for them:
InputBoxEx
----------
The InputBoxEx function allows the user to enter input value. The type of input
control used by this function can be specified so that the input can be made by
means of a ComboBox or DropDownList, a ListBox, a CheckBox, a calendar (DateTime
or MonthCal), a Hotkey box, a Slider. By default, an Edit box is used.
Parameters: [Instruction, Content, Title, Default, ControlType, ControlOptions,
Width, x, y, WindowOptions, Timeout, Owner]
Instruction: Text in a bigger font size to explain the user's objective with the
dialog box.
Content: Descriptive information, additional details. Hyperlinks can be used.
Title: Title of the window.
Default: Initial text of the input control.
ControlType: The type of the input control.
ControlOptions: Options of the input control. For example: r3 (3 rows), number,
password, checked.
Width: Optional width of the window. Height is adjusted automatically.
x and y: Coordinates. If blank or omitted, the window is centered on the screen.
WindowOptions: Options such as MinimizeBox, AlwaysOnTop and -SysMenu.
Timeout: Time (in seconds) after which the window is automatically closed.
Owner: Handle of the parent window.
The return value is the string or value selected, according to the control type.
ErrorLevel is set as follows: 0 - The user pressed OK. 1 - The user pressed the
Cancel button. 2 - InputBoxEx exited due to timeout.
TaskDialogDirect
----------------
Parameters: Instruction, [Content, Title, CustomButtons, CommonButtons, MainIcon
, Flags, Owner, VerificationText, ExpandedText, FooterText, FooterIcon, Width]
The CustomButtons parameter is a pipe-delimited list of button labels that can b
e displayed as command links provided the flag 0x10 or 0x20.
ShellMessageBox
---------------
This function uses MessageBox on Windows XP and TaskDialog on Vista+.
Parameters: Text, [Title, Options, Owner]
===============================================================================
Return value
------------
MagicBox Factory can optionally generate the conditional statements for the retu
rn value (the "ifs"). For most types of message box it is one of the following v
alues: OK, Cancel, Abort, Retry, Ignore, Yes, No, Try Again, Continue and Timeou
t.
For SoftModalMessageBox and TaskDialogIndirect, the return value is the button I
D.
For the MagicBox function, the return value is the button text with ampersands r
emoved. If the window is dismissed with the close button in the title bar or by
pressing the Esc key, the value is Cancel.
===============================================================================
Keyboard shortcuts
------------------
- F1: Help (MSDN links).
- F9: Displays the message box.
- F10: Opens the code window.
- Alt+F9: Displays the message box in a new instance of AHK.
- Ctrl+F9: Runs the script from the code window.
===============================================================================
Limitations on Windows XP
-------------------------
- Task dialog functions require Windows Vista or higher.
- MsgBox custom button: icon is not supported.
- SHMessageBoxCheck: only the combinations of buttons OK, OK|Cancel and Yes|No
are available.
- MsiMessageBox: the font size is microscopic on Windows XP.
===============================================================================
Credits to:
-----------
- Lexicos, for the function ResourceIdOfIcon.
- TheGood, for task dialog examples.
- just_me, for additional task dialog options via callback.
- A guest, for MsgBoxV2.
- Fanatic Guru, for MsgBox_XY.
- Authors of libraries in use.
- The layout of the custom buttons dialog is based on TDXML Editor.
===============================================================================
Reference
---------
1. http://www.blackwasp.co.uk/MessageBox.aspx
2. http://www.codeproject.com/Articles/18065/TDXML
===============================================================================
License
-------
No portion of MagicBox Factory or any code derived from it can be used in any so
ftware that is sold/licensed commercially, except when otherwise noted.
===============================================================================
Requirements
------------
AutoHotkey 1.1.23+ Unicode 32 or 64-bit. Tested on Windows XP, 7 and 10.