# Search a category screen

> Let players find a row across every category by what they type, with a gamepad, a keyboard, a mouse or touch, and use the text field and on-screen keyboard in...

Product: Rolly Save 1.0.0 | Sheet: guide | Updated: 2026-10-31 | HTML: https://rolly-docs.pages.dev/save/guides/search/

## What players get

![Typing with a gamepad](https://rolly-docs.pages.dev/save/_files/Images/Search_Typing_Tabs.png "Typing with a gamepad: the field, the results as real rows with their place, the on-screen keyboard and its prompts.")

| Action | Gamepad | Keyboard | Mouse | Touch |
|---|---|---|---|---|
| Open search | right stick button | Ctrl+F | click the entry | tap the entry |
| Type | the on-screen keyboard: A types, X deletes (held, it repeats), Y types a space, B ends typing | type | click keys | tap keys |
| To the results | B, or the keyboard's Done | Escape, Enter or Down | click a result | tap a result |
| Go to a result's row | A | Enter | click its name or caption | tap its name or caption |

- Results are the real rows, ranked: the name starts with the query, then a word of the name, another name, an option, the category or section, the description. Each result's caption says where it lives and, when the name did not match, what did. Left and Right change a result's value in place.
- Every word typed has to start a word of the row's texts; capitals and accents do not matter. Languages written without spaces (Chinese, Japanese, Thai) match inside words.
- The query stays for the session, per player. Back leaves search for the category and row the player was on (the side rail goes back to the search entry, the couch hub to the hub). Menu closes the screen from any phase.
- Letter shortcuts (Q, E, F, R) do not fire while the field has the keyboard, and Ctrl+F never applies.
- The keyboard's letters follow the interface language: QWERTY, AZERTY for French, QWERTZ for German, Czech, Slovak and Hungarian, the Russian and Greek layouts, and a grid of the text's letters for other alphabets. Letters the text uses that a layout lacks get one more row. Chinese, Japanese and Korean get no keys: search opens on the sorted list of every row.

![Results in the side rail](https://rolly-docs.pages.dev/save/_files/Images/Search_Results_Rail.png "Results in the side rail: the search entry selected, each result's caption naming what matched, the focused result's detail.")

## Offer search in your category screen

A screen derived from `URollySaveCoreUICategoryScreen` offers search once it describes its rows. **Search Mode** (class defaults, category Search) decides when: Auto shows the entry while the screen has two or more categories and 20 or more searchable rows; On and Off force it. **Search Keys** holds the keys that open it (a keyboard key needs Ctrl).

```cpp
// The rows search can find, in the screen's order: only rows and categories that show.
void UMyCodexScreen::CollectSearchEntries(TArray<FRollySaveCoreUISearchEntry>& OutEntries) const
{
	for (const FMyEntry& Data : Entries)
	{
		FRollySaveCoreUISearchEntry& Entry = OutEntries.AddDefaulted_GetRef();
		Entry.CategoryIndex = Data.Category;
		Entry.RowId = Data.Id;                  // the row's Get Row Id
		Entry.Name = Data.Name;                 // as the player sees it
		Entry.Description = Data.Description;
		Entry.Section = Data.Section;           // the heading it sits under, or empty
		Entry.Keywords = Data.OtherNames;       // "fps" for Frame Rate Limit
	}
}

// The real row of an entry, made in this screen's widget tree (search adds it to the list).
URollySaveCoreUIRow* UMyCodexScreen::BuildSearchRow(const FRollySaveCoreUISearchEntry& Entry)
{
	return MakeRowFor(Entry.RowId);
}
```

- `CarrySearchRowState` passes a result's state to its row when the player goes to it (a key row's picked column).
- The texts search shows are generic ("12 results"); override `MakeSearchCount`, `MakeSearchAllCount`, `GetSearchEmptyMessage`, `MakeSearchNoMatch`, `GetSearchRule` and `MakeSearchLimit` to name your rows ("12 settings").
- Call `RebuildRows` when rows show or hide: while search shows it refreshes the results instead.
- A Blueprint layout of the whole screen gets search by binding the parts `SearchField` (and `SearchEntry`, `SearchCount`, `SearchMessage`, `SearchRule`, `SearchHint`, `Keyboard` where it wants them).

## Keyboard rows of your own

Project Settings > Plugins > **Rolly Save Core UI** > **Keyboard Layouts** maps a culture ("pt", or "pt-BR" for one region) to letter rows, top to bottom, each written as its keys' characters ("qwertyuiop"). The digits come first by themselves. A culture you list replaces the built-in rows.

## The text field and keyboard in screens of your own

The palette's Rolly Save Core category has **Rolly Text Field** and **Rolly Keyboard**. A field shows a placeholder (**Field Name**), the caret while it is active, the key that opens it while empty, and a clear button; **Max Length** adds a counter. A physical keyboard types into it with the platform's input method; give a gamepad player the keyboard:

```cpp
NameField->SetActive(true, /*bPhysicalKeyboard*/ false);
Keyboard->SetMode(ERollySaveCoreUIKeyboardMode::Name);      // capitals after a space, LT is Shift
Keyboard->SetLayout(FRollySaveCoreUIKeyboardLayouts::Resolve(TEXT("en"), {}));
Keyboard->SetTarget(NameField);
Keyboard->FocusFirstKey();
Keyboard->OnDone().AddUObject(this, &UMyNameScreen::HandleNameDone);
```

## Limits

- A small area makes room for the keyboard: at short heights the field takes the navigation line while searching, and where the area hides the title the header's actions sit at the end of the navigation line (a Side Rail gives them a line of their own above its search field, at any height); in a narrow area the header's field is 280 units wide; in a short narrow area (960 x 540) one line names the first results and the footer hides while the keyboard shows; at tiny heights only the field and the keyboard show until typing ends.
- Steam's own on-screen keyboard needs Steamworks: a game that wants it replaces the Rolly keyboard with its own call.