Reference for the Mosaic class Resources::ExternBitmap

Resources::ExternBitmap Asynchronous Name OnError OnLoaded OnUpdate GetInfo() Reload() Resources::Bitmap FrameDelay FrameSize NoOfFrames Core::Resource

The class Resources::ExternBitmap provides the functionality to load a bitmap from an extern image source dynamically at the runtime of the application. Bitmaps obtained in this manner can be used as regular resources, in particular they can be shown in all adequate views like Views::Image, Views::Wallpaper, Views::Frame, Views::WarpImage or Views::AttrText.

This class depends on an extern bitmap loader which is individual for each application case, target system and pixel format. It is thus up to you to provide such extern bitmap loader implementation. Depending on your application case, the extern bitmap loader can perform the loading operation in blocking mode or asynchrounously, non blocking. The mode is controlled for each Extern Bitmap object individually by intializing its property Asynchronous.

If you plan to support the blocking mode, you will need to implement following 'C' function and link it with the generated GUI application code:

XBitmap* EwLoadExternBitmap( XString aName );

When called the function has the job to open the image file (or any other image source) identified by the parameter aName, create a new Graphics Engine bitmap object and load the bitmap object with the content of the image. The parameter aName corresponds to the Extern Bitmap object's property Name. If the image content is not intended to be loaded from any file or data source but rendered at the runtime, EwLoadExternBitmap() should use the parameter aName to deduce what content should be rendered and fill the Graphics Engine bitmap object appropriately. In case the loading is failed, the function should abort, release all involved resources and return NULL.

In order to support the non-blocking mode, you will need to implement all following five 'C' functions and link them with the generated GUI application code:

XHandle EwStartExternBitmap( XString aName );

XBool EwProgressExternBitmap( XHandle aHandle );

XBitmap* EwFinishExternBitmap( XHandle aHandle );

void EwCancelExternBitmap( XHandle aHandle );

XString EwGetExternBitmapInfo( XHandle aHandle );

The function EwStartExternBitmap() is invoked by Extern Bitmap object to kick-off the non-blocking bitmap loading operation. For example, the function could start a thread or task responsable for loading an image file. The desired image content is identified by the value provided in the parameter aName - analog to the above described function EwLoadExternBitmap().

The function EwProgressExternBitmap() is invoked by Extern Bitmap object periodically to drive the loading operation and check its status. In this manner, the function can load and decode image contents in multiple, short steps. This is specially useful if your target system does not support parallel execution of threads or tasks. When implementing this function, please keep its execution time as short as possible to not block the GUI application.

With its return value, EwProgressExternBitmap() indicates the status of the loading operation. Your implementation should return 'true' if the loading is still in progress and 'false' if it is finished and the loaded bitmap can be obtained. Also, the function should return 'false' if the loading operation is failed for whatever reason. If the extern bitmap loader uses threads or tasks to perform the loading operation, the function should limit to test the work status of the threads/tasks and return 'false' when they are finished or failed with the loading operation.

The function EwFinishExternBitmap() is invoked by Extern Bitmap object when the bitmap loading is finished (indicated by the return value 'false' of the function EwProgressExternBitmap()). The implementation of the function should return a Graphics Engine bitmap object containing the loaded image contents and release all involved resources. In case the loading is failed, the function should abort, release all involved resources and return NULL.

The function EwCancelExternBitmap() is invoked by Extern Bitmap object to cancel the loading request initiated by the corresponding EwStartExternBitmap() invocation. The implementation of this function should, for example, stop all threads or tasks driving the load operation and release all involved resources.

The function EwGetExternBitmapInfo() is invoked by Extern Bitmap object shortly before invoking EwFinishExternBitmap(). The function can return a string with information describing the loaded image content or an empty string if such information is not available.

To track asynchronous operations, the function EwStartExternBitmap() has to allocate and initialize a data structure identifying the operation and return a pointer to this structure. Later, when one of the functions EwProgressExternBitmap(), EwFinishExternBitmap(), EwCancelExternBitmap() or EwGetExternBitmapInfo() is invoked, this value is passed in the function's parameter aHandle. The implementation of the function can thereupon access the data structure, check the progress of the loading operation, obtain the loaded bitmap or cancel the request. This permits multiple loading operations to be performed and managed simultanously at the same time.

Both invocations, EwFinishExternBitmap() and EwCancelExternBitmap() finalize the operation and should release all involved resources, incl. the data structure allocated originally in the function EwStartExternBitmap() and referred by the parameter aHandle.

If the content of the image file changes dynamically at the runtime, the Extern Bitmap object can be triggered to reload the image file by using its method Reload(). Please note, while loading new contents, Extern Bitmap object retains its old contents. This is also the case when the loading is failed. If it is required to clear the content of an Extern Bitmap object, assign an empty string to Name.

If there is an information string associated to the loaded image file, this string can be queried by using the method GetInfo(). Please note, the information string is available only when the property Asynchronous is configured with the value 'true'.

By using the properties OnLoaded, OnError and OnUpdate additional slot methods can be associated to the Extern Bitmap object to be signaled when the loading is finished, it is failed or the content of the object has changed.