uiimage
Create image component
Description
im = uiimage
creates an image component in a new figure and returns
the Image
object. MATLAB® calls the uifigure
function to create the new figure.
Use uiimage
to display a picture, icon, or logo in your app.
im = uiimage(___,
specifies Name,Value
)Image
properties using one or more
Name,Value
arguments. Use this option with any of the input argument
combinations in the previous syntaxes.
Examples
Display a Picture
Create an image component within a figure. The default image displays.
fig = uifigure; im = uiimage(fig);
Now, add a picture to the image component.
im.ImageSource = "peppers.png";
Display Animated GIF with Letterboxing
Create an image component that displays an animated GIF using the actual size of the image.
fig = uifigure; im = uiimage(fig,"ImageSource","questions.gif"); im.ScaleMethod = "none";
Now, scale the image so that it fits within the default component area, preserving aspect ratio and without clipping. Then, apply a black background to create the appearance of letterboxing (black bars above and below the image).
im.ScaleMethod = "scaledown"; im.BackgroundColor = "black";
Configure Image to Open Link When Clicked
Create an image and specify a URL that opens in a new browser tab when you click the image. Specify a tooltip that appears when you point to the image.
fig = uifigure; im = uiimage(fig); im.ImageSource = "ngc6543a.jpg"; im.URL = "https://www.mathworks.com/"; im.Tooltip = "Go to www.mathworks.com";
Before R2022b: Use the ImageClickedFcn
property instead of the URL
property and create a callback using a
function
handle.im.ImageClickedFcn = @(src,event)web("https://www.mathworks.com/");
Input Arguments
parent
— Parent container
Figure
object (default) | Tab
object | Panel
object | ButtonGroup
object | GridLayout
object
Parent container, specified as a Figure
object created using the uifigure
function or one of its child
containers: Tab
, Panel
, ButtonGroup
, or GridLayout
. If you do not specify a parent container, MATLAB calls the uifigure
function to create a new Figure
object that serves as the parent container.
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: im = uiimage('ScaleMethod','none')
Note
The properties listed here are only a subset. For a complete list, see Image
.
ImageSource
— Image source or file
' ' (default) | file path | m
-by-n
-by-3 truecolor image array
Image source or file, specified as a file path or an
m
-by-n
-by-3 truecolor image array. Supported
image formats include JPEG, PNG, GIF, SVG, or
m
-by-n
-by-3 truecolor image array.
For more information on truecolor image arrays, see Working with Image Types in MATLAB.
Example: im =
uiimage('ImageSource','peppers.png');
Example: im.ImageSource = 'C:\TEMP\ngc6543a.jpg';
ScaleMethod
— Image scaling method
'fit'
(default) | 'fill'
| 'none'
| 'scaledown'
| 'scaleup'
| 'stretch'
Image scaling method, specified as one of the values listed in the table. Use this name-value pair argument to specify how you want your image to render within the component area.
The table also demonstrates each scale method with an example image. In the rendered image
examples, the BackgroundColor
property of the image component has been
set to 'magenta'
. The scaling behavior of SVG image files may vary based on
how the file is defined.
Value | Description | Example | Scales Up | Scales Down | Maintains Aspect Ratio | Clips Image | |
---|---|---|---|---|---|---|---|
Original Image | Rendered Image | ||||||
'fit' | Scales in any direction to display the image within the component area, and maintains aspect ratio without clipping. |
|
| Yes | Yes | Yes | No |
'fill' | Scales in any direction to fill the component area, maintaining aspect ratio and clipping if necessary. |
|
| Yes | Yes | Yes | Yes |
'none' | Uses the actual size of the image and maintains aspect ratio. If the component area is smaller than the image, the image is clipped. |
|
| No | No | Yes | Yes |
'scaledown' | Scales down and maintains aspect ratio without clipping. If the original image is larger than the
component area, the image scales down and renders as if the |
|
| No | Yes | Yes | No |
'scaleup' | Scales up and maintains aspect ratio with clipping. If the original image is smaller than the
component area, the image scales up and renders as if the |
|
| Yes | No | Yes | Yes |
'stretch' | Scales in any direction to fill the component area, without maintaining the aspect ratio and without clipping. |
|
| Yes | Yes | No | No |
URL
— Image hyperlink URL
''
(default) | character vector | string scalar
Image hyperlink URL, specified as a character vector or string scalar. When a user clicks the image, the web address specified by the URL opens in a new browser tab. If the user is running the app in a browser using MATLAB Online™ or as a web app, the new tab opens in the current browser. Otherwise, the new tab opens in the default browser on the user's system.
ImageClickedFcn
— Image clicked callback
' ' (default) | function handle | cell array | character vector
Image clicked callback, specified as one of these values:
A function handle.
A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.
A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.
This callback executes when the user clicks the image in the app. If you specify a
link to open using the URL
property, the callback executes after
that link opens.
This callback function can access specific information about the user's
interaction with the image. MATLAB passes this information in an ImageClickedData
object
as the second argument to your callback function. In App Designer, the argument is
called event
. You can query the object properties using dot
notation. For example, event.Source
returns the
Image
object that the user is interacting with to trigger the
callback. The ImageClickedData
object is not available to callback
functions specified as character vectors.
The following table lists the properties of the
ImageClickedData
object.
Property | Value |
---|---|
EventName | 'ImageClicked' |
Source | Component executing the callback |
For more information about writing callbacks, see Callbacks in App Designer.
Position
— Location and size of image component
[100 100 100 100]
(default) | [left bottom width height]
Location and size of image component relative to the parent, specified as a four element vector of the form [left bottom width height]
. This table describes each element in the vector.
Element | Description |
---|---|
left | Distance from the inner left edge of the parent container to the outer left edge of the image component |
bottom | Distance from the inner bottom edge of the parent container to the outer bottom edge of the image component |
width | Distance between the right and left outer edges of the image component |
height | Distance between the top and bottom outer edges of the image component |
The Position
values are relative to the drawable area of the parent container. The drawable area is the area inside the borders of the container and does not include the area occupied by decorations such as a menu bar or title.
All measurements are in pixel units.
Version History
Introduced in R2019aR2023a: Specify image alt text
Specify the AltText
property to provide a description of the image.
Screen readers use this text to describe the image when an app user navigates through your
app.
R2022b: Create an image hyperlink using the URL
property
To open a web address when a user clicks an image in your app, specify the image
URL
property.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)