Moodle APIs 3.9
Moodle 3.9.13+ (Build: 20220325)
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
core\progress\display Class Reference
Inheritance diagram for core\progress\display:
core\progress\base core\progress\display_if_slow

Public Member Functions

 __construct ($startnow=true)
 Constructs the progress reporter. More...
 
 end_html ()
 Finishes output. More...
 
 end_progress ()
 Marks the end of an operation that will display progress. More...
 
 get_current_description ()
 
 get_current_max ()
 Checks max value of current progress section. More...
 
 get_progress_count ()
 Obtains current indeterminate progress in a way suitable for adding to the progress display. More...
 
 get_progress_proportion_range ()
 Obtains current progress in a way suitable for drawing a progress bar. More...
 
int increment_progress ($incby=1)
 An alternative to calling progress. More...
 
 is_in_progress_section ()
 
 progress ($progress=self::INDETERMINATE)
 Indicates that progress has occurred. More...
 
 set_display_names ($displaynames=true)
 By default, the progress section names do not display because these will probably be untranslated and incomprehensible. More...
 
 start_html ()
 Starts to output progress. More...
 
 start_progress ($description, $max=self::INDETERMINATE, $parentcount=1)
 Marks the start of an operation that will display progress. More...
 
 update_progress ()
 When progress is updated, updates the bar. More...
 

Public Attributes

int const INDETERMINATE = -1
 Constant indicating that the number of progress calls is unknown.
 
int const TIME_LIMIT_WITHOUT_PROGRESS = 3600
 This value is set rather high to ensure there are no regressions from previous behaviour. More...
 
int const WIBBLE_STATES = 13
 Number of wibble states (state0...stateN-1 classes in CSS)
 

Protected Member Functions

 get_time ()
 Gets time (this is provided so that unit tests can override it). More...
 

Protected Attributes

int $count
 Number of progress calls (restricted to ~ 1/second).
 
array $currents = array()
 Array of current progress values.
 
 $currentstate = 0
 
array $descriptions = array()
 Array of progress descriptions for each stack level.
 
 $direction = 1
 
bool $displaynames = false
 True to display names.
 
int $lastprogresstime
 Time of last progress call.
 
 $lastwibble
 
array $maxes = array()
 Array of maximum progress values for each stack level.
 
int[] $parentcounts = array()
 Array of counts within parent progress entry (ignored for first)
 

Constructor & Destructor Documentation

◆ __construct()

core\progress\display::__construct (   $startnow = true)

Constructs the progress reporter.

This will output HTML code for the progress bar, and an indeterminate wibbler below it.

Parameters
bool$startnowIf true, outputs HTML immediately.

Member Function Documentation

◆ end_html()

core\progress\display::end_html ( )

Finishes output.

(Progress can begin again later if there are more calls to update_progress.)

Automatically called from update_progress when progress finishes.

Reimplemented in core\progress\display_if_slow.

◆ end_progress()

core\progress\base::end_progress ( )
inherited

Marks the end of an operation that will display progress.

This must be paired with each start_progress call.

If there is a parent progress section, its progress will be increased automatically to reflect the end of the child section.

Exceptions
coding_exceptionIf progress hasn't been started

◆ get_current_description()

core\progress\base::get_current_description ( )
inherited
Exceptions
coding_exception
Return values
stringCurrent progress section description

◆ get_current_max()

core\progress\base::get_current_max ( )
inherited

Checks max value of current progress section.

Return values
intCurrent max value - may be core::progress::base::INDETERMINATE.
Exceptions
coding_exceptionIf not in a progress section

◆ get_progress_count()

core\progress\base::get_progress_count ( )
inherited

Obtains current indeterminate progress in a way suitable for adding to the progress display.

This returns the number of indeterminate calls (at any level) during the lifetime of this progress reporter, whether or not there is a current indeterminate step. (The number will not be ridiculously high because progress calls are limited to one per second.)

Return values
intNumber of indeterminate progress calls

◆ get_progress_proportion_range()

core\progress\base::get_progress_proportion_range ( )
inherited

Obtains current progress in a way suitable for drawing a progress bar.

Progress is returned as a minimum and maximum value. If there is no indeterminate progress, these values will be identical. If there is intermediate progress, these values can be different. (For example, if the top level progress sections is indeterminate, then the values will always be 0.0 and 1.0.)

Return values
arrayMinimum and maximum possible progress proportions

◆ get_time()

core\progress\base::get_time ( )
protectedinherited

Gets time (this is provided so that unit tests can override it).

Return values
intCurrent system time

◆ increment_progress()

int core\progress\base::increment_progress (   $incby = 1)
inherited

An alternative to calling progress.

This keeps track of the number of items done internally. Call this method with no parameters to increment the internal counter by one or you can use the $incby parameter to specify a positive change in progress. The internal progress counter should not exceed $max as passed to start_progress for this section.

If you called start_progress with parameter INDETERMINATE then you cannot call this method.

$incby The positive change to apply to the internal progress counter. Defaults to 1.

◆ is_in_progress_section()

core\progress\base::is_in_progress_section ( )
inherited
Return values
boolTrue if currently inside a progress section

◆ progress()

core\progress\base::progress (   $progress = self::INDETERMINATE)
inherited

Indicates that progress has occurred.

The progress value should indicate the total progress so far, from 0 to the value supplied for $max (inclusive) in start_progress.

You do not need to call this function for every value. It is OK to skip values. It is also OK to call this function as often as desired; it doesn't update the display if called more than once per second.

It must be INDETERMINATE if start_progress was called with $max set to INDETERMINATE. Otherwise it must not be indeterminate.

Parameters
int$progressProgress so far
Exceptions
coding_exceptionIf progress value is invalid

◆ set_display_names()

core\progress\display::set_display_names (   $displaynames = true)

By default, the progress section names do not display because these will probably be untranslated and incomprehensible.

To make them display, call this method.

Parameters
bool$displaynamesTrue to display names

◆ start_html()

core\progress\display::start_html ( )

Starts to output progress.

Called in constructor and in update_progress if required.

Exceptions
coding_exceptionIf already started

Reimplemented in core\progress\display_if_slow.

◆ start_progress()

core\progress\base::start_progress (   $description,
  $max = self::INDETERMINATE,
  $parentcount = 1 
)
inherited

Marks the start of an operation that will display progress.

This can be called multiple times for nested progress sections. It must be paired with calls to end_progress.

The progress maximum may be self::INDETERMINATE if the current operation has an unknown number of steps. (This is default.)

Calling this function will always result in a new display, so this should not be called exceedingly frequently.

When it is complete by calling end_progress(), each start_progress section automatically adds progress to its parent, as defined by $parentcount.

Parameters
string$descriptionDescription to display
int$maxMaximum value of progress for this section
int$parentcountHow many progress points this section counts for
Exceptions
coding_exceptionIf max is invalid

◆ update_progress()

core\progress\display::update_progress ( )

When progress is updated, updates the bar.

See also
core::progress::base::update_progress()

Reimplemented from core\progress\base.

Reimplemented in core\progress\display_if_slow.

Member Data Documentation

◆ TIME_LIMIT_WITHOUT_PROGRESS

int const core\progress\base::TIME_LIMIT_WITHOUT_PROGRESS = 3600
inherited

This value is set rather high to ensure there are no regressions from previous behaviour.

For testing, it may be useful to set the frontendservertimeout config option to a lower value, such as 180 seconds (default for some commercial products).

The number of seconds that can pass without progress() calls.


The documentation for this class was generated from the following file: