---@meta Gui
local gui = {}

---The base class of all ui related classes.
---@class Object
gui.Object = {}

---Returns whether the gui object is still valid (not deleted).
---@return boolean isValid
function gui.Object:isValid() end

---The base class of all gui layout classes.
---@class Layout : Object
gui.Layout = {}

function gui.Layout:show() end

---The base class of all widget classes, an empty widget itself.
---@class Widget : Object
---@field visible boolean Whether the widget is visible or not.
---@field enabled boolean Whether the widget is enabled or not.
---@field focus boolean Whether the widget has focus or not.
---@field toolTip string The tooltip of the widget.
gui.widget = {}

---@alias LayoutChild string|BaseAspect|Layout|Widget|function
---@alias LayoutChildren LayoutChild[]

---@class WidgetAttributeMapT<T>: { [WidgetAttribute]: T }

---@class (exact) BaseWidgetOptions
---@field size? integer[] Two integers, representing the width and height of the widget.
---@field windowFlags? WindowType[] The window flags of the widget.
---@field widgetAttributes? WidgetAttributeMapT<boolean> The widget attributes of the widget.
---@field autoFillBackground? boolean A boolean, representing whether the widget should automatically fill its background.
---@field sizePolicy? SizePolicy.Policy[] Two size policies of the widget, horizontal and vertical.
---@field toolTip? string The tooltip of the widget.
gui.baseWidgetOptions = {}

---@class (exact) WidgetOptions : BaseWidgetOptions
---@field title? string The title of the widget, if applicable.
---@field onTextChanged? function The function to be called when the text of the widget changes, if applicable.
---@field onClicked? function The function to be called when the widget is clicked, if applicable.
---@field icon? IconFilePathOrString The icon of the widget, if applicable. Can be a string, FilePath or Icon.
---@field iconPath? FilePath The path to the icon of the widget, if applicable. Empty or not existent paths set null icon. (see [QIcon](https://doc.qt.io/qt-5/qicon.html#QIcon))
---@field text? string The text of the widget, if applicable.
---@field value? integer The value of the widget, if applicable.
---@field flat? boolean A boolean, representing whether the widget should be flat, if applicable.
---@field [1]? Layout The layout of the widget, if applicable.
---@field fixedSize? integer[] Two integers representing the width and height
---@field contentMargins? integer[] Four integers represending left, top, right and bottom margins.
---@field cursor? CursorShape The cursor shape for the widget.
---@field minimumWidth? integer The minimum width in pixels.
---@field minimumHeight? integer Minimum height of input
gui.widgetOptions = {}

---@param options WidgetOptions
---@return Widget
function gui.Widget(options) end

---Show the widget. (see [QWidget::show](https://doc.qt.io/qt-5/qwidget.html#show))
function gui.widget:show() end

---Sets the top-level widget containing this widget to be the active window. (see [QWidget::activateWindow](https://doc.qt.io/qt-5/qwidget.html#activateWindow))
function gui.widget:activateWindow() end

---Closes the widget. (see [QWidget::close](https://doc.qt.io/qt-5/qwidget.html#close))
function gui.widget:close() end

---Column layout
---@class Column : Layout
local column = {}

---@param children LayoutChildren
---@return Column
function gui.Column(children) end

---A group box with a title.
---@class Group : Widget
local group = {}

---@param options WidgetOptions
---@return Group
function gui.Group(options) end

---Row layout.
---@class Row : Layout
local row = {}

---@param children LayoutChildren
---@return Row
function gui.Row(children) end

---Flow layout.
---@class Flow : Layout
local flow = {}

---@param children LayoutChildren
---@return Flow
function gui.Flow(children) end

---Grid layout.
---@class Grid : Layout
local grid = {}

---@param children LayoutChildren
---@return Grid
function gui.Grid(children) end

---Form layout.
---@class Form : Layout
local form = {}

---@param children LayoutChildren
---@return Form
function gui.Form(children) end

---A stack of multiple widgets.
---@class Stack : Widget
local stack = {}

---A ScrollArea widget.
---@class ScrollArea : Widget

---@param options WidgetOptions
---@return ScrollArea
function gui.ScrollArea(options) end

---@param options WidgetOptions
---@return Stack
function gui.Stack(options) end

---A Tab widget.
---@class Tab
local tab = {}

---@param name string
---@param layout Layout
---@return Tab
function gui.Tab(name, layout) end

---@class (exact) TabOptions
---@field [1] string The name of the tab.
---@field [2] Layout The layout of the tab.
gui.tabOptions = {}

---@param options TabOptions
---@return Tab tab The new tab.
function gui.Tab(options) end

---A Multiline text edit.
---@class TextEdit : Widget
local textEdit = {}

---@return string markdown Returns the content of the TextEdit as markdown
function textEdit:markdown() end

---@param options WidgetOptions
---@return TextEdit
function gui.TextEdit(options) end

---A multiline text edit with enhanced features for command completion and embedded icons.
---@class QtcTextEdit : Widget
---@field markdown string Current markdown content
---@field text string Current text content (plain text)
---@field completer QCompleter QCompleter object for text completion
---@field placeHolderText? string Placeholder text when the edit is empty
---@field completionBehavior QtcTextEdit.CompletionBehavior Completion trigger behavior (OnKeyPress|OnTextChange)
local qtcTextEdit = {}

---Enum representing how completion is triggered in QtcTextEdit
---@enum QtcTextEdit.CompletionBehavior
QtcTextEdit.CompletionBehavior = {
    -- Trigger completion via key events (e.g., CTRL+E).
    OnKeyPress = 0,
    -- Trigger completion on every text change.
    OnTextChange = 0,
}

---@class QtcTextEditOptions : WidgetOptions
---@field markdown? string Initial markdown content
---@field text? string Initial text content (plain text)
---@field placeHolderText? string Placeholder text shown when the edit is empty
---@field rightSideIconPath? FilePath Path to icon displayed on the right side
---@field completer? QCompleter QCompleter object for text completion
---@field completionBehavior? QtcTextEdit.CompletionBehavior Completion trigger behavior (default: OnKeyPress)
---@field onReturnPressed? function Function called when Enter is pressed (Shift+Enter for new line)
---@field onRightSideIconClicked? function Function called when right-side icon is clicked
local qtcTextEditOptions = {}

---@param options QtcTextEditOptions
---@return QtcTextEdit
function gui.QtcTextEdit(options) end

---A Single line text edit
---@class LineEdit : Widget
---@field rightSideIconPath? FilePath A path to icon
---@field text string Current text
local lineEdit = {}

---@class LineEditOptions : WidgetOptions
---@field rightSideIconPath? FilePath Path to icon displayed on the right side
---@field placeHolderText? string Placeholder text shown when the edit is empty
---@field completer? QCompleter QCompleter object for text completion
---@field onReturnPressed? function The function to be called when Enter is pressed
---@field onRightSideIconClicked? function The function to be called when right side icon is clicked
---@field text string Current text
local lineEditOptions = {}

---@param options LineEditOptions
---@return LineEdit
function gui.LineEdit(options) end

---@class PushButton : Widget
local pushButton = {}

---@param options WidgetOptions
---@return PushButton
function gui.PushButton(options) end


---@class QtcLabel : Widget
local QtcLabel = {}

---Enum representing the QtcLabel types
---@enum QtcLabel.Role
QtcLabel.Role = {
    Primary = 0,
    Secondary = 0,
}

---@class QtcLabelOptions : BaseWidgetOptions
---@field role? QtcLabel.Role e The role of the label. (default: "Primary")
---@field text? string The text of the label.

---@param options QtcLabelOptions
---@return QtcLabel
function gui.QtcLabel(options) end

---@class QtcButton : Widget
local QtcButton = {}

--- Enum representing the QtcButton roles
---@enum QtcButton.Role
QtcButton.Role = {
    LargePrimary = 0,
    LargeSecondary = 0,
    LargeTertiary = 0,
    LargeGhost = 0,
    MediumPrimary = 0,
    MediumSecondary = 0,
    MediumTertiary = 0,
    MediumGhost = 0,
    SmallPrimary = 0,
    SmallSecondary = 0,
    SmallTertiary = 0,
    SmallGhost = 0,
    SmallList = 0,
    SmallLink = 0,
    Tag = 0,
}

---@class QtcButtonOptions : BaseWidgetOptions
---@field role? QtcButton.Role The role of the button. (default: "MediumPrimary")
---@field text? string The text of the button.
---@field icon? IconFilePathOrString The icon of the button.

---@param options QtcButtonOptions
---@return QtcButton
function gui.QtcButton(options) end


---@class QtcSwitch : Widget
local QtcSwitch = {}

---@class QtcSwitchOptions : BaseWidgetOptions
---@field text? string The text of the switch.
---@field checked? boolean Whether the switch is checked or not.
---@field onClicked? function The function to be called when the switch is clicked.

---@param options QtcSwitchOptions
---@return QtcSwitch
function gui.QtcSwitch(options) end

---@class QtcSearchBox : Widget

---@class QtcSearchBoxOptions : BaseWidgetOptions
---@field text? string The text of the search box.
---@field onTextChanged? function The function to be called when the text is changed.
---@field placeholderText? string The placeholder text of the search box.

---@param options QtcSearchBoxOptions
---@return QtcSearchBox
function gui.QtcSearchBox(options) end

---@class Label : Widget
---@field text string Returns the content of the Label as string
local label = {}

---@class (exact) LabelOptions : BaseWidgetOptions
---@field interactionFlags? TextInteractionFlag[]
---@field textFormat? TextFormat The text format enum
---@field wordWrap? boolean

gui.labelOptions = {}

---@param options LabelOptions
---@return Label
function gui.Label(options) end

---@class SpinBox : Widget
local spinBox = {}

---@param options WidgetOptions
---@return SpinBox
function gui.SpinBox(options) end

---@class Splitter : Widget
local splitter = {}

---@alias Orientation "horizontal"|"vertical"

---@class (exact) SplitterOptions : BaseWidgetOptions
---@field orientation? Orientation The orientation of the splitter. (default: "vertical")
---@field childrenCollapsible? boolean A boolean, representing whether the children are collapsible. (default: true)
---@field stretchFactors? integer[] A list of integers, representing the stretch factors of the children. (default: {1, ...})
---@field size? integer[] Two integers, representing the width and height of the widget.
---@field [integer] Layout | Widget The splits.
gui.splitterOptions = {}

---@param options SplitterOptions
---@return Splitter
function gui.Splitter(options) end

---@class ToolBar : Widget
local toolBar = {}

---@param options WidgetOptions
---@return ToolBar
function gui.ToolBar(options) end

---@class ToolButton : Widget
local toolButton = {}

---@param options WidgetOptions
---@return ToolButton
function gui.ToolButton(options) end

---@class TabWidget : Widget
local tabWidget = {}

---@param options Tab[]
---@return TabWidget
function gui.TabWidget(options) end

---@param name string
---@param child WidgetOptions
---@return TabWidget
function gui.TabWidget(name, child) end

---@class MarkdownBrowser : Widget
---@field markdown string The markdown content of the MarkdownBrowser. Can be set or retrieved.
local markdownBrowser = {}

---@class (exact) MarkdownBrowserOptions : WidgetOptions
---@field enableCodeCopyButton? boolean Enable or disable the code copy button
---@field viewportMargins? integer[] Four integers representing left, top, right and bottom margins
local markdownBrowserOptions = {}

---@param options MarkdownBrowserOptions
---@return MarkdownBrowser
function gui.MarkdownBrowser(options) end

---@class Spinner : Widget
---@field running boolean Set spinner visible and display spinning animation
---@field decorated boolean Display spinner with custom styleSheet defined inside control (default true)
local spinner = {}

---@class SpinnerOverlay
---@field running boolean Show the spinner as a centered overlay on its target widget and animate it
local spinnerOverlay = {}

---Create a spinner that overlays and dims an existing widget while running.
---@param on Widget The widget to overlay (e.g. a ListWidget).
---@return SpinnerOverlay
function gui.SpinnerOverlay(on) end

---@class IconDisplay : Widget
local IconDisplay = {}

---@class (exact) IconDisplayOptions : BaseWidgetOptions
---@field icon? IconFilePathOrString The icon to display
gui.iconDisplayOptions = {}

---@param options IconDisplayOptions
---@return IconDisplay
function gui.IconDisplay(options) end

---A "Line break" in the gui.
function gui.br() end

---A "Stretch" in the layout.
function gui.st() end

---An empty grid cell in a grid layout.
function gui.empty() end

---A horizontal line in the layout.
function gui.hr() end

---Clears the margin of the layout.
function gui.noMargin() end

---Sets the margin of the layout to the default value.
function gui.normalMargin() end

---Sets the alignment of a Grid layout according to the Form layout rules.
function gui.withFormAlignment() end

---Sets the stretch factor at position index to stretch.
---@param index integer The widget index.
---@param stretch integer The stretch factor.
function gui.stretch(index, stretch) end

--- Enum representing Text interaction flags
---@enum TextInteractionFlag
gui.TextInteractionFlag {
    NoTextInteraction = 0,
    TextSelectableByMouse = 0,
    TextSelectableByKeyboard = 0,
    LinksAccessibleByMouse = 0,
    LinksAccessibleByKeyboard = 0,
    TextEditable = 0,

    TextEditorInteraction = TextSelectableByMouse | TextSelectableByKeyboard | TextEditable,
    TextBrowserInteraction = TextSelectableByMouse | LinksAccessibleByMouse | LinksAccessibleByKeyboard
}

--- Enum representing text format types
---@enum TextFormat
gui.TextFormat = {
    PlainText = 0,
    RichText = 0,
    AutoText = 0,
    MarkdownText = 0
}

--- Enum representing various window types.
---@enum WindowType
gui.WindowType = {
    Widget = 0,
    Window = 0,
    Dialog = 0,
    Sheet = 0,
    Drawer = 0,
    Popup = 0,
    Tool = 0,
    ToolTip = 0,
    SplashScreen = 0,
    Desktop = 0,
    SubWindow = 0,
    ForeignWindow = 0,
    CoverWindow = 0,
    WindowType_Mask = 0,
    MSWindowsFixedSizeDialogHint = 0,
    MSWindowsOwnDC = 0,
    BypassWindowManagerHint = 0,
    X11BypassWindowManagerHint = 0,
    FramelessWindowHint = 0,
    WindowTitleHint = 0,
    WindowSystemMenuHint = 0,
    WindowMinimizeButtonHint = 0,
    WindowMaximizeButtonHint = 0,
    WindowMinMaxButtonsHint = 0,
    WindowContextHelpButtonHint = 0,
    WindowShadeButtonHint = 0,
    WindowStaysOnTopHint = 0,
    WindowTransparentForInput = 0,
    WindowOverridesSystemGestures = 0,
    WindowDoesNotAcceptFocus = 0,
    MaximizeUsingFullscreenGeometryHint = 0,
    CustomizeWindowHint = 0,
    WindowStaysOnBottomHint = 0,
    WindowCloseButtonHint = 0,
    MacWindowToolBarButtonHint = 0,
    BypassGraphicsProxyWidget = 0,
    NoDropShadowWindowHint = 0,
    WindowFullscreenButtonHint = 0,
}

---@enum (key) WidgetAttribute
gui.WidgetAttribute = {
    WA_Disabled = 0,
    WA_UnderMouse = 0,
    WA_MouseTracking = 0,
    WA_OpaquePaintEvent = 0,
    WA_StaticContents = 0,
    WA_LaidOut = 0,
    WA_PaintOnScreen = 0,
    WA_NoSystemBackground = 0,
    WA_UpdatesDisabled = 0,
    WA_Mapped = 0,
    WA_InputMethodEnabled = 0,
    WA_WState_Visible = 0,
    WA_WState_Hidden = 0,
    WA_ForceDisabled = 0,
    WA_KeyCompression = 0,
    WA_PendingMoveEvent = 0,
    WA_PendingResizeEvent = 0,
    WA_SetPalette = 0,
    WA_SetFont = 0,
    WA_SetCursor = 0,
    WA_NoChildEventsFromChildren = 0,
    WA_WindowModified = 0,
    WA_Resized = 0,
    WA_Moved = 0,
    WA_PendingUpdate = 0,
    WA_InvalidSize = 0,
    WA_CustomWhatsThis = 0,
    WA_LayoutOnEntireRect = 0,
    WA_OutsideWSRange = 0,
    WA_GrabbedShortcut = 0,
    WA_TransparentForMouseEvents = 0,
    WA_PaintUnclipped = 0,
    WA_SetWindowIcon = 0,
    WA_NoMouseReplay = 0,
    WA_DeleteOnClose = 0,
    WA_RightToLeft = 0,
    WA_SetLayoutDirection = 0,
    WA_NoChildEventsForParent = 0,
    WA_ForceUpdatesDisabled = 0,
    WA_WState_Created = 0,
    WA_WState_CompressKeys = 0,
    WA_WState_InPaintEvent = 0,
    WA_WState_Reparented = 0,
    WA_WState_ConfigPending = 0,
    WA_WState_Polished = 0,
    WA_WState_OwnSizePolicy = 0,
    WA_WState_ExplicitShowHide = 0,
    WA_ShowModal = 0,
    WA_MouseNoMask = 0,
    WA_NoMousePropagation = 0,
    WA_Hover = 0,
    WA_InputMethodTransparent = 0,
    WA_QuitOnClose = 0,
    WA_KeyboardFocusChange = 0,
    WA_AcceptDrops = 0,
    WA_DropSiteRegistered = 0,
    WA_WindowPropagation = 0,
    WA_NoX11EventCompression = 0,
    WA_TintedBackground = 0,
    WA_X11OpenGLOverlay = 0,
    WA_AlwaysShowToolTips = 0,
    WA_MacOpaqueSizeGrip = 0,
    WA_SetStyle = 0,
    WA_SetLocale = 0,
    WA_MacShowFocusRect = 0,
    WA_MacNormalSize = 0,
    WA_MacSmallSize = 0,
    WA_MacMiniSize = 0,
    WA_LayoutUsesWidgetRect = 0,
    WA_StyledBackground = 0,
    WA_CanHostQMdiSubWindowTitleBar = 0,
    WA_MacAlwaysShowToolWindow = 0,
    WA_StyleSheet = 0,
    WA_ShowWithoutActivating = 0,
    WA_X11BypassTransientForHint = 0,
    WA_NativeWindow = 0,
    WA_DontCreateNativeAncestors = 0,
    WA_DontShowOnScreen = 0,
    WA_X11NetWmWindowTypeDesktop = 0,
    WA_X11NetWmWindowTypeDock = 0,
    WA_X11NetWmWindowTypeToolBar = 0,
    WA_X11NetWmWindowTypeMenu = 0,
    WA_X11NetWmWindowTypeUtility = 0,
    WA_X11NetWmWindowTypeSplash = 0,
    WA_X11NetWmWindowTypeDialog = 0,
    WA_X11NetWmWindowTypeDropDownMenu = 0,
    WA_X11NetWmWindowTypePopupMenu = 0,
    WA_X11NetWmWindowTypeToolTip = 0,
    WA_X11NetWmWindowTypeNotification = 0,
    WA_X11NetWmWindowTypeCombo = 0,
    WA_X11NetWmWindowTypeDND = 0,
    WA_SetWindowModality = 0,
    WA_WState_WindowOpacitySet = 0,
    WA_TranslucentBackground = 0,
    WA_AcceptTouchEvents = 0,
    WA_WState_AcceptedTouchBeginEvent = 0,
    WA_TouchPadAcceptSingleTouchEvents = 0,
    WA_X11DoNotAcceptFocus = 0,
    WA_AlwaysStackOnTop = 0,
    WA_TabletTracking = 0,
    WA_ContentsMarginsRespectsSafeArea = 0,
    WA_StyleSheetTarget = 0
}

--- Enum representing cursor shape for the widget
---@enum CursorShape
gui.CursorShape = {
    ArrowCursor = 0 = 0,
    UpArrowCursor = 0,
    CrossCursor = 0,
    WaitCursor = 0,
    IBeamCursor = 0,
    SizeVerCursor = 0,
    SizeHorCursor = 0,
    SizeBDiagCursor = 0,
    SizeFDiagCursor = 0,
    SizeAllCursor = 0,
    BlankCursor = 0,
    SplitVCursor = 0,
    SplitHCursor = 0,
    PointingHandCursor = 0,
    ForbiddenCursor = 0,
    WhatsThisCursor = 0,
    BusyCursor = 0,
    OpenHandCursor = 0,
    ClosedHandCursor = 0,
    DragCopyCursor = 0,
    DragMoveCursor = 0,
    DragLinkCursor = 0,
    LastCursor = DragLinkCursor,
    BitmapCursor = 0,
    CustomCursor = 0
}

gui.SizePolicy = {
    --- Enum representing size policy.
    ---@enum Policy
    Policy = {
        Fixed = 0,
        Minimum = 0,
        Maximum = 0,
        Preferred = 0,
        MinimumExpanding = 0,
        Expanding = 0,
        Ignored = 0
    }
}

---@class Space : Layout
gui.space = {}

---Adds a non-strecthable space with size size to the layout.
---@param size integer size in pixels of the space.
---@return Space
function gui.Space(size) end

---@class Span : Layout
gui.span = {}

---@class SpanOptions
---@field [1] integer The number of columns to span.
---@field [2] Layout The inner layout to span.

---@class SpanOptionsWithRow
---@field [1] integer The number of columns to span.
---@field [2] integer The number of rows to span.
---@field [3] Layout The inner layout.

---@param options SpanOptions|SpanOptionsWithRow
---@return Span
function gui.Span(options) end

---@param col integer The number of columns to span.
---@param layout Layout The inner layout.
---@return Span
function gui.Span(col, layout) end

---@param col integer The number of columns to span.
---@param row integer The number of rows to span.
---@param layout Layout The inner layout.
---@return Span
function gui.Span(col, row, layout) end

---@class Stretch : Layout
gui.stretch = {}

---Adds a stretchable space to the layout.
---@param factor integer The factor by which the space should stretch.
function gui.Stretch(factor) end

---@class ListWidget : Widget
local listWidget = {}

---@class (exact) ListWidgetOptions : BaseWidgetOptions
---@field items? string[] The initial items of the list.
---@field onItemActivated? function Called when an item is activated (double-click/Enter), with the 0-based row.
---@field onCurrentRowChanged? function Called when the current row changes, with the 0-based row (-1 if none).
gui.listWidgetOptions = {}

---A simple selectable list of strings.
---@param options ListWidgetOptions
---@return ListWidget
function gui.ListWidget(options) end

---Replaces all items with the given strings.
---@param items string[]
function listWidget:setItems(items) end

---Appends a single item.
---@param item string
function listWidget:addItem(item) end

---Removes all items.
function listWidget:clear() end

---@return integer row The current row, or -1 if none is selected.
function listWidget:currentRow() end

---@param row integer The row to select.
function listWidget:setCurrentRow(row) end

return gui
