hiLoadImageFile

hiLoadImageFile(
t_fileName
x_width
x_height
)
=> l_hiImage / nil

Description

Loads an image file of any format, such as PNG, and returns the image in a format that can be used with hi functions that accept icons. If t_fileName is a relative path, the Cadence Search File mechanism (CSF) is used to search for the file.

Multiple resolutions of the icon are loaded, if found. The appropriate resolution is used when the icon is used.

This function provides you the ability to add your own images (icons) for custom toolbars, menus, and forms. You can place these icons in a subdirectory of your home directory. Similarly, central groups can provide icons for your entire site in a different location. Any icons you provide must be placed in an icons/16x16, icons/24x24, icons/32x32, or icons/48x48 subdirectory of a directory found by CSF. These directories should represent the resolution of the image files in them.

Follow these guidelines when you create icons:

• While any format supported by Qt is supported, PNG is preferred.
• Limit icons to 256 color.
• Use a consistent icon palette.

To this point, the above use description is identical to that of hiLoadIconFile. However if the file being referred to has changed on disk, a new image referring to the updated image is returned, rather than the cached image that is returned by hiLoadIconFile.

The hiLoadIconFile command returns the most recently cached version of a file, although multiple calls to hiLoadIconFile returns the same value, even if the file has changed on disk, if hiLoadImageFile is called for this same icon, and it has changed on disk, then the next call to hiLoadIconFile returns the newly-cached version, not the original version.

The hiLoadIconFile command always return the cached version of an icon for performance reasons (the filesystem search for an icon should only occur once during the initial call to hiLoadIconFile). Alternatively, hiLoadImageFile searches for an updated version of the icon upon each invocation. It should therefore only be used in cases where the image file may change during the lifetime of the program, and it is desirable to always have the most recent version.

The most common use then of hiLoadImageFile is to load thumbnail images for cellviews, as these are typically updated when a view is saved, and therefore changes during the lifetime of the program. Displaying an incorrect thumbnail image may be misleading, hence it is desirable to call hiLoadImageFile to check for updates, rather than always using the original image returned by hiLoadIconFile.

Unless there is a good reason to perform such filesystem checks, you should use hiLoadIconFile in order to avoid repeated checks.

Arguments

t_fileName	The name of the image file to load. If t_fileName is an absolute path (starting with /), then the file is loaded directly. Only a single resolution is available in this case. If t_fileName is a relative path, then CSF rules are used to search for all resolutions of the file. For each location in your setup.loc file, the following subdirectories are searched. The names of these subdirectories represent the resolution of the image files in them. icons/16x16 icons/24x24 icons/32x32 icons/48x48 Whichever resolutions are found are loaded into the image. When the image is used, the appropriate resolution is used.
x_width	The desired width of the image. The image that is returned is not sized to the width and height specified; these values are added to the return value of this function and applied when the icon is used.
x_height	The desired height of the image. The image that is returned is not sized to the width and height specified; these values are added to the return value of this function and applied when the image is used.

Values Returned

l_hiImage	The image handle, which can be used with any user interface  function that accepts icons. l_hiImage is of the following form: list(handle width height)
nil	t_fileName is not found or there was an error in loading it.

Examples

Loads the thumbnail for myLib/myCell/myView into an icon:

myView = ddGetObj( myLib myCell myView)

hiLoadImageFile( sprintf(nil "%s/%s" ddGetObjReadPath(myView) hiGetThumbnailFilename())) 64 64)

Related Topics

Icon Functions

hiLoadIconFile

hiLoadImageFile

hiLoadIconData

hiSaveIconData

hiStringToIcon

hiMatchColorByName

Return to top