Version 3.1
If you have already purchased this Software, let me take a moment to thank you for being a loyal customer
You are entitled to free lifetime updates for ALL future builds
This documentation is to help you understand the Software and to give you a more meaningful insight into what it can do. Please go through the documentation and read it carefully · Basic Excel and some VBA skills will be required to Copy the Class into a Project and configure the Preloader
You will need the following Excel Version & Prerequisite to use this Software
No support is provided for customization or development of this Software
The Preloader Class Fades and displays an animation over a Lightbox with a Message to measure the percentage of 'some task'. It uses 3 Shapes for the Lightbox, Animation and Message. It is very flexible and highly configurable. It is farily lightweight, requiring only the Class File and a piece of Code for the Callback to be stored in a Standard Code Module of your VBA Project
Preloader is my latest Preloader Project - you can find my original Free Preloader, Version 2 here
Open the Preloader.xlsm' File. Pressl ALT+F8 and run any of the Examples in the Workbook. To add the Class to your own VBA Project simply drag the Class across in the Project Viewer or Export it from the 'Preloader.xlsm' File and then import it back into your own VBA Project. The only additional Code you will need is the Preloader Class declaration at the top of the 'mdPreloader' Code Module and the PreloaderCallback() Subroutine at the bottom of the 'mdPreloader' Code Module
New in Version 3.1 is the ability to create a Drop-down Bar effect in a Worksheet using the Lightbox Shape. By setting Preloader.DropDownBar = True, you can use the Preloader.BarEasing Property to set different Drop-down Bar easings. You can also change the speed of the Bar using the LightboxFadeInSpeed Property. Here is a video of the Drop-down Bar in action using easing 'OutBack' to drop the Bar down at pace and then spring back up slightly:
The Preloader uses an 'msoShapeBlockArc' Shape, but it can use any Shape with any Image. It doesn't take much Code to create a basic Preloader to run a simple Task and display a Message to the user as a percentage of the Task complete. Here is the Code to create a basic Preloader - notice where you would add your task after the 'your Code goes here...' comment. The Preloader.Update() Class Property can be updated with any Text that you like
'-¬ BasicPreloader(), create a very basic Preloader with a Message and % of a Task complete Public Sub BasicPreloader() Set Preloader = New clPreloader With Preloader.Animation .IncrementRotation 1 .Adjustments.Item(2) = 90 .Adjustments.Item(3) = 0.2 End With Preloader.StartThread ' your Code goes here... Dim Task As Long For Task = 1 To 100000 DoEvents Preloader.Update = "Processing " & Round(Task / 1000, 0) & "%" Next Task Preloader.StopThread Set Preloader = Nothing End Sub
You can also write this a little shorter using With for the actual Preloader Class object that you just created
'-¬ BasicPreloaderShortNotation(), as above but using a shorter notation Private Sub BasicPreloaderShortNotation() Set Preloader = New clPreloader With Preloader With .Animation .IncrementRotation 1 .Adjustments.Item(2) = 90 .Adjustments.Item(3) = 0.2 End With .StartThread ' your Code goes here... Dim Task As Long For Task = 1 To 100000 DoEvents .Update = "Processing " & Round(Task / 1000, 0) & "%" Next Task .StopThread End With Set Preloader = Nothing End Sub
Okay so we can setup a basic Preloader, which can interact with Code, but it's not really that sexy. Let's look at 'pimping' it all up - Preloader is so flexible and configurable. For this example, we will Fade the Lightbox, Preloader and Message in and out, we will use a 'Paintbrush' Icon Shape on a hidden Worksheet and we will change some of the Colours for the Lightbox and the Message Font Name and Colour. Here is the Code to do that:
'-¬ PimpUpYourPreloader(), create a sexy Preloader that Fades in and out, using a hidden Shape Public Sub PimpUpYourPreloader() Set Preloader = New clPreloader Preloader.ChangeShape Preloader.Animation, msoShapeRectangle, ThisWorkbook.Sheets("Icons").Shapes("Icon3") With Preloader.Lightbox .Fill.ForeColor.RGB = RGB(255, 255, 255) End With With Preloader.Animation .IncrementRotation 1 End With With Preloader.Message .TextFrame2.TextRange.Characters.Text = "Processing..." .TextFrame2.TextRange.Characters.Font.Name = "Consolas" .TextFrame2.TextRange.Characters.Font.Fill.ForeColor.RGB = RGB(51, 51, 51) End With Preloader.FadeInLightbox = True Preloader.FadeInAnimation = True Preloader.StartAnimationAfterFadeIn = False Preloader.FadeInMessage = True Preloader.StartThread ' your Code goes here... Dim Task As Long For Task = 1 To 100000 DoEvents Preloader.Update = "Processing " & Round(Task / 1000, 0) & "%" Next Task Preloader.Animation.Visible = msoFalse Preloader.Message.TextFrame2.TextRange.Characters.Text = "Complete OK" Preloader.FadeOutMessage = True Preloader.FadeOutLightbox = True Preloader.StopThread Set Preloader = Nothing End Sub
You don't have to let your Preloader hog the centre of the Screen - you can also let it appear in any of the four corners of the Woksheet or in fact anywhere on the Worksheet. Here is a lovely example that spins an Arrow Icon at the top of the Worksheet. It uses Protection to prevent a user from clicking on any of the Shapes. It also has multiple Updates for the Message as the Task progresses. The Font Name and Size are changed. The end of the Task is nicely finished using different techniques - here is the Code
' -¬ AlignYourPreloaderTopLeft(), create a Preloader at the Top Left of the ActiveWindow using an Icon from a hidden Shape detailing how to use the Update for Messages ' - this example also uses Protection to prevent a user clicking on the Shapes Public Sub AlignYourPreloaderTopLeft() Set Preloader = New clPreloader Preloader.Protection = True Preloader.ChangeShape Preloader.Animation, msoShapeRectangle, ThisWorkbook.Sheets("Icons").Shapes("Icon1") Preloader.SetAlignment Preloader.Lightbox, msoAlignTops, msoAlignLefts With Preloader.Lightbox .Fill.ForeColor.RGB = RGB(255, 255, 255) .Width = 10000 .Height = 66 .Left = -2 .Top = -2 .Line.Visible = msoTrue .Line.ForeColor.RGB = RGB(245, 207, 135) .Fill.Transparency = 0.05 End With Preloader.SetAlignment Preloader.Animation, msoAlignTops, msoAlignLefts With Preloader.Animation .IncrementRotation 1 .Width = 48 .Height = 48 .Top = .Top + 8 .Left = .Left + 8 End With Preloader.SetAlignment Preloader.Message, msoAlignTops, msoAlignLefts With Preloader.Message .Width = 250 .TextFrame2.TextRange.ParagraphFormat.Alignment = msoAlignLeft .TextFrame2.TextRange.Characters.Text = "Preparing to start..." .TextFrame2.TextRange.Characters.Font.Name = "Calibri" .TextFrame2.TextRange.Characters.Font.Size = 11.5 .TextFrame2.TextRange.Characters.Font.Fill.ForeColor.RGB = RGB(51, 51, 51) .Top = .Top + 16 .Left = .Left + 56 End With Preloader.FadeInLightbox = True Preloader.FadeInAnimation = True Preloader.StartAnimationAfterFadeIn = False Preloader.FadeInMessage = True Preloader.StartThread ' your Code goes here... Dim Task As Long For Task = 1 To 100000 DoEvents If Task < 50000 Then Preloader.Update = "Processing " & Round(Task / 1000, 0) & "%" ElseIf Task < 90000 Then Preloader.Update = "Half way... " & Round(Task / 1000, 0) & "%" Else Preloader.Update = "Nearly there now... " & Round(Task / 1000, 0) & "%" End If Next Task Preloader.Update = "Processing Complete" Preloader.Animation.Visible = msoFalse Preloader.Pause 100 Preloader.FadeOutMessage = True Preloader.FadeOutLightbox = True Preloader.MessageFadeOutSpeed = 0.01 Preloader.StopThread Set Preloader = Nothing End Sub
At the heart of the Preloader are the 3 main Shapes, the Lightbox, the Animation and the Message. This is the most powerful feature of the Class. Each Shape has its Property exposed through the Preloader Class object and you can access all of the members of the Shape ie. the 'Fill', the 'Line', the 'Font' etc. To access these settings, simply add the following Code using the 'With' and 'End With' statements:
With Preloader.Lightbox .Line.Visible = msoTrue .Line.ForeColor.RGB = RGB(245, 207, 135) .Fill.Transparency = 0.05 End With With Preloader.Animation .IncrementRotation 1 .Adjustments.Item(2) = 90 .Adjustments.Item(3) = 0.2 End With With Preloader.Message .TextFrame2.TextRange.Characters.Text = "Processing..." .TextFrame2.TextRange.Characters.Font.Name = "Consolas" .TextFrame2.TextRange.Characters.Font.Fill.ForeColor.RGB = RGB(51, 51, 51) End With
Another powerful feature of the Preloader Class is all of the Property's. You can read and write many Property's for the Preloader Lightbox, Animation and Message. Here are some of the Preloader Property's together with an idea of what they do - the Lightbox, Animation and Message Parameters show are just a few of the complete member settings that you can use:
' set the Application Protection and Interactivity ' - Protection is required otherwise Shapes can be clicked ' - this will still allow any Code to run ' - Interactivity denies any kind of user interaction Preloader.Protection = True Preloader.Interactive = False ' change any of the Shapes used for the Lightbox, Animation or Message ' - you can even assign your own user-defined Shape (stored on the Hidden Icons Worksheet) 'Preloader.ChangeShape Preloader.Lightbox, msoShapeOval 'Preloader.ChangeShape Preloader.Animation, msoShapeRectangle, ThisWorkbook.Sheets("Icons").Shapes("Icon2") 'Preloader.ChangeShape Preloader.Animation, msoShapeRectangle 'Preloader.ChangeShape Preloader.Message, msoShapeOval ' set any additional LightboxShape member parameters With Preloader.Lightbox .Fill.ForeColor.RGB = RGB(255, 255, 255) .Fill.Transparency = 0.01 End With ' set any additional Animation member parameters With Preloader.Animation '.Fill.Transparency = 0.5 ' you can use an image directly from your PC '.Fill.UserPicture "C:\Archive\Working\Software\Rollover Burger Buttons\version 1\working files\1541077114_circle-icons-1\Circle Icons\PNG\64\1055018 - paintbrush.png" '1054934 - windy.png" '1054937 - water.png" ' - set the default Preloader Shape Rotation Position, Important! do not edit .IncrementRotation 1 ' edit these settings for the default Animation Shape msoShapeBlockArc ' - this Shape has points that can be edited dynamically ' the circle length of the Preloader .Adjustments.Item(2) = 90 ' the width of the Preloader .Adjustments.Item(3) = 0.2 ' edit these settings for the Preloader Shape Width and Height '.Height = 48 '.Width = 48 End With ' set any additional Message member parameters With Preloader.Message ' the Width .Width = 100 ' the initial Text .TextFrame2.TextRange.Characters.Text = "Processing..." ' the Font Size and Name '.TextFrame2.TextRange.Characters.Font.Size = 12 .TextFrame2.TextRange.Characters.Font.Name = "Consolas" '.TextFrame2.TextRange.Characters.Font.Fill.ForeColor.RGB = RGB(51, 51, 51) End With ' set the alignment for any of the Shapes used for the Lightbox, Animation or Message Preloader.SetAlignment Preloader.Lightbox, msoAlignMiddles, msoAlignCenters, True Preloader.SetAlignment Preloader.Animation, msoAlignMiddles, msoAlignCenters Preloader.SetAlignment Preloader.Message, msoAlignMiddles, msoAlignCenters ' Fade in the Lightbox and set the Speed and Step Preloader.FadeInLightbox = True Preloader.LightboxFadeInSpeed = 0.02 Preloader.LightboxFadeInStep = 0.1 ' Fade in the Animation and set the Speed and Step Preloader.FadeInAnimation = True Preloader.AnimationFadeInSpeed = 0.06 Preloader.AnimationFadeInStep = 0.1 ' begin the Animation after the Animation Shape has Faded in Preloader.StartAnimationAfterFadeIn = False ' Fade in the Message and set the Speed and Step Preloader.FadeInMessage = True Preloader.MessageFadeInSpeed = 0.08 Preloader.MessageFadeInStep = 0.1 ' set the Animation timing for the Callback Subroutine Preloader.AnimationRotationSpeed = 0.1 ' set the Preloader Easing Type Preloader.Easing = Linear ' Start the Preloader Preloader.StartThread ' refere directly to the Animation and Message parameters Preloader.Animation.Visible = msoFalse Preloader.Message.TextFrame2.TextRange.Characters.Text = "Complete OK" ' Fade out the Message and set the Speed and Step Preloader.FadeOutMessage = True Preloader.MessageFadeOutSpeed Preloader.MessageFadeOutStep ' Fade out the Animation and set the Speed and Step Preloader.FadeOutAnimation = True Preloader.AnimationFadeOutSpeed = 0.01 Preloader.AnimationFadeOutStep = 0.1 ' Fade out the Lightbox and set the Speed and Step Preloader.FadeOutLightbox = True Preloader.LightboxFadeOutSpeed = 0.01 Preloader.LightboxFadeOutStep = 0.1 ' Stop the Preloader Preloader.StopThread
Preloader uses some easing Functions for animation for the rotation. The default easing is 'Linear' which is basic a regular transition, no acceleration or decceleration. You can use easing by setting the 'Preloader.Easing' Property to any of the following:
Preloader.Easing = InCubic Preloader.Easing = InQuint Preloader.Easing = Linear Preloader.Easing = OutBack Preloader.Easing = OutQuint Preloader.Easing = OutSine
Here is a Preloader that uses Easing with a larger Preloader and the Message at the Top, Centre of the Worksheet:
You can store Shapes with Images on a hidden Worksheet and use these for your Preloaders. Here is an image of 3 that I store as Shapes for these examples. They are included in the purchase but only as part of the Shape Object - the images themselves are not included but you can download them for free at IconFinder created by Nick Roach:
Shapes cannot have their images or Pictures set from Base64 encoded data stored in memory
The Office 2016 Icons (Graphic Shapes) cannot be used as Shapes with Images for Preloader as the Styles including the Image cannot be 'Picked-up' and then 'Applied' to the Preloader
This is a Screen Shot of the basic Preloader
This is a Screen Shot of a Pimped-up Preloader using a 'Paintbrush' Image for the Animation Shape
This is a Screen Shot of a Pimped-up vertically Top-aligned and Horizontally Left-aligned Preloader using an 'Arrow' Image for the Animation Shape
This is a Screen Shot of the same Preloader as above. but displayed over the 'License' Worksheet
This example is a demonstration of using easing on the Bar (Lightbox Shape) to drop the Bar down at pace and then spring back up again slightly. It is a smooth effect
For these Preloaders I purchased an image from Can Stock Photo and then ran it using the Preloader Class Code. I changed the Lightbox to a Full Fill in White, so no Transparency
Here are some other Videos of Preloaders
Here is a Video of a Preloader using 'InCubic' easing
How do I use different Images for the Animation?
You can either Load an Image from a File directly to the 'Preloader.Animation' Shape like this:
With Preloader.Animation
.Fill.UserPicture "C:\Archive\Working\Software\Rollover Burger Buttons\version 1\working files\1541077114_circle-icons-1\Circle Icons\PNG\64\1055018 - paintbrush.png" '1054934 - windy.png" '1054937 - water.png"
End With
... or you can store many Shapes containing images on a Hidden Worksheet and simply use the 'Preloader.ChangeShape' Subroutine to use the Images like this:
Preloader.ChangeShape Preloader.Animation, msoShapeRectangle, ThisWorkbook.Sheets("Icons").Shapes("Icon2")
Please remember you have purchased very affordable Software and you have not paid for a full-time Software design agency - I am but one man. Occasionally I may help with small tweaks, but these requests will be put on a much lower priority due to their nature. You have not PAID for Support, Support is 100% optional and I provide it for your convenience, so please be patient, polite and respectful
You can find the version history in the Code Module for any Macro-enabled Software or read more information below. The latest Version is always shown first
25.11.2018 (Version 3.1) Added the ability to use easing on a Bar. By setting Preloader.DropDownBar = True, you can use the Preloader.BarEasing Property to set different Drop-down Bar easings. You can change the speed using the LightboxFadeInSpeed --- 21.11.2018 (Version 3) Released --- All previous Versions have been deprecated