FOUNDATIONPublished

Progress meters in AdvPL

Processa · ProcRegua · IncProc · RptStatus · SetRegua · IncRegua

Organize long-running processes with progress windows and progress bars.

InterfaceProcessingProgress meterProcessaRptStatus

01 · OVERVIEW

Overview

Progress meters help users understand that a long routine is still running. In AdvPL, the common Processa flow uses an action block, ProcRegua to set the total and IncProc to advance the meter. In another visual model, RptStatus works with SetRegua and IncRegua. Although the names are similar, the pairs belong to different flows; mixing them without validating the context may produce unexpected behavior.

02 · SYNTAX

Syntax

Processa · ProcRegua · IncProc · RptStatus · SetRegua · IncRegua

Parameters

Processa + ProcRegua + IncProc

Processa flowOptional

Creates the progress window, defines the meter total and increments progress during processing.

RptStatus + SetRegua + IncRegua

RptStatus flowOptional

Displays a status window and controls the progress bar with functions for that context.

Return value

Conceptual content. Open each function page for syntax and examples.

03 · PRACTICAL EXAMPLE

Processa with ProcRegua and IncProc

#Include "TOTVS.ch"

User Function RunProcess()
    Local bAction := {|lEnd| U_ProcessItems(@lEnd)}
    Local cTitle  := "Processing"
    Local cMsg    := "Processing items..."
    Local lAbort  := .T.

    Processa(bAction, cTitle, cMsg, lAbort)
Return

User Function ProcessItems(lEnd)
    Local nItem
    Local nTotal := 100

    ProcRegua(nTotal)

    For nItem := 1 To nTotal
        If lEnd
            Exit
        EndIf

        // Process the item here.
        IncProc()
    Next nItem
Return

Expected result

The window created by Processa follows the loop. ProcRegua defines the total and IncProc advances the meter for each processed item.

04 · PRACTICAL EXAMPLE

RptStatus with SetRegua and IncRegua

#Include "TOTVS.ch"
#Include "TopConn.ch"

User Function RunRptStatus()
    Local aArea := GetArea()

    RptStatus({|| U_QueryMeter()}, "Please wait...", "Running query...")

    RestArea(aArea)
Return

User Function QueryMeter()
    Local aArea  := GetArea()
    Local nTotal := 0

    TCQuery "SELECT BM_GRUPO, BM_DESC FROM %table:SBM% SBM WHERE SBM.D_E_L_E_T_ = ' '" New Alias "QRY_AUX"

    Count To nTotal
    SetRegua(nTotal)

    QRY_AUX->(DbGoTop())
    While ! QRY_AUX->(Eof())
        // Process current row.
        IncRegua()
        QRY_AUX->(DbSkip())
    EndDo

    QRY_AUX->(DbCloseArea())
    RestArea(aArea)
Return

Expected result

RptStatus opens a status window. SetRegua defines the total and IncRegua increments the bar as records are processed.

BEST PRACTICES

Use a progress meter when a routine may take noticeable time for the user.
Define the total before the main loop whenever the number of items is known.
Respect the cancellation flag when the process allows interruption.
For more complex processing with logs and concurrency, evaluate FWGridProcess.

COMMON PITFALLS

Do not call IncProc before ProcRegua in the Processa flow.
Do not confuse IncProc with IncRegua: each one belongs to a different progress context.
Avoid opening progress windows in automatic or non-interactive routines without validating the context.
Do not use an unrealistic total: it hurts user perception.