# Clipping And Scrolling (frames)

OSL provides a powerful frame system for clipping content and creating scrollable areas in your applications.

## Basic Clipping

The `frame` command lets you define a rectangular area that clips (masks) any content drawn inside it. Content outside the frame's boundaries will not be visible.

### Syntax

```javascript
frame left top right bottom (
    // Content to be clipped goes here
)
```

The frame boundaries are defined by four coordinates:

* `left`: Left edge position (x-coordinate)
* `top`: Top edge position (y-coordinate)
* `right`: Right edge position (x-coordinate)
* `bottom`: Bottom edge position (y-coordinate)

### Example: Basic Clipping

```javascript
// Define frame boundaries
left = -100
right = 100    // Creates a 200px wide frame
top = 100
bottom = -100  // Creates a 200px tall frame

mainloop:
    frame left top right bottom (
        // Draw a large square that will be clipped
        square 10000 10000 20
        // Only the portion within the 200x200 frame will be visible
    )
```

## Scrollable Frames

You can create scrollable areas in two ways:

1. Two-dimensional scrolling with content width and height
2. Vertical-only scrolling with just content height

### Two-Dimensional Scrolling Syntax

```javascript
frame left top right bottom [content_width, content_height] "frame_id" (
    // Scrollable content goes here
)
```

Additional parameters:

* `[content_width, content_height]`: Dimensions of the scrollable content area
* `"frame_id"`: Unique identifier for the scrollable frame

### Vertical-Only Scrolling Syntax

```javascript
frame left top right bottom content_height "frame_id" (
    // Vertically scrollable content goes here
)
```

Additional parameters:

* `content_height`: Total height of the scrollable content (integer)
* `"frame_id"`: Unique identifier for the scrollable frame

### Example: Two-Dimensional Scrolling

```javascript
// Style settings
text_size = 10
image_width = 150

mainloop:
    // Create a 200x200 frame with 1000x200 scrollable content
    frame -100 100 100 -100 [1000, 200] "my_scroll_frame" (
        // Position content using scroll coordinates
        goto scroll_x scroll_y
        
        // Add content that can scroll both horizontally and vertically
        text "Header Text" text_size
        change_y -20
        image my_image image_width
    )
```

### Example: Vertical-Only Scrolling

```javascript
mainloop:
    // Create a 200x200 frame with 500px scrollable height
    frame -100 100 100 -100 500 "vertical_scroll" (
        // Position content using scroll_y only
        goto 0 scroll_y
        
        // Add vertically scrolling content
        text "Title" text_size
        change_y -30
        
        text "Long content that scrolls vertically..." text_size
        change_y -20
        
        image my_image image_width
    )
```

## Important Notes

1. **Frame Coordinates**
   * Coordinates are relative to the center of the screen
   * Positive Y goes up, negative Y goes down
   * Frame size = (right - left) × (top - bottom)
2. **Scrolling Behavior**
   * Scrollbars appear automatically when content exceeds frame size
   * Scroll position is tracked via `scroll_x` and `scroll_y` variables or `frame.scroll` `frame.scroll_h` respectively
   * Content coordinates are relative to scroll position
3. **Best Practices**
   * Use meaningful frame IDs for easier management
   * Consider padding inside frames for better appearance
   * Update content layout based on scroll position
   * Clean up or reset scroll position when needed
4. **Common Use Cases**
   * Long text documents
   * Image galleries
   * Lists and menus
   * Content that exceeds screen size


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://osl.mistium.com/commands/rendering/clipping-and-scrolling-frames.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.