Contents
Navigation
Home User Reference Other Resources


The QTPlgProgressCallback class allows developers to give feedback to users about the progress of an executing task. You will find that many QTPlugin classes have a property that require instances of this class to be set.







The QTPlgProgressCallback class constructors are called when you create a new instance of the class, while the ˜QTPlgProgressCallback class destructor, is called automatically when the class is no more in use. Also, you can invoke the class destructor by setting the instance of the class to nil.
Once a new class instance is returned, it is good practice to check the class property to be sure that the new object can be used. A QTPlgProgressCallback object is valid if you have passed to the instance of the class a valid callback procedure (see for details). As, when creating an instance of this class by using the , the callback procedure held by the class instance is set to nil, then the class property will be set to false; in this case, it is lecit to continue to use the class. Though, the instance of the class should be valid if you are going to use it to setup the callback property of some other class.

The class provides you with the following initializer methods:
()
This is the default constructor. Both the callback procedure and the control references are set to nil. You can either set up or change these parameters later using the class method
(other as QTPlgProgressCallback)
This is the copy constructor. The properties of the object to be copied will be used to initialize the new class instance properties
(proc as memoryblock, refCon as RectControl)
The callback procedure is set via the proc parameter that must be a pointer to a RealBasic global method defined as
Sub Func(percent as double, c as rectControl,err as integer)

where:
  • percent: is a value indicating how far the operation has progressed. Its value is always between 0.0 and 1.0
  • c:a reference to a RealBasic RectControl
  • err: an error code (0=no error)

You can get a pointer to this method by using the addressOf RealBasic operator; of course, you can name your function and parameters in any way makes sense for you. Furthermore, you can instructs the class to store a reference to a RealBasic RectControl object by using the refCon parameter; everytime the callback will be invoked, the class will set the c parameter of your RealBasic global method to this reference so that you can use it as you like it. If you are not interested in, simply set the refCon parameter to nil.
shows the implementation of a simple RealBasic callback procedure; shows how to create an instance of the class setting up its callback procedure using the Realbasic method defined above and notifying it that a ProgressBar control will be the receiver of the progress event.

(proc as memoryblock, refCon as RectControl)
this method allows you to specify, using the proc parameter,the RealBasic global method you want to be called and an optional reference to a control, the refCon parameter, that you want to get back when the QTPlugin process will invoke the callback. For more details see the section above.
returns none. Check the class property for errors.
(percent as double, [err as integer=0])
use this method to force the class instance to invoke the callback routine specified. This provides you with a simple way to build a progress callback mechanism that works within the Realbasic IDE
returns none. Check the class property for errors.


Sub QTPlg_ProgressCallback(percent as double, pbar as ProgressBar,err as integer)

if err<>0 then
msgBox str(err)
return
elseif pbar=nil then
return
else
pBar.value=percent*100
pBar.refresh
end if

End Sub
/*
supposing that you have a progress bar control named pBar somewhere
*/
dim pCback as new QTPlgProgressCallback( addressOf QTPlg_ProgressCallback,pBar)