> ## Documentation Index
> Fetch the complete documentation index at: https://cloud-docs.mentra.glass/llms.txt
> Use this file to discover all available pages before exploring further.

# Display Layouts

> Show content on the smart glasses display

## Overview

The glasses have a simple text-based display. The SDK provides several layout types through `session.layouts` to format content effectively.

<Note>
  **Display Limitations:**

  * Text only (no images)
  * Single color (green)
  * Limited screen size
  * 200-300ms minimum between updates
</Note>

## Available Layouts

### Text Wall

Simple full-screen text display:

```typescript theme={null}
await session.layouts.showTextWall('Hello World!');

// With options
await session.layouts.showTextWall('Important message', {
  durationMs: 5000  // Show for 5 seconds
});
```

### Double Text Wall

Split screen with top and bottom sections:

```typescript theme={null}
await session.layouts.showDoubleTextWall(
  'Temperature: 72°F',
  'Humidity: 45%'
);
```

### Reference Card

Structured layout with title and body:

```typescript theme={null}
await session.layouts.showReferenceCard({
  title: 'Meeting Reminder',
  text: '2:00 PM - Team Standup\nZoom Room 3'
});
```

### Dashboard Card

Left-right layout for key-value pairs:

```typescript theme={null}
await session.layouts.showDashboardCard({
  left: 'Speed',
  right: '65 mph'
});
```

### Clear View

Remove all content from display:

```typescript theme={null}
await session.layouts.clearView();
```

### Bitmap View (Advanced)

For custom pixel-level control:

```typescript theme={null}
const bitmap = new Uint8Array(400 * 240); // Width x Height
// Fill bitmap with pixel data...

await session.layouts.showBitmapView({
  width: 400,
  height: 240,
  bitmap: bitmap
});
```

## Display Options

All layout methods accept optional parameters:

```typescript theme={null}
interface DisplayOptions {
  durationMs?: number;      // How long to show (ms)
  priority?: 'LOW' | 'NORMAL' | 'HIGH';
  targetView?: 'MAIN' | 'DASHBOARD' | 'ALWAYS_ON';
}
```

## Text Formatting

### Line Breaks

Use `\n` for line breaks:

```typescript theme={null}
await session.layouts.showTextWall(
  'Line 1\nLine 2\nLine 3'
);
```

### Text Wrapping

Long text automatically wraps, but you can control it:

```typescript theme={null}
function wrapText(text: string, maxLength: number = 30): string {
  const words = text.split(' ');
  const lines = [];
  let currentLine = '';
  
  for (const word of words) {
    if (currentLine.length + word.length > maxLength) {
      lines.push(currentLine);
      currentLine = word;
    } else {
      currentLine += (currentLine ? ' ' : '') + word;
    }
  }
  
  if (currentLine) lines.push(currentLine);
  return lines.join('\n');
}

// Usage
const wrapped = wrapText('This is a very long text that needs wrapping');
await session.layouts.showTextWall(wrapped);
```

## Common Patterns

### Status Updates

```typescript theme={null}
// Show status briefly
async function showStatus(message: string) {
  await session.layouts.showTextWall(message, {
    durationMs: 2000
  });
}

// Usage
await showStatus('✓ Saved');
await showStatus('⚠ Connection lost');
await showStatus('✗ Error occurred');
```

### Menu System

```typescript theme={null}
class MenuSystem {
  private items: string[];
  private selectedIndex = 0;
  
  constructor(private session: AppSession, items: string[]) {
    this.items = items;
  }
  
  show() {
    const display = this.items.map((item, i) => 
      i === this.selectedIndex ? `> ${item}` : `  ${item}`
    ).join('\n');
    
    this.session.layouts.showTextWall(display);
  }
  
  next() {
    this.selectedIndex = (this.selectedIndex + 1) % this.items.length;
    this.show();
  }
  
  select() {
    return this.items[this.selectedIndex];
  }
}

// Usage
const menu = new MenuSystem(session, ['Home', 'Settings', 'About']);
menu.show();

session.events.onButtonPress((data) => {
  if (data.pressType === 'short') {
    menu.next();
  } else if (data.pressType === 'long') {
    const selected = menu.select();
    console.log(`Selected: ${selected}`);
  }
});
```

### Live Data Display

```typescript theme={null}
// Update display with live data
async function showLiveData(session: AppSession) {
  const data = await fetchData();
  
  await session.layouts.showReferenceCard({
    title: 'Live Stats',
    text: [
      `Users: ${data.users}`,
      `Messages: ${data.messages}`,
      `Updated: ${new Date().toLocaleTimeString()}`
    ].join('\n')
  });
}

// Update every 30 seconds
setInterval(() => {
  if (session.isConnected) {
    showLiveData(session);
  }
}, 30000);
```

## Dashboard Mode

For always-visible information:

```typescript theme={null}
// Enable dashboard
await session.dashboard.write({
  text: 'Translator Active'
});

// Set dashboard mode
await session.dashboard.mode.set({
  enabled: true,
  alwaysOn: true  // Keep visible even when other apps show content
});
```

## Rate Limiting

<Warning>
  The display can only update every 200-300ms. Rapid updates will be queued or dropped.
</Warning>

```typescript theme={null}
// Bad: Too many updates
for (let i = 0; i < 10; i++) {
  await session.layouts.showTextWall(`Count: ${i}`); // Will be throttled!
}

// Good: Batch updates
const results = await processAllItems();
await session.layouts.showTextWall(`Processed ${results.length} items`);
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep text concise">
    The display is small. Use short, clear messages:

    ```typescript theme={null}
    // Bad
    await session.layouts.showTextWall(
      'The current temperature reading from the sensor is seventy-two degrees'
    );

    // Good
    await session.layouts.showTextWall('72°F');
    ```
  </Accordion>

  <Accordion title="Use appropriate layouts">
    Choose the right layout for your content:

    ```typescript theme={null}
    // For simple messages
    session.layouts.showTextWall('Hello!');

    // For structured data
    session.layouts.showReferenceCard({
      title: 'Weather',
      text: 'Sunny, 72°F'
    });

    // For comparisons
    session.layouts.showDoubleTextWall(
      'Expected: 100',
      'Actual: 95'
    );
    ```
  </Accordion>

  <Accordion title="Handle display timeouts">
    Content disappears after the duration:

    ```typescript theme={null}
    // Show important message longer
    await session.layouts.showTextWall('Emergency Alert!', {
      durationMs: 10000  // 10 seconds
    });

    // Or refresh periodically
    const interval = setInterval(() => {
      session.layouts.showTextWall('Still active...');
    }, 4000);
    ```
  </Accordion>
</AccordionGroup>