Skip to main content

Selection & Text

Coming from Sliders & Value Pickers, let's move from numeric values to text and lists of options.

Which one do you actually want?

If you need to...Reach for
Show static textLabel
Collect free-form text inputTextField
Store one choice from a fixed list of optionsSelectBox
Trigger an action from a list of choicesMenu

Label​

The simplest control on this whole page, but not a plain one: it holds and displays text with real styling support. Reach for one anywhere you need a caption, a heading inside a layout, or text that a screen reader should associate with another control — see accessibilityLabelProvider on the Accessibility page for that last case.

The simplest control on this whole page: shows a piece of static text. Reach for one anywhere you need a caption, a heading inside a layout, or text that a screen reader should associate with another control — see accessibilityLabelProvider on the Accessibility page for that last case.

Beyond plain text, a Label can hold StyledText for rich, per-span styling, wrap across multiple lines, align both horizontally and vertically, and adjust its own letter and line spacing — most of what you saw on the Text page, just packaged as a control instead of raw Canvas calls. It needs a LabelBehavior to render, same as everything else on this page.

info

Label requires a LabelBehavior to render. These examples use basicLabelBehavior.

TextField​

Single-line, editable text input — the one you'll use constantly. It manages its own focus automatically when styled with NativeTheme (Web, Desktop), which is why it was called out specifically back on User Input.

It's more configurable than it looks at first glance: set its purpose (Email, Telephone, a plain number, and so on) to get the platform-appropriate keyboard and input handling for free — this is exactly what the Telephone purpose was doing back in the Forms destructuring example, without it being explained there.

It is customizable via NativeTextFieldBehaviorModifier if you want to change its look while keeping the platform's native text-editing behavior underneath.

SelectBox​

Picks a single item from a list of options — a dropdown, in the presentation everyone expects. It's similar in spirit to SpinButton — both narrow a set of choices to one visible selection — but where SpinButton steps through values in place, SelectBox drops a whole list open when activated. Like SpinButton, its ListModel behaves like an Iterator, so the options don't all need to be loaded up front. It also takes two ItemVisualizers — one for how the selected item appears in the closed box, and a separate one for how each option appears in the open list.

MutableSelectBox lets you change its values directly, or by updating its underlying model.

tip

SelectBox shares List's model-driven design, even though it lives in its own package — worth a look at List if you need something closer to a full list than a compact dropdown.

A different flavor of "pick one from a list" — items you click to trigger an action, or open a nested sub-menu, rather than a dropdown field. Note that Menu itself is just the vertical list of items as a View; it doesn't handle showing itself as a popup — that's a separate, easy step using Popups & Modals, covered right after this code sample.

You build one with the declarative DSL on an injected MenuFactory:

Module Required

Include the MenuFactoryModule (Web, Desktop) in your application to use these features.

package controls import io.nacular.doodle.application.Application import io.nacular.doodle.application.Modules.Companion.MenuFactoryModule import io.nacular.doodle.application.application import io.nacular.doodle.controls.popupmenu.MenuFactory import io.nacular.doodle.core.Display import org.kodein.di.instance class MenuApp(display: Display, menus: MenuFactory): Application { override fun shutdown() {} } fun menusModule() { //sampleStart application(modules = listOf(MenuFactoryModule)) { MenuApp(display = instance(), menus = instance()) } //sampleEnd }
tip

This example adds a Menu straight to the Display as a top-level View. In practice, you'll often want one to appear on demand instead — anchored to a button, dismissed on an outside click. That's exactly what Popups & Modals is built for, and it's smart about it too: reposition the anchoring button around the screen, and a shown Menu adjusts where its popup opens to stay visible.

tip

Move the button around to see how the Menu adjusts the location of its popups to keep them visible as much as possible.

Recap​

  • Label shows static text; TextField collects editable text, and manages its own focus with NativeTheme (Web, Desktop).
  • SelectBox and Menu both narrow a list down to one choice — SelectBox when the options are a value to be stored, Menu when each option is really an action to trigger.

Next: on to Data Display for showing collections — lists, tables, and trees.