189 lines
19 KiB
Markdown
189 lines
19 KiB
Markdown
# 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. |
|
||
|
||
### `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. |
|