NAME

ProgressMonitor::AbstractStatefulMonitor - a reusable/abstract monitor implementation keeping track of state

SYNOPSIS

  ...
  use classes
    extends  => 'ProgressMonitor::AbstractStatefulMonitor',
    new      => 'new',
    ...
  ;

  sub new
  {
    my $class = shift;
    my $cfg   = shift;

    my $self = $class->SUPER::_new($cfg, $CLASS);

    ...
  }

  sub render
  {
    my $self = shift;
        
    ...
  }

DESCRIPTION

This class implements the fully abstract ProgressMonitor interface and is what generally should be used as a base. It deals with tracking the state changes and cancellation and calls the subclass through 'render' at appropriate times. It is strict and throws exceptions if misused.

When extended it provides several accessors for 'protected' data, i.e. only for the use of subclasses. These accessors are prefixed with '_'.

Subclassing this normally entails only defining the render method.

See ProgressMonitor for the general description of a progress monitor behavior with regard to state etc.

Inherits from ProgressMonitor.

METHODS

begin( $totalTicks )

Enters the active state from the preparing state, setting the total ticks that should be reached, or use undef to indicate that the number of ticks is unknown.

Throws X::InvalidState for an incorrect calling sequence.

end

Enters the done state from the active state, and the monitor can then not be used again.

Throws X::InvalidState for an incorrect calling sequence.

isCanceled

Returns the cancellation flag.

prepare

Enters the preparing state from the new state, and the monitor can now be used while the code is figuring out how many ticks it will need for the active state.

Throws X::ProgressMonitor::InvalidState for an incorrect calling sequence.

setCanceled( $boolean )

Sets the cancellation flag.

tick( $ticks )

Advances the tick count towards the total tick count (depending on if its is in the preparing state or if the total is unknown).

Throws X::ProgressMonitor::TooManyTicks if the tick count exceeds the total.

PROTECTED METHODS

_new( $hashRef, $package )

The constructor, needs to be called by subclasses.

Configuration data: resolution (default => 8) Should not needed to be used. Makes sure to round the results down to the given size decimals so as to avoid wacky floating point rounding errors when using inexact floating point values in calculations (this happens when using subtasks).

  completeAtEnd (default => 1)
    Will automatically add any ticks not performed when end is called.

_get_cfg

Returns the configuration object.

_get_state

Returns the current state value.

_get_ticks

Returns the current tick value.

_get_totalTicks

Returns the total tick value.

AUTHOR

Kenneth Olwing, <knth at cpan.org>

BUGS

I wouldn't be surprised! If you can come up with a minimal test that shows the problem I might be able to take a look. Even better, send me a patch.

Please report any bugs or feature requests to bug-progressmonitor at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ProgressMonitor. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find general documentation for this module with the perldoc command:

    perldoc ProgressMonitor

ACKNOWLEDGEMENTS

Thanks to my family. I'm deeply grateful for you!

COPYRIGHT & LICENSE

Copyright 2006,2007 Kenneth Olwing, all rights reserved.

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