# IupProgressDlg

Definition: | include pGUI.e Ihandle ih = IupProgressDlg()
Description: | Creates a progress dialog element. It is a predefined dialog for displaying the progress of an operation. The dialog is meant to be shown with the show functions IupShow or IupShowXY. Returns: the identifier of the created element.
pwa/p2js: | Not supported.
Notes: | The IupProgressDlg will display the iteration state using a IupProgressBar control. The dialog is not automatically closed, the application must do that manually inside the CANCEL_CB callback or inside your processing loop by checking the STATE attribute. |
Attributes: | Supports all the IupDialog attributes. But some attributes where changed to configure the dialog. We recommend changing only the following attributes:
ICON | Dialog’s icon.
TITLE | (non inheritable): Dialog’s title. Default: NULL. If not set the title bar will not be displayed and the dialog will occupy less space on screen.
VISIBLE | Simply call IupShow or IupHide for the dialog.
PARENTDIALOG | (creation only): Name of a dialog to be used as parent. This dialog will be always in front of the parent dialog. When NULL it will use the parent’s background color. (since 3.28)
| Other attributes were set to values different than the default value (but can still be changed): RESIZE=NO, MAXBOX=NO, MINBOX=NO, MENUBOX=NO
New attributes: | All non inheritable.
COUNT | current count of iterations.
INC | (write-only): increment the current count by the given amount. If set to NULL will increment +1.
PERCENT | current percent of iterations.
TOTALCOUNT | total number of iterations.
STATE | describe the state of the iteration. Can be: IDLE, PROCESSING, UNDEFINED or ABORTED. Default is IDLE. When INC, COUNT or PERCENT are set the state is changed to PROCESSING. If the user pressed the Cancel button the state is changed to ABORTED, but check the CANCEL_CB callback for other options. If the state is set to UNDEFINED by the application the progress bar will display an undefined state animation (same as setting MARQUEE=Yes in IupProgressBar), to resume processing set the state attribute to PROCESSING.
DESCRIPTION | text description to be shown at the dialog.
PROGRESSHEIGHT | height in pixels of the progress bar. Default: 30 (since 3.21)
MINCLOCK | minimum time between counts to an actual screen update in milliseconds. So if each count increment is too fast this avoids updating the screen too often. Must at least has passed the minimum time for a screen update. Default: 250 (since 3.21)
MINPERCENT | minimum percent between counts to an actual screen update, when the minimum clock has not reached yet. So if each count increment is too fast, but the application would like to update the screen anyway after the percent of the total progress has passed this minimum value. So at least some screen updates will occur. Default: 10 (since 3.21)
Callbacks: | Supports all the IupDialog callbacks.
New callbacks: |
CANCEL_CB | Action generated when the user clicked on the Cancel button. function cancel_cb(Ihandle ih) ih: identifier of the element that activated the event. Returns: if different from IUP_CONTINUE then STATE will be changed to ABORTED, same behavior as if the callback does not exist. The returned value will also be returned in the "Cancel" button callback (since 3.21).
Example |
    --
    -- demo\pGUI\IupProgressDlg.exw
    --
    include pGUI.e

    Ihandln dlg

    function cancel_cb(Ihandle ih)
      integer ret = IupAlarm("Warning!", "Interrupt Processing?", "Yes", "No", NULL)
      if ret==1 then /* Yes Interrupt */
        IupExitLoop()
        return IUP_DEFAULT
      end if
      return IUP_CONTINUE
    end function

    function timer_cb(Ihandle /*ih*/)
        IupSetAttribute(dlg, "INC", NULL)
        if IupGetInt(dlg, "COUNT")==IupGetInt(dlg, "TOTALCOUNT") then
            IupHide(dlg)
            return IUP_CLOSE
        end if
        return IUP_DEFAULT
    end function

    IupOpen()

    dlg = IupProgressDlg()

    IupSetAttribute(dlg, "TITLE", "IupProgressDlg Test")
    IupSetAttribute(dlg, "DESCRIPTION", "Description first line\nSecond Line")
    --                              -- (Actually can have any number of lines).
    IupSetCallback(dlg, "CANCEL_CB", Icallback("cancel_cb"))
    IupSetAttribute(dlg, "TOTALCOUNT", "300")

    IupShowXY(dlg, IUP_CENTER, IUP_CENTER)

    Ihandle timer = IupTimer(Icallback("timer_cb"),50)

    if platform()!=JS then
        IupMainLoop()
        dlg = IupDestroy(dlg)
        IupClose()
    end if
Note that dlg has an Ihandln type for the benefit of IupDestroy(); IupProgressDlg() will throw a (catchable) exception rather than return NULL.
See Also: | IupProgressBar, IupDialog