Blitz3D+ Command Reference

JobProgressText$ ( job )

Parameters

job - a Job handle returned by StartJob

Description

Returns the stage text from the worker's latest progress snapshot.

This is the caption for a job's loading bar - whatever the worker last published as SetJobProgress's stage argument: "Parsing header", "Building navigation data", "Compressing". You get a main-thread copy of a bounded string (over-long stage text is truncated by the worker side), so it is always safe to draw. It returns an empty string until the worker publishes a snapshot with text.

Like all progress data it is advisory and only as fresh as the worker's publishing rhythm. Show it next to JobProgress and leave completion decisions to JobFinished, PollJob, and JobState.

For the full story, see the Using Background Jobs guide.

Requires Extended mode.

See also: SetJobProgress, JobProgress, JobProgressDone, JobProgressTotal.

Example

; JobProgressText Example
; -----------------------
; Requires Extended mode.

Graphics 640,480,0,2
SetBuffer BackBuffer()

; The worker builds a level in three named stages
Worker Function BuildLevel(inputBank)
    For phase=1 To 3
        If phase=1 Then stage$="Carving rooms"
        If phase=2 Then stage$="Digging corridors"
        If phase=3 Then stage$="Hiding treasure"
        For toil=1 To 10
            ; Busy work standing in for real level generation
            For dig=1 To 800000
                noise#=Sin(dig)
            Next
            ; The stage string here is what JobProgressText reports
            SetJobProgress (phase-1)*10+toil,30L,stage
        Next
    Next
    Return CreateBank()
End Function

job=StartJob(BuildLevel)

While Not KeyDown(1)

    Cls

    ; JobProgressText returns a copy of the worker's latest stage text
    stage$=JobProgressText(job)

    ; Draw the loading bar so the stage text has context
    progress=JobProgress(job)
    Color 60,60,80
    Rect 70,220,500,24,True
    Color 90,200,120
    Rect 70,220,progress*500/1000,24,True
    Color 255,255,255
    Rect 70,220,500,24,False

    Text 0,0,"Esc: exit"
    Text 70,190,"Watch the stage name change as the worker advances"
    Text 70,254,"JobProgressText(job) = "+Chr(34)+stage+Chr(34)
    If JobFinished(job) Then Text 70,274,"Level complete!"

    Flip

Wend

FreeJob job
End

Index