Reference for the Mosaic class Resources::ExternBitmap
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.
property bool Asynchronous = false;
The property 'Asynchronous' determines how this Extern Bitmap object should communicate with the extern bitmap loader. If this property is 'false', the Extern Bitmap object will wait until the extern bitmap loader has processed the request. This corresponds to a blocking mode.
If the property 'Asynchronous' is 'true', the Extern Bitmap object limits to kick off the extern bitmap loader to perform the loading operation. As soon as the bitmap contents are available, the extern bitmap loader notifies the Extern Bitmap object so it can pickup the bitmap. The Extern Bitmap object is acting non-blocking in such case.
method string GetInfo();
The method GetInfo() returns a string describing the loaded image. The string is provided by the extern bitmap loader just in the moment when the bitmap is loaded. The string content and its evaluation are application specific.
property string Name = "";
The property 'Name' stores a string identifying unambiguously an image file to load within this Extern Bitmap object. The object will thereupon represent the image content so it can be shown e.g. in an Image view. The usage of this property depends on your particular application case and it's up to you how you interpret the content of this property. For example:
Modification of this property at the runtime causes the Extern Bitmap object to load new image replacing the preceding contents of the Extern Bitmap object. However, as long as there are no new contents available, the Extern Bitmap object retains its old contents. If the loading operation failed, the Extern Bitmap object also retains its old content. If it is not desired, assign an empty string to Name before the right name is assigned to this property.
property slot OnError = null;
The property 'OnError' can refer to a slot method which will receive a signal as soon as the loading of the extern image contents has failed for whatever reason. The Extern Bitmap object remains empty thereupon.
property slot OnLoaded = null;
The property 'OnLoaded' can refer to a slot method which will receive a signal as soon as the Extern Bitmap object has successfully finalized the loading operation. The new image content is available now.
property slot OnUpdate = null;
The property 'OnUpdate' can refer to a slot method which will receive a signal when the content of the Extern Bitmap object has changed. Unlike OnLoaded it includes also the case of the Extern Bitmap object being cleaned up.
method void Reload();
The method Reload() triggers the Extern Bitmap object to reload the image file identified by the property Name. This method is useful if the image file content has changed at the runtime.
Please note, as long as no new contents are available, the Extern Bitmap object retains its old contents. If the loading operation failed, the Extern Bitmap object also retains its old content. If it is not desired, assign an empty string to Name. Then assign again the original value to Name. This triggers the loading operation while the Extern Bitmap object remains empty.