.. highlightlang:: us

.. index:: AppProgressDialog

.. _appprogressdialog:

AppProgressDialog
=================

.. us.tag  AppProgressDialog NOTREADYENGLISH App Toolbar New5401

:ref:`AppProgressDialog` creates a dialog box with a progress control and a 
Cancel button.

.. function::  bool = AppProgressDialog()
               bool = AppProgressDialog(nUpper)
               bool = AppProgressDialog(nUpper, ssTitle)

.. us.return

**Return Value**

If the function succeeds, the return value is TRUE (1); otherwise it is FALSE (0).

.. us.params

**Parameters**

.. uparam:: nUpper

   Default value is 100.

.. uparam:: ssTitle

   Default value "Progress".

.. us.comment

**Comment**

Above the progress control a text control with two lines is displayed. The text
can be set with the :ref:`AppSetStatusBarText` after the control has been 
created.

Beginning with UniPlot R2015.8 calls of :ref:`AppProgressDialog` and
:ref:`AppProgressCreate` can be nested.

Example: If you have a function that displays the progress for the import of a data
file and you want to invoke this function for 5 data files and show the overall 
progress in the progress bar, 20 % of the progress of each date file will be 
displayed in the progress bar. See example.

.. image:: S:/uniplot-obj/images/ProgressDialog.*

.. us.example

**Example**

::

   def SubAppProgressDialog()
   {
      nStep = 10;
      AppProgressDialog(nStep);
      for (i in 1:nStep) {
          AppSetStatusBarText(sprintf("Step: %d", i));
          bRet = AppProgressStepIt();
          if (!bRet) {
             return FALSE; // cancel
          }
          AppSleep(50); // Simulate some work
      }
      AppProgressDestroy();
      return TRUE;
   }

   def TestAppProgressDialog()
   {
       nStep = 5
       AppProgressDialog(nStep, "Import Data");
       for (i in 1:nStep) {
           
           bRet = SubAppProgressDialog(); 
           if (!bRet) {
               return FALSE; // cancel
           }

           bRet = AppProgressStepIt(); 
           if (!bRet) {
               return FALSE; // cancel
           }
           AppSetStatusBarText(sprintf("Step: %d", i));
           AppSleep(50); // Simulate some work
       }
       AppProgressDestroy()
   }

   TestAppProgressDialog()

   TestAppProgressDialog()

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2015.8
     - Progress bar with stack support.
   * - R2012.1 (5.40.1)
     - New.

.. seealso::
   :ref:`overview-application-object`,
   :ref:`AppProgressStepIt`,
   :ref:`AppProgressDestroy`,
   :ref:`AppProgressCreate`,
   :ref:`ShowWaitCursor`,
   :ref:`AppSetStatusBarText`

:sub:`id-796429`