Geek Documentation Logo

Preloader

Version 3.1


Introduction


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

Requirements

You will need the following Excel Version & Prerequisite to use this Software

  1. Excel 2010, 2013 & 2016 (32bit or 64bit)
  2. Basic Excel and some VBA skills
  3. Windows PC · NOT a Mac!

No support is provided for customization or development of this Software






About Preloader #back to top

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

Features include:

  • * Add a Lightbox, Animation and a Message to the ActiveWorksheet to run a Preloader
  • * Easily add the Preloader Class to your own Projects
  • * Use your own Icons or Images (I recommend using Transparent PNG Images) as the Animation
  • * Use the Easing Functions to create a Preloader animation with easing
  • * Highly configurable





The Download File #back to top

The download File

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

What's New in Version 3.1 #back to top

Version 3.1

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:

Creating a Preloader #back to top

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
                            

Here is the result:

Creating a Basic Preloader

Here is a Video of the same Preloader but with added Fade In and Fade out:

Pimp-up your Preloader #back to top

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
                            

Here are the results:

Pimp-up your Preloader




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
                        


Here are the results:

Aligning a Preloader top left


The Lightbox, Animation & Message Shapes #back to top

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

The Preloader Class Property's #back to top

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

Easing #back to top

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:

a Preloader that uses Easing InCubic


The Hidden Icons Worksheet #back to top

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:

The Hidden Icons Worksheet

Limitations #back to top

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

Screen Shots #back to top

This is a Screen Shot of the basic Preloader

Creating a Basic Preloader

This is a Screen Shot of a Pimped-up Preloader using a 'Paintbrush' Image for the Animation Shape

Pimp-up your Preloader

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

Aligning a Preloader top left

This is a Screen Shot of the same Preloader as above. but displayed over the 'License' Worksheet

Aligning a Preloader top left - Demo






Videos #back to top

Video of a Drop-down Bar using the Lightbox Shape in Action

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



Video of a Bespoke Preloader in Action

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")






Support #back to top

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

Support (limited) for my Software includes:

* Responding to questions or problems regarding the Software and its features
* Fixing valid (replicated) bugs and reported issues for the VERSION I HAVE WRITTEN

Software support does not include:

* Customization and installation services
* Support for third party software or ANY kind of development whatsoever

Before seeking support, please...

* Make sure your question is a valid Software Issue and not a customization request
* Make sure you have read through the documentation and any related video guides before asking support on how to accomplish a task
* Make sure to double check the Software FAQs or online documentation
* Ensure that you access to the VBOM is allowed and that Macros can run in Excel
* Make sure to provide 'proof of purchase' and state the name / version of the Software that you are having issues with when requesting support by Email or via Facebook

How to get Support

Contact Mark Kubiszyn on the Email address provided when you purchased the Software, including the Order Number
Contact Kubiszyn.co.uk via our Facebook Page - remember to be patient, if there has been an issue with your download, I will always respond within 48 hours and will Email you the File directly if neccessary or via Messanger. For other issues the response time may be considerably longer and I may choose to respond to specific questions only (as is my right), depending on what has been asked

Version History (Changelog) #back to top

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


Changelog

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