## Quick Steps

Msg documentation

2 Simple Steps to start working

1. Unzip the Msg.Zip File and begin a New Project or see Copy Msg into an Existing Project (please follow carefully)
2. Call Msg.Init() & Msg.Box() to raise a Msg Dialog Box - see one of the many example methods of raising a Msg Dialog included with the download File

Msg - an alternative Message Box for Excel

## Acknowledgement

Msg was written by Mark Kubiszyn. It was formally known as 'Notify' but so many changes have been made, I decided to change it to 'Msg' and release it under the Terms of the 'Notify', MIT License

• the latest version is version 1.0.1
• as per terms of the Software License, you should leave the following code attribution in situ

' Website/Follow:
' http://www.kubiszyn.co.uk/


## Purchase

You can Purchase Msg for Price £5.99 via FastSpring by clicking here

When you purchase Msg, you will recieve a License for a single use of this Software. Please read the License carefully and observe the Terms of this License

## The Msg Files

Msg comes as a .ZIP archive, meaning that you need to extract the Files before using the Software. You get 2 main Files featuring 8 Preloaders and 10 Icons (or Images) that are embedded into the Msg Workbook - I also include any Files that are loaded into memory as opposed to Strings of Base64 data. The first File is the main 'Msg.xlsm' File used to Copy into your Project, or to test and develop as your finished Software. The second File is 'Msg - finished.xlsm' which has the Examples removed and is ready for deployment showing a single running Task

## Copy Msg into an Existing Project

After unzipping the Msg.zip File (right-click->Extract Files...) !Important, make a Backup of Msg.xlsm Open both Msg.xlsm (or your Backup File) and your own Macro-enabled Project in the same instance of Excel (I am using a new Project called 'Test.xlsm'). Press ALT+F11 to enter the VBA Editor, Expand all visible Nodes and in the Project Explorer Window, drag the UserForm Code Modules, 'frmLightBox' and 'frmMsg' into your Project from the Msg.xlsm Project. Drag the 'Msg' and 'mdIcons' Code Modules into your Project:

Now select Msg.xlsm and click on the '1' Worksheet. Right-click on the '1' Tab and choose 'Move or Copy...'. In the 'To Book' Dropdown Combo, select your Project, choose 'Before Sheet' and select the first Sheet Name in your Project. !Important - DO NOT CHECK 'Create a Copy' - you need to 'MOVE' the '1' Worksheet otherwise the embedded Icons will not follow the Worksheet. Press the 'OK' Button

That's it, now you can add an Example to one of your Project Code Modules and run a Msg Dialog Box - you can even use the Install Base64 Icons Button if your Project resides in the same Folder as the Msg.xlsm File and the unzipped Base64.txt Files - have fun

## Compressing Files

You can Compress your finished Files prior to distribution using VBA DecompilerMore a great little free tool

## Configuration with Screen Shots

Configuring Msg is straightforward. Msg requires one call at the beginning of your Subroutine to initialise the HTML/CSS/Javascript, default settings in memory and another call to display the actual Message Box or Dialog at another point in your Subroutine

The parameters that must be passed include 'Icon', 'Dialog', 'Caption', and 'Message'. There is also an optional 'Timeout' value that can be passed to automatically close the Message after a period of time ie. 2 seconds. Here is the Code to Initialise and Display a Success Message that the user can close by clicking on the Lightbox or the small Close cross:


' initialise
Msg.Init Icon:=icoSuccess

' display the Msg
Msg.Box Dialog:=Success, _
Caption:="Success", _


Here is the Code to Initialise and Display a Success Message that automatically closes after 2 seconds - notice the 'Timeout:=2' added to the end of the Msg.Box() Function and that the Msg does not display the small Close cross:


' initialise
Msg.Init Icon:=icoSuccess

' display the Msg
Msg.Box Dialog:=Success, _
Caption:="Success", _
Message:="Your request has been processed", _
Timeout:=2


Here is the Code to display a Help Message Dialog:


' initialise
Msg.Init Icon:=icoHelp

' display the Msg
Msg.Box Dialog:=Help, _
Caption:="Help", _
Message:="What do you want to do?"


You can display larger Messages with or without an Icon - here is the Code for a Success Dialog with a large Message that has a 'Justify' alignment. Notice that we specify the Dialog Height and Width for this example. You can mix up Text with HTML, so for line breaks I use '<\br />' tags:


' initialise
Msg.Init MessageAlignment:=AlignJustify, DialogHeight:=400, DialogWidth:=600

' display the Msg
Msg.Box Dialog:=Success, _
Caption:="Success", _
Message:="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec interdum metus at purus euismod malesuada. Cras tempor tempus bibendum. Duis at nisl lacus. Nulla a luctus magna, ut malesuada massa. Mauris in ligula sed ipsum maximus pharetra. Curabitur at risus iaculis, gravida turpis non, imperdiet lorem. Praesent fermentum suscipit accumsan. Donec fermentum mi volutpat risus ullamcorper, vel egestas eros aliquet. Vivamus eu ornare massa. In id ornare sapien. Vivamus eget dolor efficitur, sodales quam vitae, tempus elit. Duis fringilla nisi quis felis mollis consectetur. Ut elementum vestibulum sem, eget mattis urna hendrerit ac. Morbi vel sapien tincidunt, gravida sem eu, consectetur purus. Sed egestas urna id accumsan ultricies. Ut condimentum tincidunt est et porttitor." & _
"<\br /><\br />" & _
"In velit lectus, auctor nec aliquet a, varius et neque. Cras venenatis sit amet lectus a consequat. Proin suscipit malesuada placerat. Donec imperdiet lacus nunc, sed ultrices enim pellentesque feugiat. Nulla et libero sit amet neque luctus ultricies. Praesent dolor sem, dapibus vel euismod sed, volutpat vitae nisl. Etiam rhoncus eget lectus nec dignissim. Donec aliquam eu dui vehicula tincidunt."



Msg can display hover Buttons and capture the return result. It can also prevent the user dismissing the Dialog by clicking on the Lightbox. Here is the Code to do both using a Help Dialog with 'Yes' and 'No' Buttons (Yes, No and Cancel are all captured using the vbResult Variable):

    ' initialise
Msg.Init ButtonType:=Help, _
YesButton:="Yes", _
YesCaption:="Yes", _
NoButton:="No", _
NoCaption:="No"

' display a Msg and capture the result of the button press
Dim vbResult As VbMsgBoxResult
vbResult = Msg.Box(Dialog:=Help, _
Caption:="Change Setting", _
Message:="Do you wish to accept the changes?", _
DismissByLightBoxClick:=False)

If vbResult = vbYes Then
MsgBox "You pressed the Yes button", vbInformation
ElseIf vbResult = vbNo Then
MsgBox "You pressed the No button", vbInformation
ElseIf vbResult = vbCancel Then
MsgBox "The Help Dialog was cancelled", vbInformation
End If


You don't have to use the Named Arguments when calling the Init() and Box() Functions, you can just omit the Named Arguments using a comma and set all of the Parameters on a single line. This Code will also create a dynamic Hyperlink that when clicked will open the Website in the default Browser. Please Note: a Backslash '\' has been added before the '<\a' attribute so that you can see the Code below, this should be removed if Copying the Code below into your own Project:

    ' initialise
Msg.Init Help, , , , , , , , , , , , , Help, "Add Me", , "Click to Subscribe to my mailing list", , , "64px"

' display a Msg and capture the result of the button press
Dim vbResult As VbMsgBoxResult
vbResult = Msg.Box(Help, "Subscribe", "Subscribe to: <\a href=""http://www.kubiszyn.co.uk/"" style=""color:#0563C1;"" target=""_blank"" title=""click me, I am a hyperlink"">www.kubiszyn.co.uk")

If vbResult = vbYes Then
MsgBox "You pressed the 'Yes please add me to the list' button", vbInformation
End If


## Function Parameters

Here is a list of Parameters for the Init() and Box() Functions, (marked black) together with examples for each Parameter (where multiple examples are given, you should pass any single occurance as the Parameter):


Init()
Optional Icon As IconType, icoSuccess, icoWarning, icoCriticalError, icoHelp, ldrPreloader, ldrGear
- (depends on the Icon Name given to store in Project - see the Base64Table to see how you can store Icons & Preloaders)

Optional IconPosition As IconPositionType, Center, TopLeft, TopRight, BottomLeft, BottomRight (default)
CenterRight, CenterLeft
- specifies the posistion of the Icon or Preloader

Optional IconSize As Integer, 128 (default), 64, 96
- specifies the size of the Icon or Preloader

Optional DialogWidth As Integer, 400 (default), 960
- specifies the width of the Msg Dialog Box

Optional DialogHeight As Integer, 200 (default but 160 is a nice height to use too), 300, 400
- specifies the height of the Msg Dialog Box

Optional DialogBackgroundColour As String, "#FFFFFF" (default)
- specifies a HTML String to set the Background Colour of the Msg Dialog Box

Optional DismissDialogUsingEscape As Boolean, False (default), True
- specifies whether or not to allow the Msg Dialog Box to be dismissed when a user presses the Escape Button

Optional MessageAlignment As TextAlignType, AlignLeft (default), AlignRight, AlignCenter, AlignJustify
- specifies the alignment of the Message

Optional MessageHeight As Integer, 120 (default)
- specifies the height of the Message

Optional MessagePadding As Integer, 6 (default)
- specifies the padding around the Message

Optional MessageBorderColour As String, "none" (default), "#000000"
- specifies a HTML String to set the Border Colour of the Message

Optional MessageBackgroundColour As String, "transparent" (default), "#000000"
- specifies a HTML String to set the Background Colour of the Message

Optional MessageVerticalScrollbar As Boolean, False (default), True
- specifies whether or not to display a Vertical Scrollbar in the Message

Optional ButtonType As MessageBoxType, Success, CriticalError, Warning, Help
- specifies the Schema of the Button to display

Optional YesButton As String, "Yes", "OK"
- if passed, displays a Button with the passed String as its name

Optional NoButton As String, "No", "Cancel"
- if passed, displays a Button with the passed String as its name

Optional YesCaption As String, "Yes", "Click to Subscribe to the Kubiszyn.co.uk mailing list"
- if passed, displays a Caption when the Button is Hovered over

Optional NoCaption As String, "No", "Click to Cancel the Dialog"
- if passed, displays a Caption when the Button is Hovered over

Optional ButtonTop As String, "10px"
- specifies whereabouts the Button is placed

Optional ButtonWidth As String, "64px"
- specifies the Button width

Optional ButtonHeight As String, "60px"
- specifies the Button height

Optional LineHeight As String, "60px"
- specifies the height of each Text line in a Button

Optional DisplayCloseCross As Boolean = True (default), False
- whether or not to display the small Close Cross shown at the top right of the Msg Dialog Box


Box()
ByVal Dialog As MessageBoxType, Success, CriticalError, Warning, Help
- specifies the type of Msg Dialog that will be displayed

ByVal Caption As String, "Success", "Error", "Warning", "Help"
- specifies the Caption on the Msg Dialog Box Titlebar

ByVal Message As String, "Your request has been processed"
- specifies the Message that will be displayed

Optional Timeout As Integer, 0, 2, 5
- specifies the amount of time that the Msg Dialog Box is displayed before it is closed

Optional DismissByLightBoxClick As Boolean, True (default), False
- whether or not to allow a user to dismiss a Msg Dialog Box by clicking anywhere on the Lightbox

Optional Callback As Variant, "DoTask" (a Subroutine Name to be ran as a Msg Dialog Box is running)
- specifies a Subroutine that can be run after displaying a Msg Dialog Box - the task will update the Msg Dialog Box during the running of the task


## HTML & Tweaking Things in Msg

One of the things that you will probably want to do is to tweak the Font or Font Size. Msg gives you the ability to tweak a number of things by using 'span style' to change things like the Font Size when passing in your 'Title' or 'Message'. Anything you send in the Message Parameter sets the Pop Boxes 'innerHTML'. For example to change the Font for a Message use the following Code:


' display the Msg
Msg.Box Dialog:=Success, _
Caption:="Success", _
Message:="<span style='font-size:14px'>Your request has been processed</span>"


Now you will see the a larger Font Size

You can use HTML Tags like '<b>' Bold, '<u>' Underline or change the Colour using '<span style='color:Red'>Your request has been processed</span>'

If you would like to Add dynamic content ie. a Hyperlink without using the Link Pop Box then you can easily do this - remember that not everything can be set for the 'innerHTML' ie. Lists
Here is the Code to change the Font Colour and add a Hyperlink - notice the use of the target='_blank' to open a new Window for the Link:

MessageText:="This is example content.  You can <span style=\'color:#F39C11;text-decoration:underline;\'><i>change</i></span> this content.  You can add dynamic HTML content <a href=\'http://www.kubiszyn.co.uk\' target=\'_blank\' style=\'color:#518FF5 !important\'>www.kubiszyn.co.uk</a>"


Please Note: some characters need to be 'Slashed' out so that they will accepted by the Javascript - these include the ' (apostrophe) ie. \'

All Icons and Loaders are embedded into Sheet"1" or 'shtMsg' (Worksheet Code Module Name). This Sheet has a Table called 'Base64Table'. Default Icons and Preloaders (animations) have been added at the top of the Table. You can configure this Table to load from Base64 Encoded, embedded Text or to load the data from a File. To load a new Icon, you need to adjust the Table to specify the following:


' Base64Table
Column 1 Icon or Loader Name icoSuccess, icoWarning, icoCriticalError, icoHelp, ldrGear, ldrRotator, ldrMagnifier
- specifies a Name for the Icon or Preloader animation which will be added to the mdIcons Code Module as a Enum 'IconType'

Column 2 UID 1, 2, 3
- specifies a unique ID for the Icon or Preloader animation - this is a Formula that generates the next whole Integer
- if this Formula appears currupt after editing the Table, simply Copy down the first Formula or just number your
Icons consecutively ie. 1, 2, 3 etc.

Column 3 Load from File Y, N
- specifies whether or not to load the data from a File or from the Table, this can be lower or upper case

Column 4 Base64 Encoded Data or Filename (depends on Y/N for Load from File option)
'C:\Archive\- a_My Programming\- a_My Excel\Working\Msg\bar2.txt'
- specifies the Base64 Encoded Text or a Filename including the full Filepath to a Text File containing the Base64 Encoded data
- Please Note: this can be just a Filename, but the File has to be in the same Folder as the 'Msg' Workbook
- for examples of Base64 Data Strings, see the next Section 'Msg Base64 Encoded Icons'


If an Error occurs the Code written to the 'mdIcons' Code Module will no longer include the Names of your Icons or Preloaders and you will recieve an Error when further compiling 'Msg'. An Error message will also be present in the 'mdIcons' Code Module. To rectify this you need to ensure everthing in the 'base64Table' is configured correctly. When making any major changes, please ensure that you backup 'Msg' first

## Msg Base64 Encoded Icons

Here are examples of Base64 Encoded Icons (these are the 4 main Icons used by Msg) - you can use www.base64image.org or Motobit (Icons) to Base64 Encode an image or Motobit (Web Images) for Web-based Images. Please Note: you need to leave these 4 by default in the Table, however after developing your Msg Project, you can completely remove the Table and use Sheet("1") as a normal Worksheet as all of the data is compressed and hidden within the Worksheet to travel with your Project - you should also remove all of the Code used to load Icons from the 'mdMsg' Code Module


' icoSuccess

' icoWarning

' icoCriticalError

' icoHelp


When using the encoded data, please ensure that you add the relevant prefix for an image ie. for a 'png' encoded image, add:
'data:image/png;base64,/' (the last forward slash before the data is optional

If your encoded data is too large for the Table, you should load it from File. Once installed you do not have to keep reloading it - the data is compressed and encrypted into the Worksheet

## Use a Config Table

You may wish to use a Table as a Config Table ie. Icon Number, Dialog Number, Caption and Message and refer to the Row that you want to populate 'Msg.Init()' and 'Msg.Box()' with. Here is the Code to do that (add 'Table1' in 'Sheet1' with the headers, Icon, Dialog, Caption and Message, then run the Code setting the Const to the Index number for the Table Row to pick the settings from, fig. 1). I have made a Table that you can pick the Icon Types and Dialog Types from using Data Validation (fig. 2):

Fig. 1

Fig. 2


Public Sub Example_Pick_Index4()

Const Index As Long = 4

' initialise
Msg.Init Icon:=Worksheets("Sheet1").ListObjects("Table1").ListColumns("Icon").DataBodyRange(Index), _
IconPosition:=CenterRight, DialogHeight:=140

' display the Msg
Msg.Box Dialog:=Worksheets("Sheet1").ListObjects("Table1").ListColumns("Dialog").DataBodyRange(Index), _
Caption:=Worksheets("Sheet1").ListObjects("Table1").ListColumns("Caption").DataBodyRange(Index), _
Message:=Worksheets("Sheet1").ListObjects("Table1").ListColumns("Message").DataBodyRange(Index)

End Sub



## Developer Tweaks

I have included a few settings that can be tweaked by developers. You can find these at the top of both UserForm Code Modules. You can tweak the Light Box Darkness, the Light Box Timer Speed and the Light Box Transparency Step. For example if you would like a slightly darker LightBox then you would adjust the following setting in the Msg UserForm Code Module from '60' to '80':


' // configurable vars for developers
' - use this to deepen the LightBox Colour effect
'   default 0:=Lightest, 100:=Darkest
Private Const intLightBoxDarkness As Integer = 80


When using the setting above you can also adjust the speed of the LightBox by tweaking the Transparency Step from '8' to '14'. Now the darker LightBox will also fade in at the same rate or slightly faster:


' - increase this if using a darker LightBoxOpacity to speed up the LightBox Fade
'   ie. LightBoxOpacity = 80, intLightBoxTransparencyStep = 14
Private Const intLightBoxTransparencyStep As Integer = 14


If you prefer an even faster, smoother fade speed, you can also tweak the LightBox Timer Speed from '0.02' to '0.01':


' // configurable vars for developers
' - you can adjust this but ideally only between 0.01 -> 0.03
'   use the Transparency Step when using a darker LightBox
Private Const dblLightBoxTimerSpeed As Double = '0.01'


## Screen Shots

There are 4 types of standard Msg Dialogs Boxes available. Here they are together with their respective standard Icons and Messages - MessageAlignment is 'AlignLeft', MessagePadding is standard and the IconPosition is displayed 'BottomRight' (having been designed to fit nicely in this position):

1. Success - Your request has been processed

1.1 Success with a larger Font Size of '14px'

2. Warning - You must enter all required information

3. Critical Error - You have encountered a critical error

4. Help - This is a help message for Msg

Here is a non-standard sized Message Box without an Icon, with MessageAlignment 'Justify' using the Success Dialog:

Here is the same Message Box with MessagePadding set to '24' and MessageBorderColour '#CCC':

5. Warning Dialog with Mapped Yes/No Buttons

6. Help Dialog with Bespoke Mapped Button

7. Success Dialog with Mapped Yes/No Buttons

8. Critical Error Dialog with Bespoke Yes/No Buttons

9. Success Dialog with Bespoke OK Button

10. Help Dialog with Bespoke Button that will Timeout after 5 seconds

11. Success Dialog with Bespoke HTML formatting for the Message

12. Help Dialog with Bespoke Zooey Preloader Spanner (Icon Position:=BottomRight, DialogHeight:=140)

13. Critical Error Dialog with Bespoke Rotator2 Preloader Circle (IconSize:=72, Icon Position:=BottomRight, DialogHeight:=140)

14. Warning Dialog with Bespoke Infinity Preloader (IconSize:=128, IconPosition:=Center, DialogHeight:=140)

15. Help Dialog with Bespoke Leonardo Preloader (IconSize:=128, IconPosition:=CenterRight, DialogHeight:=140)

16. Help Dialog with Bespoke Magnifier Preloader (IconSize:=96, IconPosition:=TopRight, DialogHeight:=140)

17. Simple Icons - Spanner

18. Simple Icons - Magnifier

19. Simple Icons - Quote

20. Simple Icons - Calendar

21. Simple Icons - File

22. Simple Icons - Speech

## Support

Support is only given to Purchased Software. You should only contact me on the Support Email address supplied by FastSpring - please provide proof of purchase ie. Email address or Order Reference

Please Note: I Cannot undertake any bespoke modifications to this Software! Under the Terms of the License you are free to do this yourself or engage someone that can do this work on your behalf

## Changelog

15.03.2018 - Version 1.0.1. Fixed the 'ReleaseDC' 64bit declaration so instead of returning a 'LongPtr' it returns a 'Long'. Changes made to the License Text within the VBA Code Modules

23.02.2018 - Version 1 released. Please Note: this Project was formally known as 'Notify'. Msg has been modified with many new features and VBA Code changes and then released under a new License