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

/*!
    \page creator-quick-ui-forms.html
    \previouspage creator-reference.html

    \ingroup creator-reference-ui-design-qtquick

    \title UI files

    \brief Limitations of UI files (.ui.qml).

    If you create \l{Create Qt Quick UI Prototypes}
    {Qt Quick UI Prototype projects} or switch between \QC and \QDS, your
    projects might contain UI files (\c .ui.qml). You should edit them in \QMLD
    or \QDS only.

    By default, \QC opens UI files in the \uicontrol Design mode. To open them
    with \QDS, select \uicontrol {Open With} > \uicontrol {\QDS} in the context
    menu in the \uicontrol {File System} or \uicontrol {Projects} view.

    The following features are not supported in \c .ui.qml files:

    \list
        \li JavaScript blocks
        \li Other bindings than pure expressions
        \li Signal handlers
        \li States in other components than the root component
        \li Root components that are not derived from \l QQuickItem or
            \l [QML]{Item}
        \li Referencing the parent of the root component
    \endlist

    The following components are not supported:

    \list
        \li Behavior
        \li Binding
        \li Canvas
        \li Shader Effect
        \li Timer
        \li Transform
    \endlist

    \section1 Supported methods

    \QC supports most JavaScript functions that are supported by the QML
    engine, as well as a subset of Qt QML methods.

    This section lists the functions that you can use in \c .ui.qml files.

    \section2 JavaScript functions

    As a rule of thumb, \e {pure functions} are supported. They only depend on
    and modify states of parameters that are within their scope, and therefore
    always return the same results when given the same parameters. This makes
    it possible to convert and reformat property bindings without breaking the
    \c .ui.qml files.

    The following JavaScript functions are supported:

    \list
        \li \c charAt()
        \li \c charCodeAt()
        \li \c concat()
        \li \c endsWith()
        \li \c includes()
        \li \c indexOf()
        \li \c isFinite()
        \li \c isNaN()
        \li \c lastIndexOf()
        \li \c substring()
        \li \c toExponential()
        \li \c toFixed()
        \li \c toLocaleLowerCase()
        \li \c toLocaleString
        \li \c toLocaleUpperCase()
        \li \c toLowerCase()
        \li \c toPrecision()
        \li \c toString()
        \li \c toUpperCase()
        \li \c valueOf()
    \endlist

    In addition, all functions of the \c Math and \c Date objects are supported.

    For more information, see \l{List of JavaScript Objects and Functions}.

    \section2 Qt QML methods

    \QC supports color methods, helper methods for creating objects of
    specific data types, and translation methods.

    The following color methods are supported:

    \list
        \li \l{Qt::darker()}{Qt.darker()}
        \li \l{Qt::hsla()}{Qt.hsla()}
        \li \l{Qt::hsva()}{Qt.hsva()}
        \li \l{Qt::lighter()}{Qt.lighter()}
        \li \l{Qt::rgba()}{Qt.rgba()}
        \li \l{Qt::tint()}{Qt.tint()}
    \endlist

    The following helper methods are supported:

    \list
        \li \l{Qt::formatDate()}{Qt.formatDate()}
        \li \l{Qt::formatDateTime()}{Qt.formatDateTime()}
        \li \l{Qt::formatTime()}{Qt.formatTime()}
        \li \l{Qt::matrix4x4()}{Qt.matrix4x4()}
        \li \l{Qt::point()}{Qt.point()}
        \li \l{Qt::quaternion()}{Qt.quaternion()}
        \li \l{Qt::rect()}{Qt.rect()}
        \li \l{Qt::size()}{Qt.size()}
        \li \l{Qt::vector2d()}{Qt.vector2d()}
        \li \l{Qt::vector3d()}{Qt.vector3d()}
        \li \l{Qt::vector4d()}{Qt.vector4d()}
    \endlist

    The following translation methods are supported:

    \list
        \li \l{Qt::}{qsTr()}
        \li \l{Qt::}{qsTranslate()}
        \li \l{Qt::}{QT_TRANSLATE_NOOP()}
        \li \l{Qt::}{qsTrId()}
        \li \l{Qt::}{QT_TRID_NOOP()}
        \li \l{Qt::}{QT_TR_NOOP()}
    \endlist

    \note Do not mix translation methods in a UI file.

    For more information about using the methods, see \l{Qt QML Methods}.

    \section1 Using UI files

    Edit the UI files in the \uicontrol Design mode. To use components in code,
    export them as properties:

    \code
    Item {
        width: 640
        height: 480

        property alias button: button

        Button {
            anchors.centerIn: parent
            id: button
            text: qsTr("Press Me")
        }
    }
    \endcode

    The property alias exports the button to the code that uses the form.
    You can use the \inlineimage {icons/alias.png} {Export}
    (\uicontrol Export) button in \uicontrol {Navigator} to export a component
    as a property:

    \image {qmldesigner-export-item.png} {Navigator view.}

    In the UI file where the component is used, you can use the \c button
    property alias to implement signal handlers, for example. In the
    following code snippet, the UI file is called \c MainForm.ui.qml:

    \code
    MainForm {
        anchors.fill: parent
        button.onClicked: messageDialog.show(qsTr("Button pressed"))
    }
    \endcode

    You can also assign properties or define behavior or transitions.

    To move from the \uicontrol {2D} or \uicontrol {Navigator} view directly to
    the implementation of a component in the \c .qml
    file, right-click the component and select \uicontrol {Go to Implementation}
    in the context menu.

    \sa {Design Qt Quick UIs}{How to: Design Qt Quick UIs}, {Qt Quick UI design},
    {Designing Qt Quick UIs}

*/
