Syntax Guide

For py5 Tutorial Creators

This guide shows all available interactive elements you can use in your worksheets. Everything here works with pure Markdown + HTML on GitHub and GitHub Pages - no setup required!


๐Ÿ“š Table of Contents


Basic Collapsible Sections

Simple Collapsible

Click to expand

This is hidden content that appears when clicked!

Syntax:

<details markdown="1">
  <summary>Click to expand</summary>

  This is hidden content that appears when clicked!
</details>

With Emoji Icons

๐ŸŽฏ Learning Objectives
  • Understand mouse events in py5
  • Create interactive graphics
  • Use variables to track state

Syntax:

<details markdown="1">
  <summary>๐ŸŽฏ Learning Objectives</summary>

  - Understand mouse events in py5 - Create interactive graphics - Use variables
  to track state
</details>

Hints System

Single Hint

๐Ÿ’ก Need a hint?

Remember that mouseX and mouseY give you the current mouse position. You can use these anywhere in your code!

Progressive Hints (Nested)

๐Ÿค” Stuck? Get hints here!
Hint 1: Where should the circle appear?

The circle should follow your mouse cursor. Think about which variables give you the mouse positionโ€ฆ

Hint 2: Still stuck?

Youโ€™ll need to use mouseX for the x-coordinate and mouseY for the y-coordinate of your circle.

Hint 3: Final hint!

Replace the fixed numbers in circle(200, 200, 50) with circle(mouseX, mouseY, 50)

Syntax for nested hints:

<details markdown="1">
  <summary>๐Ÿค” Stuck? Get hints here!</summary>

  <details markdown="1">
    <summary>Hint 1: Where should the circle appear?</summary>

    The circle should follow your mouse cursor...

    <details markdown="1">
      <summary>Hint 2: Still stuck?</summary>

      You'll need to use `mouseX` and `mouseY`...
    </details>
  </details>
</details>

Solutions & Answers

Basic Solution

โœ… Show Solution
def setup():
    size(400, 400)

def draw():
    background(220)
    circle(mouseX, mouseY, 50)

Solution with Explanation

๐ŸŽ‰ Complete Solution & Explanation

The Code:

def setup():
    size(400, 400)
    background(255)

def draw():
    # Don't clear the background - create a painting effect!
    fill(random(255), random(255), random(255))
    circle(mouseX, mouseY, 20)

How it works:

  1. No background() in draw() - This means previous circles stay on screen
  2. random(255) - Generates random colors for each circle
  3. mouseX, mouseY - Makes circles appear at cursor position

Try moving your mouse slowly for a snake-like effect!


Progressive Challenges

Multi-Level Challenge

๐ŸŽฎ Challenge: Create a Click Counter Game

๐Ÿ“ Level 1: Basic Click Detection

Create a program that prints โ€œClick!โ€ to the console each time you click.

๐Ÿ’ก Need help?

Youโ€™ll need the mousePressed() function:

def mousePressed():
    print("Click!")
โœ… Solution
def setup():
    size(400, 400)

def draw():
    background(200)

def mousePressed():
    print("Click!")
๐Ÿ“ Level 2: Count the Clicks

Now make it count how many times youโ€™ve clicked and display the number on screen.

๐Ÿ’ก Need help?

Youโ€™ll need a global variable to store the count:

click_count = 0  # Define outside functions

def mousePressed():
    global click_count
    click_count += 1
โœ… Solution
click_count = 0

def setup():
    size(400, 400)
    textSize(32)

def draw():
    background(200)
    text(f"Clicks: {click_count}", 150, 200)

def mousePressed():
    global click_count
    click_count += 1
๐Ÿ“ Level 3: Add a Target

Draw a circle target. Only count clicks when the user clicks inside the circle!

โœ… Solution
click_count = 0
target_x = 200
target_y = 200
target_size = 50

def setup():
    size(400, 400)
    textSize(32)

def draw():
    background(200)

    # Draw target
    fill(255, 0, 0)
    circle(target_x, target_y, target_size)

    # Draw score
    fill(0)
    text(f"Score: {click_count}", 150, 50)

def mousePressed():
    global click_count
    # Check if click is inside circle
    distance = dist(mouseX, mouseY, target_x, target_y)
    if distance < target_size/2:
        click_count += 1

Interactive Checkpoints

Self-Check Questions

โœ“ Check Your Understanding

Question 1: What does `mouseX` represent?

Answer: mouseX represents the current horizontal (x) position of the mouse cursor within the sketch window, measured in pixels from the left edge.

Question 2: When does the `draw()` function run?

Answer: The draw() function runs continuously in a loop, approximately 60 times per second (60 FPS) by default, after setup() completes.

Question 3: How do you make something happen only when the mouse is clicked?

Answer: Use the mousePressed() function. This function is called once each time the mouse button is pressed down.

def mousePressed():
    # Your code here runs once per click
    print("Clicked!")

Code Examples & Explanations

Expandable Code Walkthroughs

๐Ÿ“– Example: Color-Changing Background

Complete Code:

bg_color = 0

def setup():
    size(400, 400)

def draw():
    background(bg_color)

def mousePressed():
    global bg_color
    bg_color = random(255)
๐Ÿ” Line-by-line explanation
  1. bg_color = 0 - Creates a global variable to store our background color (starts as black)

  2. def setup(): - Runs once at the start

    • size(400, 400) - Creates a 400x400 pixel window
  3. def draw(): - Runs repeatedly (60 times/second)

    • background(bg_color) - Fills the background with our stored color
  4. def mousePressed(): - Runs once each time mouse is clicked

    • global bg_color - Tells Python we want to modify the global variable
    • bg_color = random(255) - Sets background to a random grayscale value

Best Practices

๐Ÿ“Œ Tips for Using Collapsible Sections

View formatting tips
  1. Always leave a blank line after <summary> tags when using markdown inside
  2. Use clear, action-oriented labels like โ€œClick for hintโ€ or โ€œShow solutionโ€
  3. Use emoji sparingly but consistently:

    • ๐Ÿ’ก for hints
    • โœ… for solutions
    • ๐ŸŽฏ for objectives
    • ๐Ÿ“ for exercises
    • โš ๏ธ for warnings
    • ๐ŸŽฎ for challenges
  4. Structure hints progressively - from vague to specific
  5. Include โ€œTry it yourself first!โ€ messages before solutions

๐Ÿ“ Template for a Complete Exercise

View exercise template
## Exercise: [Name]

**Goal:** [What students will create]

### Instructions

[Step-by-step what to do]

<details markdown="1">
<summary>๐Ÿ’ก Hints</summary>

<details markdown="1">
<summary>Hint 1</summary>
[Gentle nudge]
</details>

<details markdown="1">
<summary>Hint 2</summary>
[More specific help]
</details>

</details>

<details markdown="1">
<summary>โœ… Solution</summary>

```python
# Complete solution code
```

How it works: [Explanation]

๐Ÿš€ Bonus Challenge

[Extension activity for fast finishers]


</details>

---

## Testing Your Worksheets

### โœจ Quick Test Checklist

<details markdown="1">
<summary>Before publishing, check these:</summary>

- [ ] All code blocks have proper syntax highlighting (```python)
- [ ] Hints progress from general to specific
- [ ] Solutions include explanations, not just code
- [ ] Tested on both GitHub and GitHub Pages
- [ ] Mobile-friendly (test on phone!)
- [ ] No nested details more than 3 levels deep
- [ ] All emoji render correctly
- [ ] Code is copy-pasteable

</details>

---

## Advanced Patterns

### Mix Content Types

<details markdown="1">
<summary>๐ŸŽจ Visual Reference: Color Values</summary>

| Color | RGB Code        | py5 Code          |
| ----- | --------------- | ----------------- |
| Red   | (255, 0, 0)     | `fill(255, 0, 0)` |
| Green | (0, 255, 0)     | `fill(0, 255, 0)` |
| Blue  | (0, 0, 255)     | `fill(0, 0, 255)` |
| White | (255, 255, 255) | `fill(255)`       |
| Black | (0, 0, 0)       | `fill(0)`         |

**Try it:**

```python
fill(255, 0, 0)  # Red
circle(200, 200, 100)

</details>

Troubleshooting Sections

๐Ÿ”ง Common Errors & Fixes
Error: "NameError: name 'mouseX' is not defined"

Cause: Youโ€™re trying to use mouseX outside of a py5 function.

Fix: Make sure youโ€™re using mouseX inside functions like draw() or mousePressed(), not at the top level of your code.

โŒ Wrong:

x = mouseX  # This won't work!

def draw():
    circle(x, 200, 50)

โœ… Correct:

def draw():
    x = mouseX  # Use it inside the function
    circle(x, 200, 50)
Error: "Nothing happens when I click"

Cause: Function name might be wrong.

Fix: Make sure itโ€™s mousePressed() not mouse_pressed() or mousepressed()


Happy teaching! Feel free to copy any of these patterns for your worksheets. ๐Ÿš€