GI.Gtk.Objects.SearchEntry

GtkSearchEntry is an entry widget that has been tailored for use as a search entry.

The main API for interacting with a GtkSearchEntry as entry is the GtkEditable interface.

It will show an inactive symbolic “find” icon when the search entry is empty, and a symbolic “clear” icon when there is text. Clicking on the “clear” icon will empty the search entry.

To make filtering appear more reactive, it is a good idea to not react to every change in the entry text immediately, but only after a short delay. To support this, GtkSearchEntry emits the SearchEntry::searchChanged signal which can be used instead of the Editable::changed signal.

The SearchEntry::previousMatch, SearchEntry::nextMatch and SearchEntry::stopSearch signals can be used to implement moving between search results and ending the search.

Often, GtkSearchEntry will be fed events by means of being placed inside a SearchBar. If that is not the case, you can use searchEntrySetKeyCaptureWidget to let it capture key input from another widget.

GtkSearchEntry provides only minimal API and should be used with the Editable API.

CSS Nodes

entry.search
╰── text

GtkSearchEntry has a single CSS node with name entry that carries a .search style class, and the text node is a child of that.

Accessibility

GtkSearchEntry uses the AccessibleRoleSearchBox role.

Exported types

newtype SearchEntry

Memory-managed wrapper type.

Constructors

SearchEntry (ManagedPtr SearchEntry)

Instances

Eq SearchEntry

Defined in GI.Gtk.Objects.SearchEntry

Methods

(==) :: SearchEntry -> SearchEntry -> Bool

(/=) :: SearchEntry -> SearchEntry -> Bool

GObject SearchEntry

Defined in GI.Gtk.Objects.SearchEntry

ManagedPtrNewtype SearchEntry

Defined in GI.Gtk.Objects.SearchEntry

Methods

toManagedPtr :: SearchEntry -> ManagedPtr SearchEntry

TypedObject SearchEntry

Defined in GI.Gtk.Objects.SearchEntry

Methods

glibType :: IO GType

HasParentTypes SearchEntry

Defined in GI.Gtk.Objects.SearchEntry

IsGValue (Maybe SearchEntry)

Convert SearchEntry to and from GValue. See toGValue and fromGValue.

Defined in GI.Gtk.Objects.SearchEntry

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe SearchEntry -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe SearchEntry)

type ParentTypes SearchEntry

Defined in GI.Gtk.Objects.SearchEntry

type ParentTypes SearchEntry = '[Widget, Object, Accessible, Buildable, ConstraintTarget, Editable]

class (GObject o, IsDescendantOf SearchEntry o) => IsSearchEntry o

Type class for types which can be safely cast to SearchEntry, for instance with toSearchEntry.

Instances

(GObject o, IsDescendantOf SearchEntry o) => IsSearchEntry o

Defined in GI.Gtk.Objects.SearchEntry

toSearchEntry :: (MonadIO m, IsSearchEntry o) => o -> m SearchEntry

Cast to SearchEntry, 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

Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, delegateGetAccessiblePlatformState, deleteSelection, deleteText, disposeTemplate, dragCheckThreshold, errorBell, finishDelegate, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initDelegate, initTemplate, insertActionGroup, insertAfter, insertBefore, insertText, 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, selectRegion, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateNextAccessibleSibling, updateProperty, updateRelation, updateState, watchClosure.

Getters

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

Setters

setAccessibleParent, setAlignment, setCanFocus, setCanTarget, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setEditable, setEnableUndo, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHalign, setHasTooltip, setHexpand, setHexpandSet, setKeyCaptureWidget, setLayoutManager, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setMaxWidthChars, setName, setOpacity, setOverflow, setParent, setPlaceholderText, setPosition, setProperty, setReceivesDefault, setSearchDelay, setSensitive, setSizeRequest, setStateFlags, setText, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible, setWidthChars.

getKeyCaptureWidget

searchEntryGetKeyCaptureWidget

Arguments

:: (HasCallStack, MonadIO m, IsSearchEntry a)

=> a

entry: a GtkSearchEntry

-> m (Maybe Widget)

Returns: The key capture widget.

Gets the widget that entry is capturing key events from.

getPlaceholderText

searchEntryGetPlaceholderText

Arguments

:: (HasCallStack, MonadIO m, IsSearchEntry a)

=> a

entry: a GtkSearchEntry

-> m (Maybe Text)

Returns: The placeholder text.

Gets the placeholder text associated with entry.

Since: 4.10

getSearchDelay

searchEntryGetSearchDelay

Arguments

:: (HasCallStack, MonadIO m, IsSearchEntry a)

=> a

entry: a GtkSearchEntry

-> m Word32

Returns: a delay in milliseconds.

Get the delay to be used between the last keypress and the SearchEntry::searchChanged signal being emitted.

Since: 4.8

new

searchEntryNew

Arguments

:: (HasCallStack, MonadIO m)

=> m SearchEntry

Returns: a new GtkSearchEntry

Creates a GtkSearchEntry.

setKeyCaptureWidget

searchEntrySetKeyCaptureWidget

Arguments

:: (HasCallStack, MonadIO m, IsSearchEntry a, IsWidget b)

=> a

entry: a GtkSearchEntry

-> Maybe b

widget: a GtkWidget

-> m ()

Sets widget as the widget that entry will capture key events from.

Key events are consumed by the search entry to start or continue a search.

If the entry is part of a GtkSearchBar, it is preferable to call searchBarSetKeyCaptureWidget instead, which will reveal the entry in addition to triggering the search entry.

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.

setPlaceholderText

searchEntrySetPlaceholderText

Arguments

:: (HasCallStack, MonadIO m, IsSearchEntry a)

=> a

entry: a GtkSearchEntry

-> Maybe Text

text: the text to set as a placeholder

-> m ()

Sets the placeholder text associated with entry.

Since: 4.10

setSearchDelay

searchEntrySetSearchDelay

Arguments

:: (HasCallStack, MonadIO m, IsSearchEntry a)

=> a

entry: a GtkSearchEntry

-> Word32

delay: a delay in milliseconds

-> m ()

Set the delay to be used between the last keypress and the SearchEntry::searchChanged signal being emitted.

Since: 4.8

Properties

activatesDefault

Whether to activate the default widget when Enter is pressed.

constructSearchEntryActivatesDefault :: (IsSearchEntry o, MonadIO m) => Bool -> m (GValueConstruct o)

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

getSearchEntryActivatesDefault :: (MonadIO m, IsSearchEntry o) => o -> m Bool

Get the value of the “activates-default” property. When overloading is enabled, this is equivalent to

get searchEntry #activatesDefault

setSearchEntryActivatesDefault :: (MonadIO m, IsSearchEntry o) => o -> Bool -> m ()

Set the value of the “activates-default” property. When overloading is enabled, this is equivalent to

set searchEntry [ #activatesDefault := value ]

placeholderText

The text that will be displayed in the GtkSearchEntry when it is empty and unfocused.

clearSearchEntryPlaceholderText :: (MonadIO m, IsSearchEntry o) => o -> m ()

Set the value of the “placeholder-text” property to Nothing. When overloading is enabled, this is equivalent to

clear #placeholderText

constructSearchEntryPlaceholderText :: (IsSearchEntry o, MonadIO m) => Text -> m (GValueConstruct o)

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

getSearchEntryPlaceholderText :: (MonadIO m, IsSearchEntry o) => o -> m (Maybe Text)

Get the value of the “placeholder-text” property. When overloading is enabled, this is equivalent to

get searchEntry #placeholderText

setSearchEntryPlaceholderText :: (MonadIO m, IsSearchEntry o) => o -> Text -> m ()

Set the value of the “placeholder-text” property. When overloading is enabled, this is equivalent to

set searchEntry [ #placeholderText := value ]

searchDelay

The delay in milliseconds from last keypress to the search changed signal.

Since: 4.8

constructSearchEntrySearchDelay :: (IsSearchEntry o, MonadIO m) => Word32 -> m (GValueConstruct o)

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

getSearchEntrySearchDelay :: (MonadIO m, IsSearchEntry o) => o -> m Word32

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

get searchEntry #searchDelay

setSearchEntrySearchDelay :: (MonadIO m, IsSearchEntry o) => o -> Word32 -> m ()

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

set searchEntry [ #searchDelay := value ]

Signals

activate

type SearchEntryActivateCallback = IO ()

Emitted when the entry is activated.

The keybindings for this signal are all forms of the Enter key.

afterSearchEntryActivate :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntryActivateCallback) -> m SignalHandlerId

Connect a signal handler for the activate signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after searchEntry #activate callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSearchEntryActivate :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntryActivateCallback) -> m SignalHandlerId

Connect a signal handler for the activate signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on searchEntry #activate callback

nextMatch

type SearchEntryNextMatchCallback = IO ()

Emitted when the user initiates a move to the next match for the current search string.

This is a keybinding signal.

Applications should connect to it, to implement moving between matches.

The default bindings for this signal is Ctrl-g.

afterSearchEntryNextMatch :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntryNextMatchCallback) -> m SignalHandlerId

Connect a signal handler for the nextMatch signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after searchEntry #nextMatch callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSearchEntryNextMatch :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntryNextMatchCallback) -> m SignalHandlerId

Connect a signal handler for the nextMatch signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on searchEntry #nextMatch callback

previousMatch

type SearchEntryPreviousMatchCallback = IO ()

Emitted when the user initiates a move to the previous match for the current search string.

This is a keybinding signal.

Applications should connect to it, to implement moving between matches.

The default bindings for this signal is Ctrl-Shift-g.

afterSearchEntryPreviousMatch :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntryPreviousMatchCallback) -> m SignalHandlerId

Connect a signal handler for the previousMatch signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after searchEntry #previousMatch callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSearchEntryPreviousMatch :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntryPreviousMatchCallback) -> m SignalHandlerId

Connect a signal handler for the previousMatch signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on searchEntry #previousMatch callback

searchChanged

type SearchEntrySearchChangedCallback = IO ()

Emitted with a delay. The length of the delay can be changed with the SearchEntry:searchDelay property.

afterSearchEntrySearchChanged :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntrySearchChangedCallback) -> m SignalHandlerId

Connect a signal handler for the searchChanged signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after searchEntry #searchChanged callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSearchEntrySearchChanged :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntrySearchChangedCallback) -> m SignalHandlerId

Connect a signal handler for the searchChanged signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on searchEntry #searchChanged callback

searchStarted

type SearchEntrySearchStartedCallback = IO ()

Emitted when the user initiated a search on the entry.

afterSearchEntrySearchStarted :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntrySearchStartedCallback) -> m SignalHandlerId

Connect a signal handler for the searchStarted signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after searchEntry #searchStarted callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSearchEntrySearchStarted :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntrySearchStartedCallback) -> m SignalHandlerId

Connect a signal handler for the searchStarted signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on searchEntry #searchStarted callback

stopSearch

type SearchEntryStopSearchCallback = IO ()

Emitted when the user stops a search via keyboard input.

This is a keybinding signal.

Applications should connect to it, to implement hiding the search entry in this case.

The default bindings for this signal is Escape.

afterSearchEntryStopSearch :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntryStopSearchCallback) -> m SignalHandlerId

Connect a signal handler for the stopSearch signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after searchEntry #stopSearch callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSearchEntryStopSearch :: (IsSearchEntry a, MonadIO m) => a -> ((?self :: a) => SearchEntryStopSearchCallback) -> m SignalHandlerId

Connect a signal handler for the stopSearch signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on searchEntry #stopSearch callback