NAME

Mac::Apps::PBar - An AppleEvent Module for Progress Bar 1.0.1

SYNOPSIS

        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;

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.

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 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.

SEE ALSO

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 of May 1997.

AUTHORS

Chris Nandor <pudge@pobox.com> http://pudge.net/

Alan Fry <ajf@afco.demon.co.uk>

Copyright (c) 1998 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. Please see the Perl Artistic License.

HISTORY

Version 1.3, 3 January 1998

General cleanup. Now requires MacPerl 5.1.4r4.

Version 1.2, 13 October 1997

Switched to Mac::Apps::Launch package.

Version 1.1, 16 September 1997

Put in the hashref methods to change multiple data in one call.