Contents
Navigation
Home User Reference Other Resources


This class allows you to be notified about the events that occurred during the execution of a task performed by an instance of a object. You should adopt the new approach instead of the older (and deprecated) one based onto a passed to the instance.

If the component service in use and its property is set to true, the QTPlgComponentServiceControl class events will never be invoked. This is due to the fact that callbacks called from a background thread must be thread–safe and Real Studio events mechanism is not. In cases such as this, the background processes will send events to the main thread queue. If you want to monitor the status of the currently active background threads, you will need to implement a custom events handler in the application main thread. In practice, all you have to do is to use the class method to install your callback and, then, retrieve and propagate as appropriate to your needs the informations about the generated event brought to you by the callback. A detailed discussion about this topic is included into the documentation of the class method below. As the management of background threads if completely handled by the component service instance, even if you do not provide such a event handler, nevertheless the background mechanism will continue to work, but, of course, I will not be able to keep track of the status of the active threads.







(handler as memoryblock) as integer
if the current component service will do its work in background, this method allows you to provide to the class a custom event handler procedure to be notified about the status of the currently active background threads (if any). The handler parameter represents the pointer to the RealStudio method you want to use to dispatch status messages and must conform to the following prototype

MyBackTaskEventHandler(info as as )

The info parameter contains all of the informations needed to univocally identify an event generated by a thread. You can find about the kind of generated event inspecting the property of the object passed to you via the callback. Four kinds of events can be generated (their signatures are reported in parenthesis as four char code strings):
  • serviceStarted("THST"): this event is analogous to the class event; use the property of the info parameter to identify the thread instance that has generated the event
  • serviceDone("THED"): this event is analogous to the class event; just like the event above, use the property of the info parameter to identify the finished thread
  • serviceProgress("THPG"): this event is analogous to the class event; use the property to identify the thread instance and the property to retrieve the percentage of accomplished task
  • serviceError("THER"): this event is analogous to the class event; use the property of the info parameter to find about the code of the error occurred during the processing of data accomplished by the thread identified by
By this API you can retrieve the parameters associated to the generated event (see discussion above) and dispatch them as appropriate to your needs. Successive calls to this method will not produce any effect
returns 0 if the custom events handler has been installed successfully, otherwise an error code
this method is effective only for MacOSX
() as integer
use this method to remove a custom event handler previously installed. If no event handler was installed this method does nothing
returns 0 if the custom events handler has been removed successfully, otherwise an error code
this method is effective only for MacOSX

The QTPlgComponentServiceControl class constructors are called when you create a new instance of the class, while the ˜QTPlgComponentServiceControl 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.

The class provides you with the following initializer methods:

()
use this constructor version to create an instance of the class with all of the properties set to empty values. If you use this class directly on to the RealStudio IDE the default constructor will be automatically invoked

allows to get or set the component service currently in use. Note that the class stores just a reference to the object passed into this property; it is up to you to dispose of it when you have done. To remove the reference currently in use, simply set this property to nil

(uid as )
a task has began. The uid parameter specifies the service instance that has sent the event
(uid as )
a task has been successfully executed. The uid parameter specifies the service instance that has sent the event
(uid as , percentDone as double)
a task is in progress. The uid parameter specifies the service instance that has sent the event; the percenDone parameter is a value ranging between 0.0 and 1.0 that indicates the percentage of accomplished task
(uid as , err as integer)
an error has occurred during the execution of the task and it has been aborted. You should take appropriate actions to handle this situation