# 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 %}