跳到主要内容
版本：Matrix OS 3.2 Beta

KeyInfo

概述​

KeyInfo 类包含关于按键状态的详细信息，包括时间数据、力度/压力和活动状态。它提供查询按键行为和检测各种输入模式的方法。

Python KeyInfo 类实现位于 Applications/Python/PikaPython/MatrixOS_KeyInfo.py，类型提示位于 Applications/Python/PikaPython/_MatrixOS_KeyInfo.pyi。

Constructor​

KeyInfo(*val)​

def __init__(self, *val) -> None

Creates a KeyInfo instance with variable arguments.

Parameters:

  • *val: Variable arguments for initialization

方法​

State​

def State(self) -> int

获取当前按键状态值。

返回值：

  • int：按键状态（对应 KeyState 枚举值）

Force​

def Force(self) -> float

Gets the force/pressure applied to the key.

Returns:

  • float: Force value (0.0 to 1.0)

Value​

def Value(self, index: int = 0) -> float

Gets a specific value from the key information.

Parameters:

  • index (int, optional): Value index (default: 0)

Returns:

  • float: Value at specified index

LastEventTime​

def LastEventTime(self) -> int

Gets the timestamp of the last key event.

Returns:

  • int: Timestamp in milliseconds of the last event

Hold​

def Hold(self) -> bool

Checks if the key is being held down.

Returns:

  • bool: True if key is being held, False otherwise

Active​

def Active(self) -> bool

Checks if the key is currently active (pressed).

Returns:

  • bool: True if key is active/pressed, False otherwise

HoldTime​

def HoldTime(self) -> int

Gets the duration the key has been held down.

Returns:

  • int: Hold duration in milliseconds

__bool__​

def __bool__(self) -> bool

Allows KeyInfo to be used in boolean contexts.

Returns:

  • bool: True if KeyInfo represents a valid key state

Usage Examples​

Force-Based LED Response​

def force_led_response():
    """Change LED colors based on key force"""
    print("Press keys with different force levels...")

    while True:
        key_event = MatrixOS.KeyPad.Get(50)

        if key_event:
            key_info = key_event.KeyInfo()
            xy = MatrixOS.KeyPad.ID2XY(key_event.ID())

            if key_info.Active():
                force = key_info.Force()

                # Map force to color intensity
                if force > 0.9:
                    color = Color(255, 255, 255)  # White for maximum force
                elif force > 0.7:
                    color = Color(255, 0, 0)      # Red for high force
                elif force > 0.5:
                    color = Color(255, 128, 0)    # Orange for medium force
                elif force > 0.3:
                    color = Color(255, 255, 0)    # Yellow for light force
                else:
                    color = Color(0, 255, 0)      # Green for minimal force

                MatrixOS.LED.SetColor(xy, color)
                print(f"Force: {force:.2f} at ({xy.X()},{xy.Y()})")
            else:
                # Key released
                MatrixOS.LED.SetColor(xy, Color(0, 0, 0))

            MatrixOS.LED.Update()

force_led_response()

Hold Time Detection​

def hold_time_detector():
    """Perform different actions based on hold time"""

    active_keys = {}

    def check_hold_actions(key_id, key_info):
        """Check and execute hold-based actions"""
        if key_info.Hold():
            hold_time = key_info.HoldTime()
            xy = MatrixOS.KeyPad.ID2XY(key_id)

            if hold_time > 3000:
                # Very long hold - white
                MatrixOS.LED.SetColor(xy, Color(255, 255, 255))
                if key_id not in active_keys or active_keys[key_id] != "very_long":
                    print(f"Very long hold: {hold_time}ms")
                    active_keys[key_id] = "very_long"

            elif hold_time > 2000:
                # Long hold - magenta
                MatrixOS.LED.SetColor(xy, Color(255, 0, 255))
                if key_id not in active_keys or active_keys[key_id] != "long":
                    print(f"Long hold: {hold_time}ms")
                    active_keys[key_id] = "long"

            elif hold_time > 1000:
                # Medium hold - blue
                MatrixOS.LED.SetColor(xy, Color(0, 0, 255))
                if key_id not in active_keys or active_keys[key_id] != "medium":
                    print(f"Medium hold: {hold_time}ms")
                    active_keys[key_id] = "medium"

            elif hold_time > 500:
                # Short hold - cyan
                MatrixOS.LED.SetColor(xy, Color(0, 255, 255))
                if key_id not in active_keys or active_keys[key_id] != "short":
                    print(f"Short hold: {hold_time}ms")
                    active_keys[key_id] = "short"

    print("Hold time detector - hold keys for different durations")

    while True:
        key_event = MatrixOS.KeyPad.Get(50)

        if key_event:
            key_id = key_event.ID()
            key_info = key_event.KeyInfo()
            xy = MatrixOS.KeyPad.ID2XY(key_id)

            if key_info.Active():
                check_hold_actions(key_id, key_info)
            else:
                # Key released
                if key_id in active_keys:
                    del active_keys[key_id]
                MatrixOS.LED.SetColor(xy, Color(0, 0, 0))

            MatrixOS.LED.Update()

hold_time_detector()

Key State Analysis​

def analyze_key_states():
    """Detailed analysis of key state information"""

    state_history = {}

    def log_key_details(key_id, key_info):
        """Log detailed key information"""
        current_time = MatrixOS.SYS.Millis()

        info = {
            "time": current_time,
            "state": key_info.State(),
            "active": key_info.Active(),
            "hold": key_info.Hold(),
            "force": key_info.Force(),
            "value": key_info.Value(0),
            "last_event": key_info.LastEventTime(),
            "hold_time": key_info.HoldTime() if key_info.Hold() else 0
        }

        # Store in history
        if key_id not in state_history:
            state_history[key_id] = []

        state_history[key_id].append(info)

        # Keep only recent history
        if len(state_history[key_id]) > 10:
            state_history[key_id] = state_history[key_id][-10:]

        # Print current state
        xy = MatrixOS.KeyPad.ID2XY(key_id)
        print(f"Key {key_id} at ({xy.X()},{xy.Y()}):")
        print(f"  State: {info['state']}")
        print(f"  Active: {info['active']}")
        print(f"  Force: {info['force']:.3f}")
        print(f"  Value[0]: {info['value']:.3f}")

        if info['hold']:
            print(f"  Hold time: {info['hold_time']}ms")

        print(f"  Last event: {current_time - info['last_event']}ms ago")
        print("---")

    print("Key state analyzer - detailed key information")

    while True:
        key_event = MatrixOS.KeyPad.Get(50)

        if key_event:
            key_id = key_event.ID()
            key_info = key_event.KeyInfo()

            if key_info:  # Check if valid KeyInfo
                log_key_details(key_id, key_info)

                # Visual feedback based on state
                xy = MatrixOS.KeyPad.ID2XY(key_id)
                if key_info.Active():
                    # Color based on force
                    force = key_info.Force()
                    red = int(255 * force)
                    green = int(255 * (1 - force))
                    MatrixOS.LED.SetColor(xy, Color(red, green, 0))
                else:
                    MatrixOS.LED.SetColor(xy, Color(0, 0, 0))

                MatrixOS.LED.Update()

analyze_key_states()

Multi-Value Key Monitoring​

def multi_value_monitor():
    """Monitor multiple values from key events"""

    print("Multi-value key monitor")

    while True:
        key_event = MatrixOS.KeyPad.Get(50)

        if key_event:
            key_info = key_event.KeyInfo()
            key_id = key_event.ID()
            xy = MatrixOS.KeyPad.ID2XY(key_id)

            if key_info.Active():
                # Read multiple values
                value0 = key_info.Value(0)
                value1 = key_info.Value(1)
                force = key_info.Force()

                print(f"Key {key_id} at ({xy.X()},{xy.Y()}):")
                print(f"  Force: {force:.3f}")
                print(f"  Value[0]: {value0:.3f}")
                print(f"  Value[1]: {value1:.3f}")

                # Use force for LED brightness
                brightness_factor = max(0.1, force)  # Minimum 10% brightness
                color = Color(int(255 * brightness_factor), 0, 0)
                MatrixOS.LED.SetColor(xy, color)
            else:
                MatrixOS.LED.SetColor(xy, Color(0, 0, 0))

            MatrixOS.LED.Update()

multi_value_monitor()

Performance Timing Analysis​

def timing_analysis():
    """Analyze key timing performance"""

    timing_data = {}

    while True:
        key_event = MatrixOS.KeyPad.Get(50)

        if key_event:
            key_id = key_event.ID()
            key_info = key_event.KeyInfo()
            current_time = MatrixOS.SYS.Millis()

            if key_id not in timing_data:
                timing_data[key_id] = {
                    "press_count": 0,
                    "total_hold_time": 0,
                    "max_hold_time": 0,
                    "last_press_time": 0,
                    "intervals": []
                }

            data = timing_data[key_id]

            if key_info.Active():
                if data["last_press_time"] > 0:
                    interval = current_time - data["last_press_time"]
                    data["intervals"].append(interval)

                    # Keep only recent intervals
                    if len(data["intervals"]) > 20:
                        data["intervals"] = data["intervals"][-20:]

                data["last_press_time"] = current_time

                if key_info.Hold():
                    hold_time = key_info.HoldTime()
                    data["max_hold_time"] = max(data["max_hold_time"], hold_time)

            else:
                # Key released
                data["press_count"] += 1

                if key_info.Hold():
                    hold_time = key_info.HoldTime()
                    data["total_hold_time"] += hold_time

                # Print stats every 10 presses
                if data["press_count"] % 10 == 0:
                    xy = MatrixOS.KeyPad.ID2XY(key_id)
                    avg_hold = data["total_hold_time"] / data["press_count"]

                    print(f"Key ({xy.X()},{xy.Y()}) Statistics:")
                    print(f"  Presses: {data['press_count']}")
                    print(f"  Avg hold time: {avg_hold:.1f}ms")
                    print(f"  Max hold time: {data['max_hold_time']}ms")

                    if data["intervals"]:
                        avg_interval = sum(data["intervals"]) / len(data["intervals"])
                        print(f"  Avg press interval: {avg_interval:.1f}ms")
                    print("---")

timing_analysis()

Common Patterns​

State Checking​

# Check if key information is valid
key_info = key_event.KeyInfo()
if key_info:  # Uses __bool__ method
    # Process key info
    pass

Force-Based Actions​

def force_based_action(key_info):
    """Perform different actions based on key force"""
    if key_info.Active():
        force = key_info.Force()

        if force > 0.8:
            return "strong_press"
        elif force > 0.5:
            return "medium_press"
        else:
            return "light_press"
    return "not_pressed"

Hold Duration Classification​

def classify_hold(key_info):
    """Classify hold duration"""
    if key_info.Hold():
        hold_time = key_info.HoldTime()

        if hold_time > 2000:
            return "long_hold"
        elif hold_time > 500:
            return "short_hold"
        else:
            return "brief_hold"
    return "no_hold"

Value Array Access​

def read_multiple_values(key_info):
    """Read multiple values from key info"""
    values = []
    for i in range(3):  # Read first 3 values
        values.append(key_info.Value(i))
    return values

Comments