gi-gtk4-4.0.12: Gtk 4.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.SearchBar

Contents

- Exported types
- Methods
  - connectEntry
  - getChild
  - getKeyCaptureWidget
  - getSearchMode
  - getShowCloseButton
  - new
  - setChild
  - setKeyCaptureWidget
  - setSearchMode
  - setShowCloseButton
- Properties
  - child
  - keyCaptureWidget
  - searchModeEnabled
  - showCloseButton

Description

Reveals a search entry when search is started.

<picture> <source srcset="search-bar-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkSearchBar" src="search-bar.png"> </picture>

It can also contain additional widgets, such as drop-down menus, or buttons. The search bar would appear when a search is started through typing on the keyboard, or the application’s search mode is toggled on.

For keyboard presses to start a search, the search bar must be told of a widget to capture key events from through `searchBarSetKeyCaptureWidget`. This widget will typically be the top-level window, or a parent container of the search bar. Common shortcuts such as Ctrl+F should be handled as an application action, or through the menu items.

You will also need to tell the search bar about which entry you are using as your search entry using `searchBarConnectEntry`.

## Creating a search bar

The following example shows you how to create a more complex search entry.

A simple example

# Shortcuts and Gestures

`GtkSearchBar` supports the following keyboard shortcuts:

- <kbd>Escape</kbd> hides the search bar.

# CSS nodes

    searchbar
    ╰── revealer
        ╰── box
             ├── [child]
             ╰── [button.close]

`GtkSearchBar` has a main CSS node with name searchbar. It has a child node with name revealer that contains a node with name box. The box node contains both the CSS node of the child widget as well as an optional button node which gets the .close style class applied.

# Accessibility

`GtkSearchBar` uses the `AccessibleRoleSearch` role.

Synopsis

- newtype SearchBar = SearchBar (ManagedPtr SearchBar)
- class (GObject o, IsDescendantOf SearchBar o) => IsSearchBar o
- toSearchBar :: (MonadIO m, IsSearchBar o) => o -> m SearchBar
- searchBarConnectEntry :: (HasCallStack, MonadIO m, IsSearchBar a, IsEditable b) => a -> b -> m ()
- searchBarGetChild :: (HasCallStack, MonadIO m, IsSearchBar a) => a -> m (Maybe Widget)
- searchBarGetKeyCaptureWidget :: (HasCallStack, MonadIO m, IsSearchBar a) => a -> m (Maybe Widget)
- searchBarGetSearchMode :: (HasCallStack, MonadIO m, IsSearchBar a) => a -> m Bool
- searchBarGetShowCloseButton :: (HasCallStack, MonadIO m, IsSearchBar a) => a -> m Bool
- searchBarNew :: (HasCallStack, MonadIO m) => m SearchBar
- searchBarSetChild :: (HasCallStack, MonadIO m, IsSearchBar a, IsWidget b) => a -> Maybe b -> m ()
- searchBarSetKeyCaptureWidget :: (HasCallStack, MonadIO m, IsSearchBar a, IsWidget b) => a -> Maybe b -> m ()
- searchBarSetSearchMode :: (HasCallStack, MonadIO m, IsSearchBar a) => a -> Bool -> m ()
- searchBarSetShowCloseButton :: (HasCallStack, MonadIO m, IsSearchBar a) => a -> Bool -> m ()
- clearSearchBarChild :: (MonadIO m, IsSearchBar o) => o -> m ()
- constructSearchBarChild :: (IsSearchBar o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o)
- getSearchBarChild :: (MonadIO m, IsSearchBar o) => o -> m (Maybe Widget)
- setSearchBarChild :: (MonadIO m, IsSearchBar o, IsWidget a) => o -> a -> m ()
- clearSearchBarKeyCaptureWidget :: (MonadIO m, IsSearchBar o) => o -> m ()
- constructSearchBarKeyCaptureWidget :: (IsSearchBar o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o)
- getSearchBarKeyCaptureWidget :: (MonadIO m, IsSearchBar o) => o -> m (Maybe Widget)
- setSearchBarKeyCaptureWidget :: (MonadIO m, IsSearchBar o, IsWidget a) => o -> a -> m ()
- constructSearchBarSearchModeEnabled :: (IsSearchBar o, MonadIO m) => Bool -> m (GValueConstruct o)
- getSearchBarSearchModeEnabled :: (MonadIO m, IsSearchBar o) => o -> m Bool
- setSearchBarSearchModeEnabled :: (MonadIO m, IsSearchBar o) => o -> Bool -> m ()
- constructSearchBarShowCloseButton :: (IsSearchBar o, MonadIO m) => Bool -> m (GValueConstruct o)
- getSearchBarShowCloseButton :: (MonadIO m, IsSearchBar o) => o -> m Bool
- setSearchBarShowCloseButton :: (MonadIO m, IsSearchBar o) => o -> Bool -> m ()

# Exported types

newtype SearchBar Source #

Memory-managed wrapper type.

Constructors

SearchBar (ManagedPtr SearchBar) |

#### Instances

Instances details

Eq SearchBar Source # |
Instance details Defined in GI.Gtk.Objects.SearchBar Methods (==) :: SearchBar -> SearchBar -> Bool Source # (/=) :: SearchBar -> SearchBar -> Bool Source #
GObject SearchBar Source # |
Instance details Defined in GI.Gtk.Objects.SearchBar
ManagedPtrNewtype SearchBar Source # |
Instance details Defined in GI.Gtk.Objects.SearchBar Methods toManagedPtr :: SearchBar -> ManagedPtr SearchBar Source #
TypedObject SearchBar Source # |
Instance details Defined in GI.Gtk.Objects.SearchBar Methods glibType :: IO GType Source #
HasParentTypes SearchBar Source # |
Instance details Defined in GI.Gtk.Objects.SearchBar
IsGValue (Maybe SearchBar) Source # | Convert `SearchBar` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.SearchBar Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe SearchBar -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe SearchBar) Source #
type ParentTypes SearchBar Source # |
Instance details Defined in GI.Gtk.Objects.SearchBar type ParentTypes SearchBar = '[Widget, Object, Accessible, Buildable, ConstraintTarget]

class (GObject o, IsDescendantOf SearchBar o) => IsSearchBar o Source #

Type class for types which can be safely cast to `SearchBar`, for instance with `toSearchBar`.

#### Instances

Instances details

(GObject o, IsDescendantOf SearchBar o) => IsSearchBar o Source # |
Instance details Defined in GI.Gtk.Objects.SearchBar

toSearchBar :: (MonadIO m, IsSearchBar o) => o -> m SearchBar Source #

Cast to `SearchBar`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, announce, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, connectEntry, contains, createPangoContext, createPangoLayout, disposeTemplate, dragCheckThreshold, errorBell, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFloating, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, map, measure, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, queueAllocate, queueDraw, queueResize, realize, ref, refSink, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, resetProperty, resetRelation, resetState, runDispose, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateNextAccessibleSibling, updatePlatformState, updateProperty, updateRelation, updateState, watchClosure.

#### Getters

getAccessibleId, getAccessibleParent, getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAtContext, getBaseline, getBounds, getBuildableId, getCanFocus, getCanTarget, getChild, getChildVisible, getClipboard, getColor, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getFirstAccessibleChild, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasTooltip, getHeight, getHexpand, getHexpandSet, getKeyCaptureWidget, getLastChild, getLayoutManager, getLimitEvents, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNextAccessibleSibling, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPlatformState, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRoot, getScaleFactor, getSearchMode, getSensitive, getSettings, getShowCloseButton, getSize, getSizeRequest, getStateFlags, getStyleContext, getTemplateChild, getTooltipMarkup, getTooltipText, getValign, getVexpand, getVexpandSet, getVisible, getWidth.

#### Setters

setAccessibleParent, setCanFocus, setCanTarget, setChild, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHalign, setHasTooltip, setHexpand, setHexpandSet, setKeyCaptureWidget, setLayoutManager, setLimitEvents, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setParent, setProperty, setReceivesDefault, setSearchMode, setSensitive, setShowCloseButton, setSizeRequest, setStateFlags, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible.

## connectEntry

searchBarConnectEntry Source #

Arguments

:: (HasCallStack, MonadIO m, IsSearchBar a, IsEditable b) |
=> a | `bar`: a `GtkSearchBar`
-> b | `entry`: a `GtkEditable`
-> m () |

Connects the `GtkEditable` widget passed as the one to be used in this search bar.

The entry should be a descendant of the search bar. Calling this function manually is only required if the entry isn’t the direct child of the search bar (as in our main example).

## getChild

searchBarGetChild Source #

Arguments

:: (HasCallStack, MonadIO m, IsSearchBar a) |
=> a | `bar`: a `GtkSearchBar`
-> m (Maybe Widget) | Returns: the child widget of `bar`

Gets the child widget of `bar`.

## getKeyCaptureWidget

searchBarGetKeyCaptureWidget Source #

Arguments

:: (HasCallStack, MonadIO m, IsSearchBar a) |
=> a | `bar`: a `GtkSearchBar`
-> m (Maybe Widget) | Returns: The key capture widget.

Gets the widget that `bar` is capturing key events from.

## getSearchMode

searchBarGetSearchMode Source #

Arguments

:: (HasCallStack, MonadIO m, IsSearchBar a) |
=> a | `bar`: a `GtkSearchBar`
-> m Bool | Returns: whether search mode is toggled on

Returns whether the search mode is on or off.

## getShowCloseButton

searchBarGetShowCloseButton Source #

Arguments

:: (HasCallStack, MonadIO m, IsSearchBar a) |
=> a | `bar`: a `GtkSearchBar`
-> m Bool | Returns: whether the close button is shown

Returns whether the close button is shown.

## new

searchBarNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m SearchBar | Returns: a new `GtkSearchBar`

Creates a `GtkSearchBar`.

You will need to tell it about which widget is going to be your text entry using `searchBarConnectEntry`.

## setChild

searchBarSetChild Source #

Arguments

:: (HasCallStack, MonadIO m, IsSearchBar a, IsWidget b) |
=> a | `bar`: a `GtkSearchBar`
-> Maybe b | `child`: the child widget
-> m () |

Sets the child widget of `bar`.

## setKeyCaptureWidget

searchBarSetKeyCaptureWidget Source #

Arguments

:: (HasCallStack, MonadIO m, IsSearchBar a, IsWidget b) |
=> a | `bar`: a `GtkSearchBar`
-> Maybe b | `widget`: a `GtkWidget`
-> m () |

Sets `widget` as the widget that `bar` will capture key events from.

If key events are handled by the search bar, the bar will be shown, and the entry populated with the entered text.

Note that despite the name of this function, the events are only 'captured' in the bubble phase, which means that editable child widgets of `widget` will receive text input before it gets captured. If that is not desired, you can capture and forward the events yourself with `eventControllerKeyForward`.

## setSearchMode

searchBarSetSearchMode Source #

Arguments

:: (HasCallStack, MonadIO m, IsSearchBar a) |
=> a | `bar`: a `GtkSearchBar`
-> Bool | `searchMode`: the new state of the search mode
-> m () |

Switches the search mode on or off.

## setShowCloseButton

searchBarSetShowCloseButton Source #

Arguments

:: (HasCallStack, MonadIO m, IsSearchBar a) |
=> a | `bar`: a `GtkSearchBar`
-> Bool | `visible`: whether the close button will be shown or not
-> m () |

Shows or hides the close button.

Applications that already have a “search” toggle button should not show a close button in their search bar, as it duplicates the role of the toggle button.

# Properties

## child

The child widget.

clearSearchBarChild :: (MonadIO m, IsSearchBar o) => o -> m () Source #

Set the value of the “`child`” property to `Nothing`. When overloading is enabled, this is equivalent to

    clear #child

constructSearchBarChild :: (IsSearchBar o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`child`” property. This is rarely needed directly, but it is used by `new`.

getSearchBarChild :: (MonadIO m, IsSearchBar o) => o -> m (Maybe Widget) Source #

Get the value of the “`child`” property. When overloading is enabled, this is equivalent to

    get searchBar #child

setSearchBarChild :: (MonadIO m, IsSearchBar o, IsWidget a) => o -> a -> m () Source #

Set the value of the “`child`” property. When overloading is enabled, this is equivalent to

    set searchBar [ #child := value ]

## keyCaptureWidget

The key capture widget.

clearSearchBarKeyCaptureWidget :: (MonadIO m, IsSearchBar o) => o -> m () Source #

Set the value of the “`key-capture-widget`” property to `Nothing`. When overloading is enabled, this is equivalent to

    clear #keyCaptureWidget

constructSearchBarKeyCaptureWidget :: (IsSearchBar o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`key-capture-widget`” property. This is rarely needed directly, but it is used by `new`.

getSearchBarKeyCaptureWidget :: (MonadIO m, IsSearchBar o) => o -> m (Maybe Widget) Source #

Get the value of the “`key-capture-widget`” property. When overloading is enabled, this is equivalent to

    get searchBar #keyCaptureWidget

setSearchBarKeyCaptureWidget :: (MonadIO m, IsSearchBar o, IsWidget a) => o -> a -> m () Source #

Set the value of the “`key-capture-widget`” property. When overloading is enabled, this is equivalent to

    set searchBar [ #keyCaptureWidget := value ]

## searchModeEnabled

Whether the search mode is on and the search bar shown.

constructSearchBarSearchModeEnabled :: (IsSearchBar o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`search-mode-enabled`” property. This is rarely needed directly, but it is used by `new`.

getSearchBarSearchModeEnabled :: (MonadIO m, IsSearchBar o) => o -> m Bool Source #

Get the value of the “`search-mode-enabled`” property. When overloading is enabled, this is equivalent to

    get searchBar #searchModeEnabled

setSearchBarSearchModeEnabled :: (MonadIO m, IsSearchBar o) => o -> Bool -> m () Source #

Set the value of the “`search-mode-enabled`” property. When overloading is enabled, this is equivalent to

    set searchBar [ #searchModeEnabled := value ]

## showCloseButton

Whether to show the close button in the search bar.

constructSearchBarShowCloseButton :: (IsSearchBar o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`show-close-button`” property. This is rarely needed directly, but it is used by `new`.

getSearchBarShowCloseButton :: (MonadIO m, IsSearchBar o) => o -> m Bool Source #

Get the value of the “`show-close-button`” property. When overloading is enabled, this is equivalent to

    get searchBar #showCloseButton

setSearchBarShowCloseButton :: (MonadIO m, IsSearchBar o) => o -> Bool -> m () Source #

Set the value of the “`show-close-button`” property. When overloading is enabled, this is equivalent to

    set searchBar [ #showCloseButton := value ]