### 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.

~IResourceLibrary

      public:
      virtual ~IResourceLibrary()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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.

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

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.

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

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.

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.

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

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

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.

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

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

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

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

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.

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

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

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

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

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

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None