14

IupProgressDlg

@serial = 932

dialog

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.

Include

iup.e

Namespace

iup

Signature

public function IupProgressDlg()

Creation

Returns: the identifier of the created element, or NULL if an error occurs.

Attribute

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.

TITLE: Dialog title.

Other attributes were set to values different than the default value:

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.

Callback

Supports all the IupDialog callbacks.

New callbacks.

CANCEL_CB: Action generated when the user clicked on the Cancel button. int function(Ihandle* ih); [in C] elem:cancel_cb() -> (ret: number) [in Lua]

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.

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.

Example

incomplete, partly functioning, uses a timer to simulate progress

include iup/iup.e  
 
IupOpen(NULL)  
  
function cancel_cb( atom ih)  
  
  atom ret = IupAlarm("Warning!", "Interrupt Processing?", "Yes", "No", NULL)  
  if equal(ret, 1) then /* Yes Interrupt */  
  
    IupExitLoop()  
    return IUP_DEFAULT  
  end if  
  
  return IUP_CONTINUE  
end function  
  
-- ...  
atom dlg = IupProgressDlg()  
atom timer1 =IupTimer() 
IupSetAttribute(timer1,"TIME","30") 
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")  
 
IupSetCallback(timer1,"ACTION_CB",Icallback("update_progress")) 
IupSetAttribute(timer1,"RUN","Yes") 
IupShowXY(dlg, IUP_CENTER, IUP_CENTER)  
 
--...  
  
-- Called from Timer Callback to make it work 
function update_progress( atom ih) -- ih is here the timer, not usable for updating the dialog 
   
  IupSetAttribute(dlg, "INC", NULL)  
 
  -- This is just an example, the application can control the loop in other ways  
  if equal(IupGetInt(dlg, "COUNT"), IupGetInt(dlg, "TOTALCOUNT")) then  
  
    IupHide(dlg)  
    return 0  
  end if  
  
  return 1  
end function  
  
IupMainLoop()  
IupClose()  

See Also