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:
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 therefCon 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.
where:
percent : is a value indicating how far the operation has progressed. Its value is always between 0.0 and 1.0c :a reference to a RealBasic RectControlerr : 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
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.
(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
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
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
*/