Button

The Button component in dill-pixel provides an interactive button implementation with support for different states, textures, sounds, and accessibility features.

Basic Usage

The simplest way to create a button is using the add.button() factory method:

const button = this.add.button({
  textures: {
    default: 'btn/blue',
    hover: 'btn/yellow',
    disabled: 'btn/grey',
  },
  sheet: 'ui',
});

Button Configuration

The button accepts several configuration options:

export type ButtonConfig = {
  id: string;
  textures: {
    default: TextureLike;
    hover?: TextureLike;
    active?: TextureLike;
    disabled?: TextureLike;
  };
  sounds?: {
    hover?: string;
    out?: string;
    down?: string;
    click?: string;
  };
  actions?: {
    hover?: ButtonActionOrCallback;
    out?: ButtonActionOrCallback;
    down?: ButtonActionOrCallback;
    click?: ButtonActionOrCallback;
  };
  textLabel?: { text: string; style?: object; type?: 'text' | 'html' | 'bitmap' };
  cursor: Cursor;
  disabledCursor: Cursor;
  sheet: SpriteSheetLike;
  enabled: boolean;
};

Button States

Buttons support multiple states with different textures:

• default: Normal state
• hover: When pointer is over the button
• active: When button is pressed
• disabled: When button is disabled

Event Handling

Buttons provide several signals for interaction:

// Click handling
button.onClick.connect(() => {
  console.log('Button clicked!');
});

// Other available signals
button.onDown.connect(() => {}); // Button pressed
button.onUp.connect(() => {}); // Button released
button.onOver.connect(() => {}); // Pointer entered
button.onOut.connect(() => {}); // Pointer exited

Adding a Label

You can easily add a text label to a button, either at creation time using the textLabel configuration property, or after creation using the addLabel() method. The label will be automatically centered on the button.

Using the textLabel configuration

The easiest way to add a label is to pass it in the button’s configuration.

const button = this.add.button({
  textures: { default: 'btn/blue' },
  sheet: 'ui',
  textLabel: {
    text: 'Click Me',
    style: {
      fontSize: 60,
      fill: 0xffffff,
    },
  },
});

The textLabel property accepts any valid Text, HTMLText, or BitmapText properties. You can specify the type of text using the type property ('text', 'html', or 'bitmap'). The default is 'text'.

Using the addLabel() method

You can also add or replace a label after the button has been created using the addLabel method.

const button = this.add.button({
  textures: { default: 'btn/blue' },
  sheet: 'ui',
});

// Add a text label
const label = button.addLabel({
  text: 'Click Me',
  style: {
    fontSize: 60,
    fill: 0xffffff,
  },
});

// You can update the label's properties later
label.text = 'Clicked!';

The addLabel method returns the created text object, so you can store a reference to it for later manipulation.

Accessing the Label

You can also access the label at any time using the textLabel getter on the button instance. This is useful if you created the label using the textLabel configuration option and didn’t store a reference to it.

const button = this.add.button({
  textures: { default: 'btn/blue' },
  sheet: 'ui',
  textLabel: {
    text: 'Initial Text',
    style: {
      fontSize: 60,
      fill: 0xffffff,
    },
  },
});

// Access the label later
if (button.textLabel) {
    button.textLabel.text = 'New Text';
}

Focus Management

Buttons automatically integrate with dill-pixel’s focus management system.

To enable focus management:

// Add focus layer in your scene
this.app.focus.addFocusLayer('my-scene');

// Add button to focus management
this.app.focus.add(button);

// Optional: Set custom focus order
button.tabIndex = 1;

Example: Interactive Menu

Here’s a complete example showing button usage in a menu:

import { Button, FlexContainer, Scene } from 'dill-pixel';
export default class MenuScene extends Scene {
  async initialize() {
    // Create focus layer
    this.app.focus.addFocusLayer(this.id);

    // Create container for buttons
    const container = this.add.flexContainer({
      gap: 20,
      justifyContent: 'center',
      alignItems: 'center',
    });

    // Create play button
    const playButton = container.add.button({
      textures: {
        default: 'btn/green',
        hover: 'btn/yellow',
        disabled: 'btn/grey',
      },
      textLabel: {
        text: 'Play',
        style: { fontSize: 60, fill: 0xffffff },
      },
      accessibleTitle: 'Play Game',
      scale: 0.65,
    });

    playButton.onClick.connectOnce(() => {
      this.app.exec.loadScene('game');
    });

    // Add to focus management
    this.app.focus.add(playButton);
  }
}