NAME
    PBar.pm  An AppleEvent Module for 'Progress Bar 1.0.1'

DESCRIPTION
    Progress Bar is a small AppleScriptable utility written by Gregory H. Dow. This module,
    'PBar.pm', generates Apple Event calls using AEBuild in place of AppleScript. Because the
    Apple Event Manager is not involved, Progress Bar updates more quickly.

    In most applications the time taken to up date the Progress Bar must be kept to a minimum.
    On this machine (68030 CPU) An 'AppleScript' update to the progress bar takes about 0.72
    seconds. Using 'PBar.pm' the time is reduced to 0.10 seconds; a seven-fold improvement.

    Progress Bar 1.0.1 is found by a search for the creator type 'PBar' and launched
    automatically. To minimise the time taken for the search, 'Progress Bar 1.0.1' should be
    kept in the same volume as 'PBar.pm'.

SYNOPSIS
            use Mac::AppleEvents
            use Mac::Processes
            use Mac::MoreFiles
            
    Install C<"PBar.pm"> in a folder named C<"Apps"> in the
    C<"Mac"> folder in MacPerl's library path.

TEST PROGRAM
    The following script (ideally saved as a MacPerl droplet) shows 10 increments of the bar at
    1 second intervals. The window is closed when the bar is full after a final five second
    pause.

            #!perl
            # Droplet "Run_PBar"
        
            use Mac::Apps::PBar;

            $bar = Mac::Apps::PBar->new('FTP DOWNLOAD', '100, 50');
            $bar->data({
                    Cap1=>'file: BigFile.tar.gz',
                    Cap2=>'size: 1,230K',
                    MinV=>'0',
                    MaxV=>'1230',
            });
            for(0..10) {
                    $n = $_*123;
                    $bar->data(Valu, $n);
                    sleep(1);
            }
            sleep(5);
            $bar->close_window;

  CREATING A NEW PROGRESS BAR

    Progress Bar 1.0.1 is launced and a new Progress bar created by:

             $bar = Mac::Apps::PBar->new('NAME', 'xpos, ypos');
             
    where the arguments to the C<new> constructor have the following meanings:

    First argument:
        is a string for the title bar of the Progress Bar window.

    Second argument:
        is a string "xpos, ypos" defining the position of the top left-hand corner of the
        window in pixels. The pair of numbers and the comma should be enclosed in single quotes
        as shown.

  SENDING DATA

    Values are sent to the 'Progress Bar' by the 'data' sub-routine using the variable names in
    the 'aete resource' for each of the 'Progress Bar' properties. There are five property
    values for the 'PBar' class. The syntax is:

            $bar->data('property', 'value')

    or

            $bar->data({'property', 'value', 'property', 'value'})

    The second method is suggested.

    Minimum value  "MinV"
        This is the value of the displayed parameter corresponding to the origin of the bar.
        Often it is zero, but may take other values (for instance a temperature bar in degrees
        Fahrenheit might start at 32).

    Maximum value  "MaxV"
        This is the value corresponding to the full extent of the bar. It can take any value,
        such as the size of a file in KB, or 100 for a percentage variable. Bar increments are
        integers, hence discrimination is finer the larger the value of 'MaxV'.

    Current value  "Valu"
        This is the value which sets the progress bar to the position corresponding to the
        current value of the parameter displayed. The value must obviously lie somewhere between
        'MinV' and 'MaxV'.

    Upper caption  "Cap1"
        This string, immediately under the title bar, can be set to anything appropriate for the
        application.

    Lower caption  "Cap2"
        The lower caption string can either be set to a constant value (e.g. 'File size =
        1234K') or up-dated with the bar. For instance it might be appropriate to set "Cap2"
        as follows:

                $n = $max_value - $current_value;
                $bar->data({Cap2=>"remaining $n"});

        Note the double quotes so that the value of '$n' is interpolated.

        It should be remembered however that it will take twice as long to update both 'Cap2'
        and 'Valu' as just to update the bar 'Valu' by itself. In applications where speed is of
        the essence, just the bar value 'Valu' should be changed.

  REFERENCES

    The following documents, which are relevant to AEBuild, may be of interest:

    AEGizmos_1.4.1
        Written by Jens Peter Alfke this gives a description of AEBuild on which the MacPerl
        AEBuildAppleEvent is based. Available from:

                ftp://dev.apple.com/
                devworld/Tool_Chest/Interapplication_Communication/
                AE_Tools_/AEGizmos_1.4.1

    aete.convert
        A fascinating MacPerl script by David C. Schooley which extracts the aete resources from
        scriptable applications. It is an invaluable aid for the construction ofAEBuild events.
        Available from:

                ftp://ftp.ee.gatech.edu/
                pub/mac/Widgets/
                aete.converter_1.1.sea.hqx

    AE_Tracker
        This a small control panel which allows some or all AE Events to be tracked at various
        selectable levels of information. It is relatively difficult to decipher the output but
        AE_Tracker can be helpful. Available from:

                ftp://ftp.amug.org/
                pub/amug/bbs-in-a-box/files/system7/a/
                aetracker2.0.sit.hqx

    Inside Macintosh
        Chapter 6 "Resolving and Creating Object Specifier Records" . The summary can be
        obtained from:

                http://gemma.apple.com/
                dev/techsupport/insidemac/IAC/
                IAC-287.html

    Progress Bar 1.0.1
        Obtainable from Info-Mac archives as:

                info-mac/dev/osa/progress-bar-1.0.1.hqx

    References are valid as at May 1997.

COPYRIGHT
    Copyright (c) 1997 by Chris Nandor and Alan Fry. All rights reserved.

    This program is free software; you can redistribute it and/or modify it under the same terms
    as Perl itself.

AUTHORS
    Chris Nandor <pudge@pobox.com> is responsible for the AEBuild techniques, and particularly
    for evolving the AE object specifications. He wrote the first working script on which this
    module is largely based.

    Alan Fry <ajf@afco.demon.co.uk> wrote the module and this documentation.

HISTORY
    Version 1.1 16 September 1997

