IResourceLibrary

The IResourceLibrary class loads resources, such as strings, menus, and bitmaps, from an application's executable file. Use the IDynamicLinkLibrary class to load resources that are stored in a dynamic link library.

Typically, you do not need to use this class as most classes in Open Class Library that require resources, provide functions that accept an IResourceId and load the resources from the resource file themselves.

To obtain either the Open Class Library's resource library or the default user resource library, call ICurrentApplication::resourceLibrary or ICurrentApplication::userResourceLibrary, respectively.


IResourceLibrary - Member Functions and Data by Group

Constructors & Destructor

Use these members to construct, copy, assign, and destruct objects of this class. You can construct objects of this class by using the default constructor, which does not accept any parameters, or by using the copy constructor to copy one resource library to another.


[view class]
~IResourceLibrary
public:
virtual ~IResourceLibrary()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IResourceLibrary


Overload 1
public:
IResourceLibrary(const IResourceLibrary& resLibrary)

resourceLibrary
Reference to an existing resource library object.

Creates a resource library object using a reference to an existing resource library object. This is commonly known as a copy constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IResourceLibrary()

Creates a resource library object using this, the default constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
public:
IResourceLibrary& operator =( const IResourceLibrary& resLibrary )

Assigns the member data of an object of this class to another object of this class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Diagnostics

Use these members for diagnostic purposes. They return an IString representation of an object of this class.


[view class]
asDebugInfo
public:
virtual IString asDebugInfo() const

Provides debugging information about the class object. It returns a string that contains the file name of the resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asString
public:
virtual IString asString() const

Provides textual information about the class object. It returns a string that contains the file name of the resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Resource Information

Use these members to query general resource information.


[view class]
fileName
public:
virtual IString fileName() const

Returns the fully qualified file name of the resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handle
public:
virtual IModuleHandle handle() const

Returns the handle to the resource library that is used to load the resources. IResourceLibrary objects always return 0 as the handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

This is always 0 for an IResourceLibrary object.


[view class]
isOpen
public:
virtual bool isOpen() const

Returns the open state of the resource file. IResourceLibrary objects always return true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Resource Loading

Use these members to load specific resources from a resource file.


[view class]
loadAccelTable
public:
virtual IAccelTblHandle loadAccelTable( unsigned long accelTableId ) const

Loads an accelerator table from a resource file.

accelTableId
Unsigned long value that represents the accelerator table identifier.

Exception

IAccessError The accelerator table was not loaded. The accelerator table identifier may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
loadBitmap

Loads a bitmap from a resource file.

If the cached argument is true, the bitmap is reference-counted. Therefore, if multiple requests are made for the bitmap, the reference count is incremented and the same copy of the bitmap is returned. When all of the references to the bitmap are deleted, the Open Class Library deletes the bitmap.

If you set the cached argument to false, IResourceLibrary creates a new copy of the bitmap. It is your responsibility to delete bitmaps created in this manner.


Overload 1
public:
virtual IBitmapHandle loadBitmap( unsigned long bitmapId, bool cached = true ) const

bitmapId
Unsigned long value that represents the bitmap identifier.
cached
A boolean value that determines caching.

Exception

IAccessError The bitmap was not loaded. The bitmap identifier may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IBitmapHandle loadBitmap( unsigned long bitmapId, const ISize& bitmapSize, bool cached = true ) const

bitmapId
Unsigned long value that represents the bitmap identifier.
bitmapSize
Reference to a size object that determines at which size the bitmap is loaded.
cached
A boolean value that determines caching.

Use this version of the function if you want to specify the size at which the bitmap is loaded.

Exception

IAccessError The bitmap was not loaded. The bitmap identifier may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
loadDialog
public:
virtual IWindowHandle loadDialog( unsigned long dialogId, IWindow* dialogParent, IWindow* dialogOwner, IWinProc* dialogProcedure, void* dialogCreateParameters ) const

Loads a dialog resource with the specified parent and owner windows.

You normally load dialog windows by creating IFrameWindow objects with an IFrameWindow::FrameSource of IFrameWindow::dialogWindow.

Exception

IAccessError The dialog was not loaded. The dialog identifier, parent, owner, procedure, or create parameters may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

AIX does not support dialogs.


[view class]
loadHelpTable
public:
virtual IResourceLibrary& loadHelpTable( IWindow* helpInstance, unsigned long helpTableId ) const

Loads a help table from a resource file. The IHelpWindow class provides information on help windows.

Exception

IAccessError The help table was not loaded. The help table identifier or the help table instance may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
loadIcon
public:
virtual IPointerHandle loadIcon( unsigned long iconId, bool cached = true ) const

Loads an icon from a resource file.

If the cached argument is true, the icon is reference-counted. Therefore, if multiple requests are made for the icon, the reference count is incremented and the same copy of the icon is used. When all of the references to the icon are removed, the Open Class Library deletes the icon.

If you set the cached argument to false, IResourceLibrary creates a new copy of the icon. It is your responsibility to delete icons created in this manner.

Exception

IAccessError The icon was not loaded. The icon identifier may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
loadMenu

Loads a menu resource from a resource file.


Overload 1
public:
virtual void loadMenu( unsigned long menuId, const IWindowHandle& menuHandle, IMenu* parentMenu ) const

menuId
Unsigned long value that represents the identifier of the menu resource.
menuHandle
Reference to the handle of the menu window.
parentMenu
Pointer to a menu object that is the menu's parent.

Exception

IInvalidParameter The parentMenu was 0.
IAccessError The menu was not loaded. The menu identifier or the menu handle may be invalid.

Supported Platforms

Windows OS/2 AIX
No No Yes

Portability Considerations

To achieve portable code, you should use a unique ID value for each item in a given menu. This is because the UNIX implementation for loading menus from a resource menu template requires unique IDs on, for example, each submenu item even though you may not use them yourself.


Overload 2
public:
virtual IMenuHandle loadMenu( unsigned long menuId, IWindow* menuOwner ) const

menuId
Unsigned long value that represents the menu identifier.
menuOwner
Pointer to a window object that is the menu's owner.

Exception

IAccessError The menu was not loaded. The menu identifier or the menu owner may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
loadMessage
public:
virtual IString loadMessage(unsigned long messageId) const

Loads a message resource from a resource file using the specified message identifier.

Exception

IAccessError The message string was not loaded. The message identifier may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
loadPointer
public:
virtual IPointerHandle loadPointer( unsigned long iconId, bool cached = true ) const

Loads a pointer with the specified resource identifier from a resource file.

If the cached argument is true, the pointer is reference-counted. Therefore, if multiple requests are made for the pointer, the reference count is incremented and the same copy of the pointer is used. When all of the references to the pointer are removed, the Open Class Library deletes the icon.

If you set the cached argument to false, IResourceLibrary creates a new copy of the pointer.

It is your responsibility to delete pointers created in this manner.

Calling this function is the same as calling IResourceLibrary::loadIcon.

Exception

IAccessError The pointer was not loaded. The icon identifier may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

On the OS/2 and Windows operating systems, this function is the same as calling loadIcon. On Motif, the pointer created via this function is a single-plane image which is suitable for use as a cursor.


[view class]
loadString
public:
virtual IString loadString(unsigned long stringId) const

Loads a string resource from a resource file using the specified string identifier.

Exception

IAccessError The string was not loaded. The string identifier may be invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
tryToLoadBitmap

Attempts to load a bitmap from a resource file. If this function cannot load the bitmap, it returns an IBitmapHandle with a 0 handle value rather than throwing an exception.

If the cached argument is true, the bitmap is reference-counted. Therefore, if multiple requests are made for the bitmap, the reference count is incremented and the same copy of the bitmap is used. When all of the references to the bitmap are deleted, the Open Class Library deletes the bitmap.

If you set the cached argument to false, IResourceLibrary creates a new copy of the bitmap. It is your responsibility to delete bitmaps created in this manner.


Overload 1
public:
virtual IBitmapHandle tryToLoadBitmap( unsigned long bitmapId, const ISize& bitmapSize, bool cached = true ) const

bitmapId
Unsigned long value that represents the bitmap identifier.
bitmapSize
Reference to a size object that determines at which size the bitmap is loaded.
cached
A boolean value that determines caching.

Use this version of the function if you want to specify the size at which the bitmap is loaded.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IBitmapHandle tryToLoadBitmap( unsigned long bitmapId, bool cached = true ) const

bitmapId
Unsigned long value that represents the bitmap identifier.
cached
A boolean value that determines caching.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
tryToLoadIcon
public:
virtual IPointerHandle tryToLoadIcon( unsigned long iconId, bool cached = true ) const

Attempts to load an icon from a resource file. If this function cannot load the icon, it returns an IPointerHandle with a 0 handle value rather than throwing an exception.

If the cached argument is true, the icon is reference-counted. Therefore, if multiple requests are made for the icon, the reference count is incremented and the same copy of the icon is used. When all of the references to the icon are deleted, the Open Class Library deletes the icon.

If you set the cached argument to false, IResourceLibrary creates a new copy of the icon. It is your responsibility to delete icons created in this manner.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
tryToLoadMessage
public:
virtual IString tryToLoadMessage( unsigned long messageId ) const

Attempts to load a message resource from a resource file. If this function cannot load the message, it returns an empty IString rather than throwing an exception.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
tryToLoadPointer
public:
virtual IPointerHandle tryToLoadPointer( unsigned long iconId, bool cached = true ) const

Attempts to load a pointer from a resource file. If this function cannot load the icon, it returns an IPointerHandle with a 0 handle value rather than throwing an exception.

If the cached argument is true, the icon is reference-counted. Therefore, if multiple requests are made for the icon, the reference count is incremented and the same copy of the icon is used. When all of the references to the icon are deleted, the Open Class Library deletes the icon.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
tryToLoadString
public:
virtual IString tryToLoadString( unsigned long stringId ) const

Attempts to load a string resource from a resource file. If this function cannot load the string, it returns an empty IString rather than throwing an exception.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resourceAddress
protected:
virtual void* resourceAddress() const

This is an internal use only function used to load resources on the Motif platform.

Supported Platforms

Windows OS/2 AIX
No No Yes


IResourceLibrary - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data