diff --git a/Documentation/Reference/README.md b/Documentation/Reference/README.md index a6e55af..f6ba66e 100644 --- a/Documentation/Reference/README.md +++ b/Documentation/Reference/README.md @@ -17,6 +17,7 @@ - [AboutWindow](structs/AboutWindow.md) - [AppearObserver](structs/AppearObserver.md) +- [Banner](structs/Banner.md) - [Binding](structs/Binding.md) - [Button](structs/Button.md) - [Carousel](structs/Carousel.md) diff --git a/Documentation/Reference/structs/Banner.md b/Documentation/Reference/structs/Banner.md new file mode 100644 index 0000000..147d332 --- /dev/null +++ b/Documentation/Reference/structs/Banner.md @@ -0,0 +1,55 @@ +**STRUCT** + +# `Banner` + +A banner widget. + +## Properties +### `title` + +The content. + +### `visible` + +Whether the banner is visible. + +### `buttonLabel` + +The button's label. + +### `handler` + +The button's handler. + +## Methods +### `init(_:visible:)` + +Initialize a text widget. +- Parameters: + - title: The content. + - visible: Whether the banner is visible. + +### `update(_:modifiers:)` + +Update the view storage of the text widget. +- Parameters: + - storage: The view storage. + - modifiers: Modify views before being updated. + +### `container(modifiers:)` + +Get the container of the text widget. +- Returns: The view storage. + +### `update(banner:)` + +Update the banner. +- Parameter banner: The banner. + +### `button(_:handler:)` + +Configure the banner's button. +- Parameters: + - label: The button's title. + - handler: The button's handler. +- Returns: The banner. diff --git a/Sources/Adwaita/View/Banner.swift b/Sources/Adwaita/View/Banner.swift new file mode 100644 index 0000000..96ee65d --- /dev/null +++ b/Sources/Adwaita/View/Banner.swift @@ -0,0 +1,76 @@ +// +// Banner.swift +// Adwaita +// +// Created by david-swift on 03.01.24. +// + +import Libadwaita + +/// A banner widget. +public struct Banner: Widget { + + /// The content. + var title: String + /// Whether the banner is visible. + var visible: Bool + /// The button's label. + var buttonLabel: String? + /// The button's handler. + var handler: () -> Void = { } + + /// Initialize a text widget. + /// - Parameters: + /// - title: The content. + /// - visible: Whether the banner is visible. + public init(_ title: String, visible: Bool) { + self.title = title + self.visible = visible + } + + /// Update the view storage of the text widget. + /// - Parameters: + /// - storage: The view storage. + /// - modifiers: Modify views before being updated. + public func update(_ storage: ViewStorage, modifiers: [(View) -> View]) { + if let banner = storage.view as? Libadwaita.Banner { + update(banner: banner) + } + } + + /// Get the container of the text widget. + /// - Returns: The view storage. + public func container(modifiers: [(View) -> View]) -> ViewStorage { + let banner = Libadwaita.Banner(title) + update(banner: banner) + return .init(banner) + } + + /// Update the banner. + /// - Parameter banner: The banner. + func update(banner: Libadwaita.Banner) { + _ = banner.title(title) + if let buttonLabel { + _ = banner.buttonLabel(buttonLabel) + _ = banner.buttonHandler(handler) + } + if visible { + banner.show() + } else { + banner.hide() + } + } + + /// Configure the banner's button. + /// - Parameters: + /// - label: The button's title. + /// - handler: The button's handler. + /// - Returns: The banner. + public func button(_ label: String, handler: @escaping () -> Void) -> Self { + var newSelf = self + newSelf.buttonLabel = label + newSelf.handler = handler + return newSelf + } + +} diff --git a/user-manual/Information/Widgets.md b/user-manual/Information/Widgets.md index 283ea0d..31bde3e 100644 --- a/user-manual/Information/Widgets.md +++ b/user-manual/Information/Widgets.md @@ -21,6 +21,7 @@ This is an overview of the available widgets and other components in _Adwaita_. | Carousel | A paginated scrolling widget. | AdwCarousel | | ViewSwitcher | A control for switching between different views. | AdwViewSwitcher | | ProgressBar | A bar showing a progress. | GtkProgressBar | +| Banner | A bar showing contextual information. | AdwBanner | | StateWrapper | A wrapper not affecting the UI which stores state information. | - | ### View Modifiers @@ -76,6 +77,11 @@ This is an overview of the available widgets and other components in _Adwaita_. | ---------------------------- | --------------------------------------------------------------------------------------- | | `wideDesign(_:)` | Whether the wide view switcher design is used. | +## `Banner` Modifiers +| Syntax | Description | +| ---------------------------- | --------------------------------------------------------------------------------------- | +| `button(_:handler)` | Show the banner's button and set its title and handler. | + ### Window Types | Name | Description | Widget | | -------------------- | ----------------------------------------------------------------- | ---------------------- |