// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page quick-images.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-design-qtquick-components

    \title Use images in UIs

    The \uicontrol Image component is used for adding images to the UI in several supported
    formats, including bitmap formats, such as PNG and JPEG, and vector graphics
    formats, such as SVG. To use any image files in your designs, you need to
    first add them to \l {Add assets}{Assets}:

    \list 1
        \li Select \uicontrol Assets > \imageplus.
        \li Select the image file, and then select \uicontrol Open.
        \li Select the location where the image will be saved in the
            \uicontrol {Add Resources} dialog.
        \li Select \uicontrol OK.
    \endlist

    Your image is now available in \uicontrol Assets.

    \image {qtquick-designer-image-type.png} {Image component in different views.}

    When you drag an image file from \uicontrol Assets to \uicontrol {Navigator}
    or the \uicontrol {2D} view, \QMLD automatically
    creates an instance of the Image component for you with the path to the
    image file set as the value of the \uicontrol Source field in
    \uicontrol Properties.

    To load images from a URL using a supported URL scheme, specify the URL
    in the \uicontrol Source field.

    You can use the \l {Border Image} component to display an image,
    such as a PNG file, as a border and a background. For more
    information about using border images to create buttons, see
    \l {Create scalable buttons and borders}.

    If you need to display animated images, such as GIFs, use the
    \l {Animated Image} component.

    \note Currently, the supported image formats include JPEG, JPG, PNG, SVG,
    HDR, KTX, BMP, TTF, TIFF, WEBP, and GIF.

    \section1 Image size

    \image {qtquick-designer-image-properties.png} {Image properties.}

    If the image \uicontrol Size is not specified, the size of the source
    image is used automatically.

    By default, explicitly setting the width and height of the component causes
    the image to be scaled to that size. To change this behavior, set the
    value of the \uicontrol {Fill mode} field. Images can be stretched, tiled,
    or scaled uniformly to the specified size with or without cropping. The
    \uicontrol Pad option means that the image is not transformed.

    \note If \uicontrol Clip is not selected, the component might
    paint outside its bounding rectangle even if the \uicontrol {Fill mode}
    is set to \uicontrol PreserveAspectCrop.

    Select \uicontrol Smooth to smoothly filter images when scaled
    or transformed. Smooth filtering gives better visual quality, but it may be
    slower on some hardware. If the image is displayed at its natural size,
    this property has no visual or performance effect.

    Select \uicontrol Mipmap to use mipmap filtering when scaling
    or transforming images. Mipmap filtering gives better visual quality when
    scaling down compared with smooth filtering, but it may come at a
    performance cost both when initializing the image and during rendering.

    Select \uicontrol {Auto transform} if the image should
    automatically apply image transformation metadata, such as EXIF orientation.

    \section1 Source size

    The \uicontrol {Source size} property specifies the scaled width and height
    of the full-frame image. Unlike the value of the \uicontrol Size property,
    which scales the painting of the image, this property sets the maximum
    number of pixels stored for the loaded image so that large images do not
    use more memory than necessary. This ensures the image in memory is no
    larger than the set source size, regardless of its set size.

    If the image's actual size is larger than the source size, the image is
    scaled down. If only one dimension of the size is set to greater than 0,
    the other dimension is set in proportion to preserve the source image's
    aspect ratio. The \uicontrol {Fill mode} is independent of this.

    If both the source size width and height are set, the image is scaled
    down to fit within the specified size maintaining the image's aspect ratio.
    However, if \uicontrol PreserveAspectCrop or \uicontrol PreserveAspectFit
    are used, the image is scaled to match the optimal size for cropping or
    fitting.

    If the source is an intrinsically scalable image (such as SVG), source size
    determines the size of the loaded image regardless of intrinsic size.
    Avoid changing the source size property dynamically because rendering an
    SVG is slow compared with rendering other image formats.

    If the source is a non-scalable image (such as JPEG), the loaded image will
    be no greater than the source size specifies. For some formats, the whole
    image will never actually be loaded into memory.

    \note Changing this property dynamically causes the image source to be
    reloaded, potentially even from the network, if it is not in the disk cache.
    Select \uicontrol Cache to cache the image.

    \section1 Image alignment

    You can align images horizontally and vertically in the
    \uicontrol {Alignment H} and \uicontrol {Alignment V}
    fields. By default, images are centered.

    Select \uicontrol Mirror to horizontally invert the image,
    effectively displaying a mirrored image.

    \section1 Performance

    By default, locally available images are loaded immediately, and the UI
    is blocked until loading is complete. If a large image is to be loaded,
    it may be preferable to load the image in a low priority thread, by
    selecting \uicontrol Asynchronous. If the image is obtained
    from a network rather than a local resource, it is automatically loaded
    asynchronously.

    Images are cached and shared internally, so if several images have the same
    \uicontrol Source, only one copy of the image will be loaded.

    \note Images are often the greatest user of memory in UIs. We recommended
    that you set the \uicontrol {Source size} of images that do not form a part
    of the UI. This is especially important for content that is loaded from
    external sources or provided by the user.

    \section1 Border Image

    The \uicontrol{Border Image} component extends the features of the
    \uicontrol Image component. It is used to create borders out of images by
    scaling or tiling parts
    of each image. A source image is broken into 9 regions that are scaled or
    tiled individually. The corner regions are not scaled at all, while the
    horizontal and vertical regions are scaled according to the values of the
    \uicontrol {Tile mode H} and \uicontrol {Tile mode V} field, or both.

    The \uicontrol Stretch option scales the image to fit the available area.
    The \uicontrol Repeat option tiles the image until there is no more space.
    To ensure that the last image is not cropped, select the \uicontrol Round
    option that scales the images down when necessary.

    Specify the regions of the image in the \uicontrol {Border left},
    \uicontrol {Border right}, \uicontrol {Border top}, and
    \uicontrol {Border bottom} fields. The regions describe
    the distance from each edge of the source image to use as a border.

    \image {qtquick-designer-border-image-properties.png} {Border Image properties.}

    \note You cannot change the \uicontrol {Source size} of a border image.

    For examples of using border images, see the documentation of the
    \l [QtQuick]{BorderImage} component.

    \section1 Animated Image

    The \uicontrol {Animated Image} component extends the features of the Image component,
    providing a way to play animations stored as images containing a series of
    frames, such as those stored in GIF files.

    Set the speed of the animation in the \uicontrol Speed field. The speed is
    measured in percentage of the original animated image speed. The default
    speed is 1.0, which means the original speed.

    \image qtquick-designer-animated-image-properties.png "Animated Image properties"

    To play the animation, select \uicontrol Playing.

    To pause the animation, select \imagepauseicon
    (\uicontrol Paused).

    When \uicontrol Cache is selected, every frame of the
    animation is cached. Clear the checkbox if you are playing a long
    or large animation and you want to conserve memory.

    If the image data comes from a sequential device (such as a socket),
    Animated Image can only loop if caching is enabled.

    For more information, watch the following video:

    \youtube DVWd_xMMgvg

    \section1 Summary of the image components

    The following table lists the components that you can use to add images.
    The \e Location column contains the tab name where you can find the
    component in \uicontrol Components. The \e {MCU support} column
    indicates which components are supported on MCUs.

    \table
    \header
        \li Icon
        \li Name
        \li Location
        \li MCU support
        \li Purpose
    \row
        \li \imageanimatedimageicon16
        \li \l [QtQuick]{AnimatedImage}{Animated Image}
        \li Default Components - Basic
        \li No
        \li An images that stores animations containing a series of frames,
            such as those stored in GIF files.
    \row
        \li \imageborderimageicon16
        \li \l [QtQuick]{BorderImage}{Border Image}
        \li Default Components - Basic
        \li Yes
        \li An image that is used as a border or background.
    \row
        \li \imageimageicon16
        \li \l [QtQuick]{Image}
        \li Default Components - Basic
        \li Yes
        \li An image in one of the supported formats, including bitmap formats
            such as PNG and JPEG and vector graphics formats such as SVG.
    \endtable

    \sa {Use UI components}{How to: Use UI components}, {Qt Quick UI design},
    {Designing Qt Quick UIs}
*/
