Returns the image object associated with the specified name.
- macOS 10.0+
The name associated with the desired image. This can be a name you assigned to the image or the name of an image file in your app bundle.
NSImage object associated with the specified name or
nil if no such image was found.
This method searches for named images in several places, returning the first image it finds matching the given name. The order of the search is as follows:
Search for an object whose name was set explicitly using the
setmethod and currently resides in the image cache.
Search the Application Kit framework for a shared image with the specified name.
When looking for files in the app bundle, it is better (but not required) to include the filename extension in the
name parameter. When naming an image with the
set method, it is convention not to include filename extensions in the names you specify. That way, you can easily distinguish between images you have named explicitly and those you want to load from the app's bundle.
One particularly useful image you can retrieve is your app's icon. This image is set by Cocoa automatically and accessible using the
NSImage constant. Icons for other apps can be obtained through the use of methods declared in the
NSWorkspace class. You can also retrieve many of the standard system images using Cocoa defined constants; for more information, see the Image Template Constants, Sharing Permissions Named Images, System Entity Images, Toolbar Named Images, and View Type Template Images sections for applicable constants.
If an app is linked on macOS 10.5 or later, images requested using this method and whose name ends in the word “Template” are automatically marked as template images.
NSImage class may cache a reference to the returned image object for performance in some cases. However, the class holds onto cached objects only while the object exists. If all strong references to the image are subsequently removed, the object may be quietly removed from the cache. Thus, if you plan to hold onto a returned image object, you must maintain a strong reference to it like you would any Cocoa object. You can clear an image object from the cache explicitly by calling the object’s
set method and specifying
nil for the image name.