Panel: progress

Syntax

{<name>:} progress <start>,<finish> {,<value>}

Description

Progress sub-panel. A horizontal or vertical bar to show progress within a given range via a blue rectangle within a containing trough. The current progress value is displayed in the middle of the trough. A progress panel has no interactive functionality.

Membership

• Panel window

• Tab window

• Table window

Parameters

• <name>
  A name to be given to the sub-panel for reference purposes.

• <start>
  The value corresponding to the left or bottom of the progress bar. This is a numeric value.

• <finish>
  The value corresponding to the right or top of the progress bar. This is a numeric value.

• <value>
  The initial progress value. This should be between <start> and <finish>. The default is the minimum of <start> and <finish>.

Switches

• -dim=<screen_xy>
  Define the dimensions of the progress bar in pixels. This is a two-element numeric array providing width and height. If only one is required, the other can be set to -1 and will be ignored. Typically, for a horizontal progress bar only the width is supplied, and for a vertical progress bar only the height is supplied.

• -dp=<num>
  The number of decimal places to print when displaying and computing progress values. The default is 0.

• -eb
  Extend the height of the progress bar to the bottom of its parent row or column.

• -er
  Extend the width of the progress bar to the right of its parent row or column.

• -fo=<font>
  The font to be used for the text display of the progress value. This must be a fixed font. If omitted the progress bar inherits the font of its parent row or column.

• -h=<num>
  The height of the progress trough in pixels. The default for vertical progress bars is 100 pixels. For horizontal progress bars, a suitable default is computed from the font size.

• -icol=<color>
  The color of the progress indicator rectangle. If omitted, the system highlight color (typically blue) is used.

• -inv
  Make the sub-panel invisible on creation.

• -j=<just>
  The justification of the progress bar within its parent row or column. Within a parent row the value should be one of L, M, R. Within a parent column the value should be one of T, M or B. The default in both cases is M.

• -link=<text>
  The resize linkage for the panel. This ties panel edges to one or more edges of the parent window, with the result that when the parent window gets resized, the panel gets automatically resized as well. <text> is a combination of the characters L, R, T, B and M. A value of "LRTB" means that the left, right, top and bottom edges of a sub-panel are linked to its parent. The default value is "TL", which links the left and top edges to the parent window but does no resizing because its right and bottom edges are not linked. Note that the linkage is to edges of the parent window, not to column/row extremities. More complex linkage requirements should be done via the window.resize callback on the parent window.

• -pj=<just>
  The position justification of the sub-panel within the panel window. This combined with the -x and -y switches can be used to position the sub-panel by one of its corners. The default is ’TL’. It also defines the control point to be used when repositioning the sub-panel after creation.

• -show
  Show the current progress value within the trough. This is the default behavior. Use -no_show to suppress the text.

• -tc=<color>
  The color for text when displaying the progress value. If omitted the parent window "other color" is used.

• -v
  The progress bar is a vertical bar with the range values displayed from bottom to top. Without this switch the default is horizontal, left to right.

• -w=<num>
  The width of the progress trough in pixels. The default for horizontal progress bars is 100 pixels. For vertical progress bars, a suitable default is computed from possible values within the range.

• -x=<num>
  The x position of the progress bar relative to the top-left corner of its parent row or column. If omitted, the progress bar is placed adjacent to the previously defined sub-panel.

• -y=<num>
  The y position of the progress bar relative to the top-left corner of its parent row or column. If omitted, the progress bar is placed below the previously defined sub-panel.

Callbacks

None

Notes

If the <start> value is greater than the <finish> value the direction of the progress bar is reversed, i.e. left to right, or top to bottom.

Switches -j, -pj, -x and -y apply only to progress bars within a panel window. Progress bars within other windows and menupanes cannot have a user-defined position or justification.

Examples

Create a panel window containing a row of two horizontal progress bars.

window w = wpanel {
   p1: progress 0,100,-tc=red,-w=200;# Red text
   p2: progress 0,10,-dp=2,-w=200,-icol=yellow
}

Set the progress values within them.

w.p1.value = 95
w.p2.value = 4.2