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
- Hints System
- Solutions & Answers
- Progressive Challenges
- Interactive Checkpoints
- Code Examples & Explanations
- Best Practices
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:
- No background() in draw() - This means previous circles stay on screen
- random(255) - Generates random colors for each circle
- 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
-
bg_color = 0
- Creates a global variable to store our background color (starts as black) -
def setup():
- Runs once at the startsize(400, 400)
- Creates a 400x400 pixel window
-
def draw():
- Runs repeatedly (60 times/second)background(bg_color)
- Fills the background with our stored color
-
def mousePressed():
- Runs once each time mouse is clickedglobal bg_color
- Tells Python we want to modify the global variablebg_color = random(255)
- Sets background to a random grayscale value
Best Practices
๐ Tips for Using Collapsible Sections
View formatting tips
- Always leave a blank line after
<summary>
tags when using markdown inside - Use clear, action-oriented labels like โClick for hintโ or โShow solutionโ
-
Use emoji sparingly but consistently:
- ๐ก for hints
- โ for solutions
- ๐ฏ for objectives
- ๐ for exercises
- โ ๏ธ for warnings
- ๐ฎ for challenges
- Structure hints progressively - from vague to specific
- 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. ๐