SettingsListWidget

When to Use

Use SettingsListWidget for preference panels, configuration screens or any UI where the user picks values for a set of named options. For free-form text input, use InputWidget or EditorWidget. For picking a single item from a plain list, use SelectListWidget.

Basic Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

use Symfony\Component\Tui\Widget\SettingItem;
use Symfony\Component\Tui\Widget\SettingsListWidget;

$items = [
    new SettingItem(
        id: 'theme',
        label: 'Theme',
        currentValue: 'dark',
        description: 'Choose the color theme',
        values: ['dark', 'light', 'auto'],
    ),
    new SettingItem(
        id: 'font_size',
        label: 'Font Size',
        currentValue: '14',
        values: ['12', '14', '16', '18'],
    ),
];

$settings = new SettingsListWidget($items);
$tui->add($settings);
$tui->setFocus($settings);

Setting Items

Each SettingItem is defined with:

• id: a unique identifier for the setting.
• label: the display name shown in the list.
• currentValue: the initial value.
• description: optional help text shown when the item is selected.
• values: a list of allowed values for cycling. When empty, the item must use a submenu instead.
• submenu: a callable that creates a focusable widget for picking a value (see below).

Cycling Values

When an item has predefined values, the user cycles through them with Enter, Space, Left or Right:

1
2
3
4
5
6

new SettingItem(
    id: 'difficulty',
    label: 'Difficulty',
    currentValue: 'normal',
    values: ['easy', 'normal', 'hard'],
);

Submenus

For settings that require a richer picker (e.g. a search-and-select list), provide a submenu callable. The callable receives the current value and a done callback:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

new SettingItem(
    id: 'language',
    label: 'Language',
    currentValue: 'en',
    submenu: function (string $current, callable $done) {
        $list = new SelectListWidget([
            ['value' => 'en', 'label' => 'English'],
            ['value' => 'fr', 'label' => 'French'],
            ['value' => 'de', 'label' => 'German'],
        ]);

        return $list;
    },
);

The submenu widget must implement FocusableInterface. When it dispatches a SelectEvent, the selected value is applied. When it dispatches a CancelEvent, the change is discarded.

Reading and Updating Values

Read or update values programmatically:

1
2

$settings->getValue('theme');        // 'dark'
$settings->updateValue('theme', 'light');

Events

• SettingChangeEvent: Fired whenever a setting value changes (cycling or submenu selection):

  1
  2
  3
  4
  5
  6

  use Symfony\Component\Tui\Event\SettingChangeEvent;
  
  $settings->onChange(function (SettingChangeEvent $event) {
      $id = $event->getId();
      $newValue = $event->getValue();
  });

• CancelEvent: Fired when the user presses Escape or Ctrl+C:

  1
  2
  3

  $settings->onCancel(function () {
      // close the settings panel
  });

Default Keybindings