portico/Sources/PorticoGtk/Generated/HeaderBar.swift

// Generated by PorticoGen. DO NOT EDIT. See Sources/PorticoGen to make changes.

import Adw
import Gtk
import Gio
import Gdk
@_spi(Portico) import Portico

// PorticoGen: generateStruct | source: Gtk.HeaderBar
/// Creates a custom titlebar for a window.
///
/// <picture>
///   <source srcset="headerbar-dark.png" media="(prefers-color-scheme: dark)">
///   <img alt="An example GtkHeaderBar" src="headerbar.png">
/// </picture>
///
/// `GtkHeaderBar` is similar to a horizontal `GtkCenterBox`. It allows
/// children to be placed at the start or the end. In addition, it allows
/// the window title to be displayed. The title will be centered with respect
/// to the width of the box, even if the children at either side take up
/// different amounts of space.
///
/// `GtkHeaderBar` can add typical window frame controls, such as minimize,
/// maximize and close buttons, or the window icon.
///
/// For these reasons, `GtkHeaderBar` is the natural choice for use as the
/// custom titlebar widget of a `GtkWindow` (see [method`Gtk`.Window.set_titlebar]),
/// as it gives features typical of titlebars while allowing the addition of
/// child widgets.
///
/// ## GtkHeaderBar as GtkBuildable
///
/// The `GtkHeaderBar` implementation of the `GtkBuildable` interface supports
/// adding children at the start or end sides by specifying “start” or “end” as
/// the “type” attribute of a `<child>` element, or setting the title widget by
/// specifying “title” value.
///
/// By default the `GtkHeaderBar` uses a `GtkLabel` displaying the title of the
/// window it is contained in as the title widget, equivalent to the following
/// UI definition:
///
/// ```xml
/// <object class="GtkHeaderBar">
///   <property name="title-widget">
///     <object class="GtkLabel">
///       <property name="label" translatable="yes">Label</property>
///       <property name="single-line-mode">True</property>
///       <property name="ellipsize">end</property>
///       <property name="width-chars">5</property>
///       <style>
///         <class name="title"/>
///       </style>
///     </object>
///   </property>
/// </object>
/// ```
///
/// # CSS nodes
///
/// ```
/// headerbar
/// ╰── windowhandle
///     ╰── box
///         ├── box.start
///         │   ├── windowcontrols.start
///         │   ╰── [other children]
///         ├── [Title Widget]
///         ╰── box.end
///             ├── [other children]
///             ╰── windowcontrols.end
/// ```
///
/// A `GtkHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle`
/// subnode, which contains a `box` subnode, which contains two `box` subnodes at
/// the start and end of the header bar, as well as a center node that represents
/// the title.
///
/// Each of the boxes contains a `windowcontrols` subnode, see
/// [class`Gtk`.WindowControls] for details, as well as other children.
///
/// # Accessibility
///
/// `GtkHeaderBar` uses the [enum`Gtk`.AccessibleRole.group] role.
///
/// A Portico view that mounts a `Gtk.HeaderBar`.
@MainActor public struct HeaderBar: View {
    private let make: (MountContext) -> Gtk.HeaderBar
    private var configure: [(Gtk.HeaderBar, MountContext) -> Void] = []

    public var body: Never { fatalError() }

    // PorticoGen: generateInits(static) | source: Gtk.HeaderBar.init()
    /// Creates a new `GtkHeaderBar` widget.
    ///
    /// Applied once at mount; use the `Binding` or closure overload for values that change.
    /// Each closure is evaluated once; children are added in order and slot closures mount their first view.
    /// An empty closure adds no children and leaves slots unset.
    /// Optional value parameters are applied only when non-`nil`; a `nil` argument leaves the widget's own default in place and cannot clear a nullable property - use the matching modifier for that.
    ///
    /// - Parameter decorationLayout: The decoration layout for buttons.
    /// - Parameter showTitleButtons: Whether to show title buttons like close, minimize, maximize.
    /// - Parameter useNativeControls: Whether to show platform native close/minimize/maximize buttons.
    /// - Parameter titleWidget: A `ViewBuilder` closure whose first view is mounted into the `titleWidget` slot.
    public init(decorationLayout: String? = nil, showTitleButtons: Bool? = nil, useNativeControls: Bool? = nil, @ViewBuilder titleWidget: () -> [AnyView] = { [] }) {
        let titleWidgetViews = titleWidget()
        make = { _ in Gtk.HeaderBar() }
        configure.append { w, ctx in
            if let decorationLayout { w.setDecorationLayout(layout: decorationLayout) }
            if let showTitleButtons { w.setShowTitleButtons(setting: showTitleButtons) }
            if let useNativeControls { w.setUseNativeControls(setting: useNativeControls) }
            if let v = titleWidgetViews.first { w.setTitleWidget(titleWidget: v.makeWidget(ctx)) }
        }
    }

}

extension HeaderBar: WidgetView {
    public typealias Target = Gtk.HeaderBar

    @_spi(Portico) public func appending(
        _ step: @escaping (Gtk.HeaderBar, MountContext) -> Void
    ) -> Self {
        var c = self
        c.configure.append(step)
        return c
    }
}

@_spi(Portico) extension HeaderBar: Mountable {
    @_spi(Portico) public func mount(_ ctx: MountContext) -> Gtk.Widget {
        let w = make(ctx)
        for step in configure { step(w, ctx) }
        return w
    }
}