FUNCTIONPublished

Processa

Processa( <bAcao>, [<cTitulo>], [<cMsg>], [<lAborta>] )

Creates a processing window with a progress meter to track action execution.

AdvPL functionsInterfaceProcessingProgress meter

01 · OVERVIEW

Overview

Processa creates a dialog with a progress meter and runs an action provided as a code block. The called routine may receive a logical variable by reference to identify cancellation requests. Together with ProcRegua and IncProc, it defines the total number of steps and visually updates progress.

02 · SYNTAX

Syntax

Processa( <bAcao>, [<cTitulo>], [<cMsg>], [<lAborta>] )

Parameters

bAcao

BlocoRequired

Code block executed inside the processing window.

cTitulo

CaractereOptional

Window title.

cMsg

CaractereOptional

Message displayed below the progress meter.

lAborta

LógicoOptional

When true, enables the cancel button.

Return value

Nil, according to the TOTVS Support Center reference.

03 · PRACTICAL EXAMPLE

Create a progress window

#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

Processa opens the window; ProcRegua defines 100 steps and IncProc advances the meter during the For...Next loop.

BEST PRACTICES

Use ProcRegua to set the meter total inside the processed routine.
Use IncProc to increment the meter for each processed item.
If lAborta is enabled, handle the logical variable received by the action to stop safely.

COMMON PITFALLS

Do not ignore cancellation if the action receives the control variable by reference.
Do not use Processa for instant tasks; the window adds complexity without user benefit.
Avoid opening Processa in non-interactive execution.