# Screen

{% hint style="warning" %}
Quick Reference can help with simple issues or give you a basic understanding of the methods available, but it can never replace full documentation which is available [here](https://pydraw.graphics/api).
{% endhint %}

## Initialization

You can initialize a Screen by passing a width and height (in pixels), and you can also pass an optional title. The default title is: "pydraw".

```python
screen = Screen(800, 600)
screen = Screen(800, 600, 'Title')
```

## Title

The title may be set in the constructor, but can also be modified later with:

```python
screen.title(title)
```

## Size

The Screen maintains its width and height and is not resizable. The values are retrievable via:

```python
screen.width()
screen.height()
```

Also, you can resize the Screen manually with:

```python
screen.resize(width, height)
```

## Locations

The Screen contains some basic helper methods to quickly grab commonly used locations. You can access those locations via:

```python
screen.top_left()  # 0, 0
screen.top_right()  # width, 0
screen.center()  # width / 2, height / 2
screen.bottom_left()  # 0, height
screen.bottom_right()  # width, height
```

## Color

The Screen's background is white by default, but it can be modified (or retrieved) with:

```python
screen.color()  # Retrieve the current Color
screen.color(color)  # Set a new Color
```

{% hint style="info" %}
Note: Colors in pyDraw are wrapped with the [Color](https://docs.pydraw.graphics/quick-reference/color) class.
{% endhint %}

## Background Image

You can also set the background image of the screen with:

```python
screen.picture(image_file)
```

## Input

You can have the screen listen for input by calling this after defining input methods:

```python
screen.listen()
```

#### Example

```python
def mousedown(location, button):
    # input handling code

screen.listen()  # Register any input methods
```

Check the dedicated page for more info:

{% content-ref url="input" %}
[input](https://docs.pydraw.graphics/quick-reference/input)
{% endcontent-ref %}

## Scene Change

You can create Scenes which serve essentially as boxed up pyDraw programs that can be applied to the Screen!

```python
screen.scene(scene)  # will apply scene and override all previous input hooks
```

Get more info on the dedicated page:

{% content-ref url="scene" %}
[scene](https://docs.pydraw.graphics/quick-reference/scene)
{% endcontent-ref %}

## Alert

You can pop an alert up onto the screen with:

```python
screen.alert(text)  # Default title and buttons
screen.alert(text, title)  # Custom title, default buttons
screen.alert(text, title, accept_text, cancel_text)  # Custom

# Returns True for "accept" and False for "cancel
result = alert('some text')
print(result)  # True or False
```

## Text Input (Prompt)

You can initiate a prompt to collect user input simply:

```python
screen.prompt(text)  # Ask a question
screen.prompt(text, title)  # Specify a title for the dialog
```

## Mouse Location

You can retrieve the mouse's current (or last known) location like so:

```python
screen.mouse()
```

## Screen Capture

It is possible to capture the contents of the Screen and write it to a specified image file:

```python
screen.grab()  # Just get an image and give it a random name
screen.grab(filename)  # Specify a filename to save to
```

## Updating and Clearing

You can update/clear the screen as expected:

```python
screen.update()  # Update the screen to display new changes
screen.clear()  # Clear all objects off the Screen
```

## Reset

You can reset the screen, which removes all objects and input hooks:

```python
screen.reset()
```

## Sleeping and Delay

The Screen has the ability to delay the program by a specified amount in seconds, but will also calculate a deltaTime in order to keep program execution delays as consistent as possible:

```python
screen.sleep(seconds)
```

{% hint style="info" %}
This method can only be used while within a while loop, if you want to normally delay a program, you should call:

```python
import time
time.sleep(seconds)
```

{% endhint %}

## Removing Objects

Although a method exists on all objects to remove themselves, the Screen is also able to remove objects from itself:

```python
screen.remove(obj)
```

## Objects List

You can retrieve a list of all active objects (not including grid and helpers):

```python
screen.objects()  # Returns a tuple (immutable list) of all objects.
```

## Check if an Object Exists

You can check if an object is on the screen:

```python
screen.contains(obj)
```

## Grids and Helpers

Screens have a fairly advanced grid system, allowing you to specify the number of rows or columns, or optionally the size of each cell (the default size of the cells will be 50x50):

```python
screen.grid(rows, cols)  # Specify # of rows and cols
screen.grid(cellsize=(50, 50))  # Specify the cellsize

screen.toggle_grid(state)  # Toggle the grid's visibility
```

You can also activate helper-labels for coordinates like so (every 100 pixels):

```python
screen.grid(rows, cols, helpers=True)  # Label coordinates
```

{% hint style="warning" %}
Be careful when creating or destroying grids, as it is a somewhat intensive process.
{% endhint %}


---

# 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://docs.pydraw.graphics/quick-reference/screen.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.