# Widgets

This is an overview of the available widgets and other components in _Adwaita_ that are not auto-generated or that are wrappers for easily accessing auto-generated widgets.
There are many more widgets available using auto-generation. Learn [how to use them.](AutoGeneratedWidgets.md)

| Name                 | Description                                                         | Widget                 |
| -------------------- | ------------------------------------------------------------------- | ---------------------- |
| ViewStack            | A widget that displays one of its child views based on an id.       | GtkStack               |
| VStack               | A widget which arranges child widgets into a single column.         | GtkBox                 |
| HStack               | A widget which arranges child widgets into a single row.            | GtkBox                 |
| Toggle               | A button with two possible states, on and off.                      | GtkToggleButton        |
| List                 | A widget which arranges child widgets vertically into rows.         | GtkListBox             |
| ForEach              | Arrange dynamic widgets vertically or horizontally.                 | GtkBox                 |
| NavigationSplitView  | A widget presenting sidebar and content side by side.               | AdwNavigationSplitView |
| ScrollView           | A container that makes its child scrollable.                        | GtkScrolledWindow      |
| ViewSwitcher         | A control for switching between different views.                    | AdwViewSwitcher        |
| StateWrapper         | A wrapper not affecting the UI which stores state information.      | -                      |
| FormSection          | A titled section, usually containing one or multiple forms.         | AdwPreferencesGroup    |
| Form                 | A static boxed list, usually containing one or multiple rows.       | GtkListBox             |

### View Modifiers

| Syntax                            | Description                                                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `freeze(_:)`                      | Prevent a view from being updated.                                                                                             |
| `inspect(_:)`                     | Edit the underlying Gtk or Libadwaita widget.                                                                                  |
| `padding(_:_:)`                   | Add empty space around a view.                                                                                                 |
| `hexpand(_:)`                     | Enable or disable the horizontal expansion of a view.                                                                          |
| `vexpand(_:)`                     | Enable or disable the vertical expansion of a view.                                                                            |
| `halign(_:)`                      | Set the horizontal alignment of a view.                                                                                        |
| `valign(_:)`                      | Set the vertical alignment of a view.                                                                                          |
| `frame(minWidth:minHeight:)`      | Set the view’s minimum width or height.                                                                                        |
| `frame(maxWidth:)`                | Set the view’s maximum width.                                                                                                  |
| `frame(maxHeight:)`               | Set the view’s maximum height.                                                                                                 |
| `transition(_:)`                  | Assign a transition with the view that is used if it is a direct child of an EitherView.                                       |
| `onUpdate(_:)`                    | Run a function every time a view gets updated.                                                                                 |
| `navigationTitle(_:)`             | Add a title that is used if the view is a direct child of a NavigationView.                                                    |
| `style(_:)`                       | Add a style class to the view.                                                                                                 |
| `onAppear(_:)`                    | Run when the view is rendered for the first time.                                                                              |
| `inspectOnAppear(_:)`             | Edit the underlying Gtk or Libadwaita class when the view is rendered for the first time.                                      |
| `topToolbar(visible:_:)`          | Add a native toolbar to the view. Normally, it contains a HeaderBar.                                                           |
| `bottomToolbar(visible:_:)`       | Add a native bottom toolbar to the view.                                                                                       |
| `modifyContent(_:modify:)`        | Replace all occurrences of a certain view type with another view.                                                              |
| `stopModifiers()`                 | Ignore all the `modifyContent(_:modify:)` modifiers from higher above in the view tree.                                        |
| `toast(_:signal:)`                | Show a toast on top of the view whenever the signal gets activated.                                                            |
| `toast(_:signal:button:handler:)` | Show a toast with a button on top of the view whenever the signal gets activated.                                              |
| `overlay(_:)`                     | Overlay a view with another view.                                                                                              |
| `insensitive(_:)`                 | Make a view unable to detect actions. This is especially useful for overlays.                                                  |
| `onClick(handler:)`               | Run a function when the user clicks on the widget.                                                                             |
| `focused(_:)`                     | Set and observe whether a view is focused.                                                                                     |
| `focus(_:)`                       | Bind a signal that focuses the view.                                                                                           |
| `verticalCenter()`                | Wrap a view in a `VStack` and center vertically.                                                                               |
| `horizontalCenter()`              | Wrap a view in an `HStack` and center horizontally.                                                                            |
| `dialog(visible:title:content:)`  | Add a dialog to the window containing the view.                                                                                |

### `Button` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `keyboardShortcut(_:window:)`| Create a keyboard shortcut for the window with the button's action.                     |
| `keyboardShortcut(_:app:)`   | Create a keyboard shortcut for the application with the button's action.                |

### `HeaderBar` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `headerBarTitle(view:)`      | Customize the title view in the header bar.                                             |

### `Text` Modifiers
| Syntax                       | Description                                                                                         |
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
| `wrap(_:)`                   | Enable or disable line wrapping (expanding the text view to multiple lines if the width is narrow). |

### `Toggle` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `checkButton()`              | Use a check button design instead of a toggle.                                          |

### `List` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `sidebarStyle()`             | Change the style of the list to match a sidebar.                                        |

### `OverlaySplitView` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `trailingSidebar(_:)`        | Whether the sidebar is trailing to the content view.                                    |

### `Carousel` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `longSwipes(_:)`             | Whether long swiping is enabled.                                                        |

### `ViewSwitcher` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `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.                                 |

### `FormSection` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `description(_:)`            | Set the section's description.                                                          |
| `suffix(_:)`                 | Set the section's suffix view.                                                          |

### `ActionRow` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `subtitle(_:)`               | Set the row's subtitle.                                                                 |
| `prefix(_:)`                 | Set the row's prefix view.                                                              |
| `suffix(_:)`                 | Set the row's suffix view.                                                              |

### `ComboRow` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `subtitle(_:)`               | Set the row's subtitle.                                                                 |
| `prefix(_:)`                 | Set the row's prefix view.                                                              |
| `suffix(_:)`                 | Set the row's suffix view.                                                              |

### `EntryRow` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `onSubmit(_:)`               | Add a submit button to the entry row. Run the provided closure when it gets pressed.    |
| `prefix(_:)`                 | Set the row's prefix view.                                                              |
| `suffix(_:)`                 | Set the row's suffix view.                                                              |
| `secure()`                   | Use the secure design for password inputs etc.                                          |

### `SpinRow` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `subtitle(_:)`               | Set the row's subtitle.                                                                 |
| `prefix(_:)`                 | Set the row's prefix view.                                                              |
| `suffix(_:)`                 | Set the row's suffix view.                                                              |
| `step(_:)`                   | Set the increase/decrease rate of the buttons.                                          |

### `SwitchRow` Modifiers
| Syntax                       | Description                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `subtitle(_:)`               | Set the row's subtitle.                                                                 |
| `prefix(_:)`                 | Set the row's prefix view.                                                              |
| `suffix(_:)`                 | Set the row's suffix view.                                                              |

### Window Types
| Name                 | Description                                                       | Widget                 |
| -------------------- | ----------------------------------------------------------------- | ---------------------- |
| Window               | A simple application window.                                      | AdwApplicationWindow   |
| AboutWindow          | A GNOME about window.                                             | AdwAboutWindow         |

### Window Modifiers
| Syntax                          | Description                                                                             |
| ------------------------------- | --------------------------------------------------------------------------------------- |
| `appKeyboardShortcut(_:action:)`| Create a keyboard shortcut available in the whole the application.                      |
| `quitShortcut()`                | Create a keyboard shortcut for quitting the application with "Ctrl + q".                |

### `Window` Modifiers
| Syntax                                                             | Description                                                                             |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `keyboardShortcut(_:action:)`                                      | Create a keyboard shortcut available in one window.                                     |
| `closeShortcut()`                                                  | Create a keyboard shortcut for closing the window with "Ctrl + w".                      |
| `overlay(windows:)`                                                | Add windows that attach to a window of this type when being presented.                  |
| `fileImporter(_:initialFolder:extensions:folders:onOpen:onClose:)` | Add an import file dialog.                                                              |
| `fileExporter(_:initialFolder:initialName:onSave:onClose:)`        | Add an export file dialog.                                                              |
| `defaultSize(width:height:)`                                       | Set the window's initial size.                                                          |
| `title(_:)`                                                        | Set the window's title.                                                                 |
| `resizable(_:)`                                                    | Set the window's resizability.                                                          |
| `deletable(_:)`                                                    | Set the window's deletability.                                                          |
| `maximized(_:)`                                                    | Get and set whether the window is maximized.                                            |
| `size(width:height:)`                                              | Get and set the window's width and height.                                              |

### `AboutWindow` Modifiers
| Syntax          | Description                                                                             |
| --------------- | --------------------------------------------------------------------------------------- |
| `icon(_:)`      | Set the app icon.                                                                       |
| `website(_:)`   | Set the app's website.                                                                  |
| `issues(_:)`    | Set the app's bug tracker.                                                              |

### Menu Widgets
| Name                 | Description                                                       | Widget                 |
| -------------------- | ----------------------------------------------------------------- | ---------------------- |
| MenuButton           | A button in a menu.                                               | GMenuItem              |
| MenuSection          | A collection of menu widgets grouped with lines.                  | GMenuItem              |
| Submenu              | A collection of menu widgets grouped by navigation.               | GMenuItem              |

### `MenuButton` Modifiers
| Syntax                          | Description                                                                             |
| ------------------------------- | --------------------------------------------------------------------------------------- |
| `keyboardShortcut(_:)`          | Assign a keyboard shortcut to the button's action.                                      |
