UISelector

Overview

The UISelector component provides a versatile selection interface with multiple lighting modes and layout directions. It's ideal for creating value selectors, level indicators, and interactive controls.

The UISelector component is implemented in Applications/Python/PikaPython/MatrixOS_UISelector.py with type hints in Applications/Python/PikaPython/_MatrixOS_UISelector.pyi.

---

Constructor

MatrixOS.UISelector()

class UISelector(UIComponent):
    def __init__(self) -> None

Creates a new selector component.

Example:

selector = UISelector()

---

Enumerations

UISelectorDirection

class UISelectorDirection:
    RIGHT_THEN_DOWN: int = 0
    DOWN_THEN_RIGHT: int = 1
    LEFT_THEN_DOWN: int = 2
    DOWN_THEN_LEFT: int = 3
    UP_THEN_RIGHT: int = 4
    RIGHT_THEN_UP: int = 5
    UP_THEN_LEFT: int = 6
    LEFT_THEN_UP: int = 7

UISelectorLitMode

class UISelectorLitMode:
    LIT_EQUAL: int = 0              # Light only the selected value
    LIT_LESS_EQUAL_THAN: int = 1    # Light all values <= selected
    LIT_GREATER_EQUAL_THAN: int = 2 # Light all values >= selected
    LIT_ALWAYS: int = 3             # Always light all positions

---

Behavior Functions

SetValueFunc

def SetValueFunc(self, getValueFunc: any) -> bool

Sets a function to get the current selector value.

Parameters:

• getValueFunc (function): Function returning current value

Returns:

• bool: True if successful

SetColorFunc

def SetColorFunc(self, colorFunc: any) -> bool

Sets a function to determine the selector color.

Parameters:

• colorFunc (function): Function returning current color

Returns:

• bool: True if successful

SetIndividualColorFunc

def SetIndividualColorFunc(self, individualColorFunc: any) -> bool

Sets a function to determine individual position colors.

Parameters:

• individualColorFunc (function): Function returning color for each position

Returns:

• bool: True if successful

SetNameFunc

def SetNameFunc(self, nameFunc: any) -> bool

Sets a function to determine the selector name.

Parameters:

• nameFunc (function): Function returning current name

Returns:

• bool: True if successful

---

Configuration Methods

SetLitMode

def SetLitMode(self, litMode: int) -> bool

Sets the lighting mode for the selector.

Parameters:

• litMode (int): Lighting mode from UISelectorLitMode

Returns:

• bool: True if successful

SetDimension

def SetDimension(self, dimension: Dimension) -> bool

Sets the size of the selector.

Parameters:

• dimension (Dimension): Selector dimensions

Returns:

• bool: True if successful

SetName

def SetName(self, name: str) -> bool

Sets the selector name.

Parameters:

• name (str): Selector name

Returns:

• bool: True if successful

SetCount

def SetCount(self, count: int) -> bool

Sets the number of selectable positions.

Parameters:

• count (int): Number of positions

Returns:

• bool: True if successful

SetDirection

def SetDirection(self, direction: int) -> bool

Sets the layout direction for the selector.

Parameters:

• direction (int): Direction from UISelectorDirection

Returns:

• bool: True if successful

SetColor

def SetColor(self, color: Color) -> bool

Sets the base color for the selector.

Parameters:

• color (Color): Base color

Returns:

• bool: True if successful

---

Callback Functions

OnChange

def OnChange(self, changeCallback: any) -> bool

Sets a callback function for when the selection changes.

Parameters:

• changeCallback (function): Function called on value change

Returns:

• bool: True if successful

---

Usage Examples

Basic Volume Selector

def create_volume_selector():
    """Create a horizontal volume selector"""

    volume_level = 5  # Current volume (0-10)
    volume_selector = UISelector()

    # Configure the selector
    volume_selector.SetName("Volume")
    volume_selector.SetCount(11)  # 0-10 levels
    volume_selector.SetDirection(UISelectorDirection.RIGHT_THEN_DOWN)
    volume_selector.SetLitMode(UISelectorLitMode.LIT_LESS_EQUAL_THAN)
    volume_selector.SetDimension(Dimension(8, 1))  # Full width, 1 row
    volume_selector.SetColor(Color(0, 255, 0))

    # Value function
    def get_volume():
        return volume_level

    # Change callback
    def on_volume_change(new_value):
        nonlocal volume_level
        volume_level = new_value
        print(f"Volume changed to: {volume_level}")

    volume_selector.SetValueFunc(get_volume)
    volume_selector.OnChange(on_volume_change)

    ui = UI()
    ui.AddUIComponent(volume_selector, Point(0, 3))

    return ui, volume_selector

ui, vol_selector = create_volume_selector()
ui.Start()

Multi-Color Level Indicator

def create_level_indicator():
    """Create a level indicator with color coding"""

    current_level = 0
    max_level = 16
    level_selector = UISelector()

    level_selector.SetName("Level")
    level_selector.SetCount(max_level)
    level_selector.SetDirection(UISelectorDirection.DOWN_THEN_RIGHT)
    level_selector.SetLitMode(UISelectorLitMode.LIT_LESS_EQUAL_THAN)
    level_selector.SetDimension(Dimension(4, 4))

    # Dynamic color based on level
    def get_level_color():
        if current_level < 4:
            return Color(0, 255, 0)    # Green - low
        elif current_level < 8:
            return Color(255, 255, 0)  # Yellow - medium
        elif current_level < 12:
            return Color(255, 100, 0)  # Orange - high
        else:
            return Color(255, 0, 0)    # Red - maximum

    # Individual color function for gradient effect
    def get_individual_colors(position):
        ratio = position / (max_level - 1)
        red = int(255 * ratio)
        green = int(255 * (1 - ratio))
        return Color(red, green, 0)

    level_selector.SetValueFunc(lambda: current_level)
    level_selector.SetColorFunc(get_level_color)
    level_selector.SetIndividualColorFunc(get_individual_colors)

    def on_level_change(new_level):
        nonlocal current_level
        current_level = new_level
        print(f"Level: {current_level}/{max_level}")

    level_selector.OnChange(on_level_change)

    ui = UI()
    ui.AddUIComponent(level_selector, Point(2, 2))

    return ui, level_selector

ui, level_sel = create_level_indicator()
ui.Start()

EQ Band Selector

def create_eq_selector():
    """Create an equalizer-style selector"""

    eq_bands = [0, 2, 5, 8, 5, 3, 1, 0]  # 8 frequency bands
    current_band = 0
    eq_selector = UISelector()

    eq_selector.SetName("EQ")
    eq_selector.SetCount(len(eq_bands))
    eq_selector.SetDirection(UISelectorDirection.RIGHT_THEN_DOWN)
    eq_selector.SetLitMode(UISelectorLitMode.LIT_EQUAL)  # Only light selected band
    eq_selector.SetDimension(Dimension(8, 1))

    # Color based on EQ level
    def get_eq_color():
        current_level = eq_bands[current_band]
        if current_level > 6:
            return Color(255, 0, 0)    # Red - boost
        elif current_level > 3:
            return Color(255, 255, 0)  # Yellow - slight boost
        elif current_level == 0:
            return Color(255, 255, 255) # White - flat
        else:
            return Color(0, 255, 255)  # Cyan - cut

    # Individual colors show EQ curve
    def get_band_colors(position):
        level = eq_bands[position]
        intensity = (level + 1) * 25  # Scale to 0-255
        return Color(0, intensity, intensity)

    eq_selector.SetValueFunc(lambda: current_band)
    eq_selector.SetColorFunc(get_eq_color)
    eq_selector.SetIndividualColorFunc(get_band_colors)

    def on_band_change(new_band):
        nonlocal current_band
        current_band = new_band
        print(f"Selected band {current_band}: {eq_bands[current_band]} dB")

    eq_selector.OnChange(on_band_change)

    ui = UI()
    ui.AddUIComponent(eq_selector, Point(0, 3))

    return ui, eq_bands, eq_selector

ui, bands, eq_sel = create_eq_selector()
ui.Start()

Pattern Step Sequencer

def create_step_sequencer():
    """Create a 16-step sequencer pattern selector"""

    pattern = [True, False, True, False, True, False, True, False,
               False, True, False, True, False, True, False, True]
    current_step = 0
    playing = False

    step_selector = UISelector()
    step_selector.SetName("Steps")
    step_selector.SetCount(16)
    step_selector.SetDirection(UISelectorDirection.RIGHT_THEN_DOWN)
    step_selector.SetLitMode(UISelectorLitMode.LIT_ALWAYS)  # Show all steps
    step_selector.SetDimension(Dimension(8, 2))  # 8x2 grid for 16 steps

    # Color coding for steps
    def get_step_colors(position):
        if position == current_step and playing:
            return Color(255, 255, 255)  # White - current playing step
        elif pattern[position]:
            return Color(0, 255, 0)      # Green - active step
        else:
            return Color(100, 0, 0)      # Dark red - inactive step

    step_selector.SetValueFunc(lambda: current_step)
    step_selector.SetIndividualColorFunc(get_step_colors)

    def on_step_change(new_step):
        nonlocal current_step
        current_step = new_step
        # Toggle step on/off
        pattern[current_step] = not pattern[current_step]
        print(f"Step {current_step}: {'ON' if pattern[current_step] else 'OFF'}")

    step_selector.OnChange(on_step_change)

    ui = UI()
    ui.AddUIComponent(step_selector, Point(0, 3))

    return ui, pattern, step_selector

ui, seq_pattern, step_sel = create_step_sequencer()
ui.Start()

Dynamic Range Selector

def create_range_selector():
    """Create a selector with dynamic range and labeling"""

    current_value = 50
    min_value = 0
    max_value = 100
    range_selector = UISelector()

    # Dynamic configuration
    def update_selector_config():
        range_size = max_value - min_value + 1
        range_selector.SetCount(min(range_size, 64))  # Limit to grid size

        # Update name with current range
        range_selector.SetNameFunc(lambda: f"Range {min_value}-{max_value}")

    range_selector.SetDirection(UISelectorDirection.RIGHT_THEN_DOWN)
    range_selector.SetLitMode(UISelectorLitMode.LIT_LESS_EQUAL_THAN)
    range_selector.SetDimension(Dimension(8, 8))

    # Normalize value to selector range
    def get_normalized_value():
        if max_value == min_value:
            return 0
        normalized = (current_value - min_value) / (max_value - min_value)
        return int(normalized * (range_selector.count - 1))

    # Color based on percentage
    def get_range_color():
        percentage = (current_value - min_value) / max(1, max_value - min_value)
        if percentage < 0.3:
            return Color(255, 0, 0)      # Red - low
        elif percentage < 0.7:
            return Color(255, 255, 0)    # Yellow - medium
        else:
            return Color(0, 255, 0)      # Green - high

    range_selector.SetValueFunc(get_normalized_value)
    range_selector.SetColorFunc(get_range_color)

    def on_range_change(new_position):
        nonlocal current_value
        if range_selector.count > 0:
            ratio = new_position / (range_selector.count - 1)
            current_value = int(min_value + ratio * (max_value - min_value))
            print(f"Value: {current_value} ({ratio*100:.1f}%)")

    range_selector.OnChange(on_range_change)

    update_selector_config()

    ui = UI()
    ui.AddUIComponent(range_selector, Point(0, 0))

    return ui, range_selector

ui, range_sel = create_range_selector()
ui.Start()

---

Lighting Mode Examples

LIT_EQUAL (Single Selection)

# Shows only the selected position
selector.SetLitMode(UISelectorLitMode.LIT_EQUAL)
# Use for: Radio buttons, single item selection

LIT_LESS_EQUAL_THAN (Fill Mode)

# Shows all positions up to and including selected
selector.SetLitMode(UISelectorLitMode.LIT_LESS_EQUAL_THAN)
# Use for: Volume bars, progress indicators, level meters

LIT_GREATER_EQUAL_THAN (Reverse Fill)

# Shows selected position and all higher positions
selector.SetLitMode(UISelectorLitMode.LIT_GREATER_EQUAL_THAN)
# Use for: Countdown displays, remaining capacity

LIT_ALWAYS (Show All)

# Shows all positions with different colors
selector.SetLitMode(UISelectorLitMode.LIT_ALWAYS)
# Use for: Pattern editors, multi-state displays