simple-graphics-lib 0.0.8__tar.gz → 0.0.9__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: simple-graphics-lib
3
- Version: 0.0.8
3
+ Version: 0.0.9
4
4
  Summary: A simple graphics library for python learners
5
5
  Author-email: Max-Hillyer <maxhillyer7012@gmail.com>
6
6
  License-Expression: MIT
@@ -63,6 +63,8 @@ Arguments:
63
63
  | height | int | the height of the rect | 10 |
64
64
  | color | str | the color of the rect | "black" |
65
65
  | outline | bool | whether the rect is just an outline | False |
66
+ | draggable | bool | whether the rect can be dragged | False |
67
+ | visible | bool | whether the rect is drawn on screen | True |
66
68
 
67
69
  Methods:
68
70
  | Method | Purpose | Arguments | Returns |
@@ -80,6 +82,8 @@ Arguments:
80
82
  | radius | int | the radius of the circle | 10 |
81
83
  | color | str | the color of the circle | "black" |
82
84
  | outline | bool | whether the circle is just an outline | False |
85
+ | draggable | bool | whether the circle can be dragged | False |
86
+ | visible | bool | whether the circle is drawn on screen | True |
83
87
 
84
88
  Methods:
85
89
  | Method | Purpose | Arguments | Returns |
@@ -94,6 +98,8 @@ Arguments:
94
98
  | points | list[tuple] | the vertices of the polygon | None |
95
99
  | color | str | the color of the polygon | "black" |
96
100
  | outline | bool | whther the polygon is just an outline | False |
101
+ | draggable | bool | whether the polygon can be dragged | False |
102
+ | visible | bool | whether the polygon is drawn on screen | True |
97
103
 
98
104
  Methods:
99
105
  | Method | Purpose | Arguments | Returns |
@@ -107,6 +113,8 @@ Arguments:
107
113
  | points | list[tuple] |the points that the line will connect | None |
108
114
  | width | int | the width of the line | 10 |
109
115
  | color | str | the color of the line | "black" |
116
+ | draggable | bool | whether the line can be dragged | False |
117
+ | visible | bool | whether the line is drawn on screen | True |
110
118
 
111
119
  Methods:
112
120
  | Method | Purpose | Arguments | Returns |
@@ -122,6 +130,8 @@ Arguments:
122
130
  | text | str | the text of the text | None |
123
131
  | color | str | the color of the text | "black" |
124
132
  | size | int | the size of the text | 36 |
133
+ | draggable | bool | whether the text can be dragged | False |
134
+ | visible | bool | whether the text is drawn on screen | True |
125
135
 
126
136
  Methods:
127
137
  | Method | Purpose | Arguments | Returns |
@@ -137,6 +147,8 @@ Arguments:
137
147
  | img_path | str | the path to the image | None |
138
148
  | width | int | the width of the image | the width from the image path |
139
149
  | height | int | the height of the image | the height from the image path |
150
+ | draggable | bool | whether the image can be dragged | False |
151
+ | visible | bool | whether the image is drawn on screen | True |
140
152
 
141
153
  Methods:
142
154
  | Method | Purpose | Arguments | Returns |
@@ -160,7 +172,8 @@ group.color = "green"
160
172
  Arguments:
161
173
  | Argument | Type | Role | Default |
162
174
  | :--- | :---: | :---: | ---: |
163
- | *shapes | list[Shape] | the shapes to group | None |
175
+ | *shapes | list[Shape] | the shapes to group | None |
176
+ | visible | bool | whether shapes in group are drawn on screen | True |
164
177
 
165
178
  Methods:
166
179
  | Method | Purpose | Arguments | Returns |
@@ -319,6 +332,20 @@ r1 = Rect(200,200, 100, 100)
319
332
  def p():
320
333
  print("hovering")
321
334
 
335
+ run(400,400)
336
+ ```
337
+
338
+ ### on_drag
339
+ functions defined with the `@on_drag` decorator will run whenever the specified object is being dragged
340
+
341
+ the function below will run whenevr the r1 rect is being dragged
342
+ ```python
343
+ r1 = Rect(200,200,draggable = True)
344
+
345
+ @on_drag(r1)
346
+ def do_something():
347
+ print("dragging r1")
348
+
322
349
  run(400,400)
323
350
  ```
324
351
  ---
@@ -47,6 +47,8 @@ Arguments:
47
47
  | height | int | the height of the rect | 10 |
48
48
  | color | str | the color of the rect | "black" |
49
49
  | outline | bool | whether the rect is just an outline | False |
50
+ | draggable | bool | whether the rect can be dragged | False |
51
+ | visible | bool | whether the rect is drawn on screen | True |
50
52
 
51
53
  Methods:
52
54
  | Method | Purpose | Arguments | Returns |
@@ -64,6 +66,8 @@ Arguments:
64
66
  | radius | int | the radius of the circle | 10 |
65
67
  | color | str | the color of the circle | "black" |
66
68
  | outline | bool | whether the circle is just an outline | False |
69
+ | draggable | bool | whether the circle can be dragged | False |
70
+ | visible | bool | whether the circle is drawn on screen | True |
67
71
 
68
72
  Methods:
69
73
  | Method | Purpose | Arguments | Returns |
@@ -78,6 +82,8 @@ Arguments:
78
82
  | points | list[tuple] | the vertices of the polygon | None |
79
83
  | color | str | the color of the polygon | "black" |
80
84
  | outline | bool | whther the polygon is just an outline | False |
85
+ | draggable | bool | whether the polygon can be dragged | False |
86
+ | visible | bool | whether the polygon is drawn on screen | True |
81
87
 
82
88
  Methods:
83
89
  | Method | Purpose | Arguments | Returns |
@@ -91,6 +97,8 @@ Arguments:
91
97
  | points | list[tuple] |the points that the line will connect | None |
92
98
  | width | int | the width of the line | 10 |
93
99
  | color | str | the color of the line | "black" |
100
+ | draggable | bool | whether the line can be dragged | False |
101
+ | visible | bool | whether the line is drawn on screen | True |
94
102
 
95
103
  Methods:
96
104
  | Method | Purpose | Arguments | Returns |
@@ -106,6 +114,8 @@ Arguments:
106
114
  | text | str | the text of the text | None |
107
115
  | color | str | the color of the text | "black" |
108
116
  | size | int | the size of the text | 36 |
117
+ | draggable | bool | whether the text can be dragged | False |
118
+ | visible | bool | whether the text is drawn on screen | True |
109
119
 
110
120
  Methods:
111
121
  | Method | Purpose | Arguments | Returns |
@@ -121,6 +131,8 @@ Arguments:
121
131
  | img_path | str | the path to the image | None |
122
132
  | width | int | the width of the image | the width from the image path |
123
133
  | height | int | the height of the image | the height from the image path |
134
+ | draggable | bool | whether the image can be dragged | False |
135
+ | visible | bool | whether the image is drawn on screen | True |
124
136
 
125
137
  Methods:
126
138
  | Method | Purpose | Arguments | Returns |
@@ -144,7 +156,8 @@ group.color = "green"
144
156
  Arguments:
145
157
  | Argument | Type | Role | Default |
146
158
  | :--- | :---: | :---: | ---: |
147
- | *shapes | list[Shape] | the shapes to group | None |
159
+ | *shapes | list[Shape] | the shapes to group | None |
160
+ | visible | bool | whether shapes in group are drawn on screen | True |
148
161
 
149
162
  Methods:
150
163
  | Method | Purpose | Arguments | Returns |
@@ -303,6 +316,20 @@ r1 = Rect(200,200, 100, 100)
303
316
  def p():
304
317
  print("hovering")
305
318
 
319
+ run(400,400)
320
+ ```
321
+
322
+ ### on_drag
323
+ functions defined with the `@on_drag` decorator will run whenever the specified object is being dragged
324
+
325
+ the function below will run whenevr the r1 rect is being dragged
326
+ ```python
327
+ r1 = Rect(200,200,draggable = True)
328
+
329
+ @on_drag(r1)
330
+ def do_something():
331
+ print("dragging r1")
332
+
306
333
  run(400,400)
307
334
  ```
308
335
  ---
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "simple-graphics-lib"
3
- version = "0.0.8"
3
+ version = "0.0.9"
4
4
  authors = [
5
5
  { name="Max-Hillyer", email="maxhillyer7012@gmail.com" },
6
6
  ]
@@ -12,6 +12,7 @@ _key_funcs = {}
12
12
  _key_hold_funcs = {}
13
13
  _mouse_click_funcs = {}
14
14
  _hover_funcs = {}
15
+ _dragging_funcs = {}
15
16
  _dragging_shape = None
16
17
  _bgcolor = "white"
17
18
  _font = "Arial"
@@ -20,6 +21,9 @@ pygame.init()
20
21
 
21
22
 
22
23
  class Mouse:
24
+ def __init__(self, hiding = False):
25
+ self.hiding = hiding
26
+
23
27
  @property
24
28
  def x(self):
25
29
  return pygame.mouse.get_pos()[0]
@@ -28,20 +32,37 @@ class Mouse:
28
32
  def y(self):
29
33
  return pygame.mouse.get_pos()[1]
30
34
 
35
+ def set_hiding(self, state: bool):
36
+ """Sets the mouse visibility"""
37
+ self.hiding = state
38
+ pygame.mouse.set_visible(self.hiding)
39
+
31
40
 
32
41
  mouse = Mouse()
33
42
 
34
43
 
35
44
  class Shape:
36
- def __init__(self, x, y, color="black", outline=False, draggable=False):
45
+ """Base class for all drawable shapes. Do not instantiate directly."""
46
+ def __init__(self, x, y, color="black", outline=False, draggable=False, visible = True):
47
+ """Initialize a shape at position (x, y).
48
+
49
+ Args:
50
+ x: X coordinate (pixels from left)
51
+ y: Y coordinate (pixels from top)
52
+ color: Color as hex string (#RRGGBB) or name (default: "black")
53
+ outline: If True, draw outline only; if False, fill shape (default: False)
54
+ draggable: If True, shape can be moved by mouse (default: False)
55
+ """
37
56
  self.x = x
38
57
  self.y = y
39
58
  self.color = color
40
59
  self.outline = int(outline)
41
60
  self.draggable = draggable
61
+ self.visible = visible
42
62
  _shapes.append(self)
43
63
 
44
64
  def __str__(self):
65
+ """Return string representation showing shape type and parameters"""
45
66
  class_name = self.__class__.__name__.lower()
46
67
  sig = signature(self.__init__)
47
68
  params = [p for p in sig.parameters if p != "self"]
@@ -63,8 +84,9 @@ class Rect(Shape):
63
84
  color: str = "black",
64
85
  outline: bool = False,
65
86
  draggable: bool = False,
87
+ visible : bool = True
66
88
  ):
67
- super().__init__(x, y, color, outline, draggable)
89
+ super().__init__(x, y, color, outline, draggable, visible)
68
90
  self.width = width
69
91
  self.height = height
70
92
 
@@ -73,6 +95,15 @@ class Rect(Shape):
73
95
  return (self.x, self.y, self.width, self.height)
74
96
 
75
97
  def is_obj_over(self, ox=None, oy=None):
98
+ """Check if a point is inside this rectangle.
99
+
100
+ Args:
101
+ ox: X coordinate (default: current mouse x)
102
+ oy: Y coordinate (default: current mouse y)
103
+
104
+ Returns:
105
+ bool: True if point is inside rectangle, False otherwise
106
+ """
76
107
  if ox == None:
77
108
  ox = pygame.mouse.get_pos()[0]
78
109
  if oy == None:
@@ -82,9 +113,11 @@ class Rect(Shape):
82
113
  return x_over and y_over
83
114
 
84
115
  def get_area(self):
116
+ """Calculate and return the area of the rectangle"""
85
117
  return self.width * self.height
86
118
 
87
119
  def get_perimeter(self):
120
+ """Calculate and return the perimeter of the rectangle"""
88
121
  return (2 * self.width) + (2 * self.height)
89
122
 
90
123
 
@@ -97,11 +130,21 @@ class Circle(Shape):
97
130
  color: str = "black",
98
131
  outline: bool = False,
99
132
  draggable: bool = False,
133
+ visible: bool = True
100
134
  ):
101
- super().__init__(x, y, color, outline, draggable)
135
+ super().__init__(x, y, color, outline, draggable, visible)
102
136
  self.radius = radius
103
137
 
104
138
  def is_obj_over(self, ox=None, oy=None):
139
+ """Check if a point is inside this circle.
140
+
141
+ Args:
142
+ ox: X coordinate (default: current mouse x)
143
+ oy: Y coordinate (default: current mouse y)
144
+
145
+ Returns:
146
+ bool: True if point is inside circle, False otherwise
147
+ """
105
148
  if ox == None:
106
149
  ox = pygame.mouse.get_pos()[0]
107
150
  if oy == None:
@@ -110,6 +153,7 @@ class Circle(Shape):
110
153
  return inside
111
154
 
112
155
  def get_area(self):
156
+ """Calculate and return the area of the circle."""
113
157
  return pi * self.radius**2
114
158
 
115
159
 
@@ -120,14 +164,25 @@ class Polygon(Shape):
120
164
  color: str = "black",
121
165
  outline: bool = False,
122
166
  draggable: bool = False,
167
+ visible: bool = True
123
168
  ):
124
169
  self.color = color
125
170
  self.points = points
126
171
  self.outline = int(outline)
127
172
  self.draggable = draggable
173
+ self.visible = visible
128
174
  _shapes.append(self)
129
175
 
130
176
  def is_obj_over(self, ox=None, oy=None):
177
+ """Check if a point is inside this polygon using ray casting algorithm.
178
+
179
+ Args:
180
+ ox: X coordinate (default: current mouse x)
181
+ oy: Y coordinate (default: current mouse y)
182
+
183
+ Returns:
184
+ bool: True if point is inside polygon, False otherwise
185
+ """
131
186
  if ox == None:
132
187
  ox = pygame.mouse.get_pos()[0]
133
188
  if oy == None:
@@ -157,14 +212,25 @@ class Line(Shape):
157
212
  width: int = 10,
158
213
  color: str = "black",
159
214
  draggable: bool = False,
215
+ visible: bool = True
160
216
  ):
161
217
  self.color = color
162
218
  self.points = points
163
219
  self.width = width
164
220
  self.draggable = draggable
221
+ self.visible = visible
165
222
  _shapes.append(self)
166
223
 
167
224
  def is_obj_over(self, ox=None, oy=None):
225
+ """Check if a point is near this line (within line width).
226
+
227
+ Args:
228
+ ox: X coordinate (default: current mouse x)
229
+ oy: Y coordinate (default: current mouse y)
230
+
231
+ Returns:
232
+ bool: True if point is within line width, False otherwise
233
+ """
168
234
  if ox == None:
169
235
  ox = pygame.mouse.get_pos()[0]
170
236
  if oy == None:
@@ -182,6 +248,7 @@ class Line(Shape):
182
248
  return False
183
249
 
184
250
  def _distance_to_segment(self, px, py, x1, y1, x2, y2):
251
+ """Calculate shortest distance from a point to a line segment."""
185
252
  dx = x2 - x1
186
253
  dy = y2 - y1
187
254
 
@@ -205,8 +272,9 @@ class Image(Shape):
205
272
  width: int = None,
206
273
  height: int = None,
207
274
  draggable: bool = False,
275
+ visible: bool = True
208
276
  ):
209
- super().__init__(x, y, draggable)
277
+ super().__init__(x, y, draggable, visible)
210
278
  self.img_path = img_path
211
279
  self.original_img = pygame.image.load(self.img_path)
212
280
 
@@ -219,6 +287,15 @@ class Image(Shape):
219
287
  )
220
288
 
221
289
  def is_obj_over(self, ox=None, oy=None):
290
+ """Check if a point is inside this image rectangle.
291
+
292
+ Args:
293
+ ox: X coordinate (default: current mouse x)
294
+ oy: Y coordinate (default: current mouse y)
295
+
296
+ Returns:
297
+ bool: True if point is inside image bounds, False otherwise
298
+ """
222
299
  if ox is None:
223
300
  ox = pygame.mouse.get_pos()[0]
224
301
  if oy is None:
@@ -239,17 +316,28 @@ class Text(Shape):
239
316
  font=_font,
240
317
  size: int = 36,
241
318
  draggable: bool = False,
319
+ visible: bool = True
242
320
  ):
243
- super().__init__(x, y, color, False, draggable)
321
+ super().__init__(x, y, color, False, draggable, visible)
244
322
  self.text = text
245
323
  self.size = size
246
324
  self.font = pygame.font.SysFont(font, size)
247
325
 
248
326
  @property
249
327
  def txtsurf(self):
328
+ """Render and return the text surface for drawing on screen."""
250
329
  return self.font.render(str(self.text), True, self.color)
251
330
 
252
331
  def is_obj_over(self, ox=None, oy=None):
332
+ """Check if a point is inside this text's bounding box.
333
+
334
+ Args:
335
+ ox: X coordinate (default: current mouse x)
336
+ oy: Y coordinate (default: current mouse y)
337
+
338
+ Returns:
339
+ bool: True if point is inside text bounds, False otherwise
340
+ """
253
341
  if ox == None:
254
342
  ox = pygame.mouse.get_pos()[0]
255
343
  if oy == None:
@@ -264,7 +352,17 @@ class Text(Shape):
264
352
 
265
353
 
266
354
  class Group:
267
- def __init__(self, *shapes: list[Shape]):
355
+ """Container for grouping multiple shapes for batch operations.
356
+
357
+ Allows moving, coloring, and interacting with multiple shapes as one unit.
358
+ Implements the full Python container protocol (__len__, __iter__, etc.).
359
+ """
360
+ def __init__(self, *shapes: list[Shape], visible:bool = True):
361
+ """Initialize group with optional initial shapes.
362
+
363
+ Args:
364
+ *shapes: Variable number of Shape objects to add initially
365
+ """
268
366
  self.grouped = []
269
367
  self.add(*shapes)
270
368
 
@@ -322,20 +420,43 @@ class Group:
322
420
  del self.grouped[key]
323
421
 
324
422
  def add(self, *shapes):
423
+ """Add one or more shapes to the group.
424
+
425
+ Args:
426
+ *shapes: One or more Shape objects to add
427
+
428
+ Raises:
429
+ TypeError: If any argument is not a Shape
430
+ """
325
431
  for s in shapes:
326
432
  if not isinstance(s, Shape):
327
433
  raise TypeError(f"{s} must be Shape")
328
434
  self.grouped.append(s)
329
435
 
330
436
  def remove(self, *shapes):
437
+ """Remove one or more shapes from the group.
438
+
439
+ Args:
440
+ *shapes: One or more Shape objects to remove
441
+ """
331
442
  for s in shapes:
332
443
  self.grouped.remove(s)
333
444
  _shapes.remove(s)
334
445
 
335
446
  def clear(self):
447
+ """Remove all shapes from the group."""
336
448
  self.grouped.clear()
337
449
 
338
450
  def is_obj_over(self, x, y):
451
+ """Check if any shape in group contains the point.
452
+
453
+ Args:
454
+ x: X coordinate
455
+ y: Y coordinate
456
+
457
+ Returns:
458
+ bool: True if any child shape contains point, False otherwise
459
+ """
339
460
  for i in self.grouped:
340
461
  if i.is_obj_over(x, y):
341
462
  return True
@@ -350,12 +471,28 @@ class Group:
350
471
 
351
472
 
352
473
  class CollisionManager:
474
+ """Static utility class containing collision detection for all shape combinations."""
353
475
  @staticmethod
354
476
  def rect_rect(rect1: Rect, rect2: Rect):
355
- return pygame.Rect(*rect1.rect).colliderect(pygame.Rect(*rect2.rect))
477
+ """Check if two rectangles are colliding."""
478
+ for rect in [rect1, rect2]:
479
+ corners = [
480
+ (rect.x, rect.y),
481
+ (rect.x + rect.width, rect.y),
482
+ (rect.x, rect.y + rect.height),
483
+ (rect.x + rect.width, rect.y + rect.height),
484
+ ]
485
+ for other in [rect1, rect2]:
486
+ if other is rect:
487
+ continue
488
+ for point in corners:
489
+ if other.is_obj_over(*point):
490
+ return True
491
+ return False
356
492
 
357
493
  @staticmethod
358
494
  def rect_circle(rect: Rect, circle: Circle):
495
+ """Check if a rectangle and circle are colliding."""
359
496
  closest_x = max(rect.x, min(circle.x, rect.x + rect.width))
360
497
  closest_y = max(rect.y, min(circle.y, rect.y + rect.height))
361
498
  dist = ((circle.x - closest_x) ** 2 + (circle.y - closest_y) ** 2) ** 0.5
@@ -363,11 +500,13 @@ class CollisionManager:
363
500
 
364
501
  @staticmethod
365
502
  def circle_circle(circle1: Circle, circle2: Circle):
503
+ """Check if two circles are colliding."""
366
504
  dist = ((circle1.x - circle2.x) ** 2 + (circle1.y - circle2.y) ** 2) ** 0.5
367
505
  return dist < circle1.radius + circle2.radius
368
506
 
369
507
  @staticmethod
370
508
  def rect_polygon(rect: Rect, polygon: Polygon):
509
+ """Check if a rectangle and polygon are colliding."""
371
510
  corners = [
372
511
  (rect.x, rect.y),
373
512
  (rect.x + rect.width, rect.y),
@@ -384,6 +523,7 @@ class CollisionManager:
384
523
 
385
524
  @staticmethod
386
525
  def circle_polygon(circle: Circle, polygon: Polygon):
526
+ """Check if a circle and polygon are colliding."""
387
527
  if polygon.is_obj_over(circle.x, circle.y):
388
528
  return True
389
529
  for px, py in polygon.points:
@@ -394,6 +534,7 @@ class CollisionManager:
394
534
 
395
535
  @staticmethod
396
536
  def rect_text(rect, text):
537
+ """Check if a rectangle and text are colliding."""
397
538
  text_width = text.txtsurf.get_width()
398
539
  text_height = text.txtsurf.get_height()
399
540
  return pygame.Rect(*rect.rect).colliderect(
@@ -402,6 +543,7 @@ class CollisionManager:
402
543
 
403
544
  @staticmethod
404
545
  def circle_text(circle, text):
546
+ """Check if a circle and text are colliding."""
405
547
  text_width = text.txtsurf.get_width()
406
548
  text_height = text.txtsurf.get_height()
407
549
  closest_x = max(text.x, min(circle.x, text.x + text_width))
@@ -411,12 +553,14 @@ class CollisionManager:
411
553
 
412
554
  @staticmethod
413
555
  def rect_image(rect, image):
556
+ """Check if a rectangle and image are colliding."""
414
557
  return pygame.Rect(*rect.rect).colliderect(
415
558
  pygame.Rect(image.x, image.y, image.width, image.height)
416
559
  )
417
560
 
418
561
  @staticmethod
419
562
  def circle_image(circle, image):
563
+ """Check if a circle and image are colliding."""
420
564
  closest_x = max(image.x, min(circle.x, image.x + image.width))
421
565
  closest_y = max(image.y, min(circle.y, image.y + image.height))
422
566
  dist = ((circle.x - closest_x) ** 2 + (circle.y - closest_y) ** 2) ** 0.5
@@ -424,6 +568,7 @@ class CollisionManager:
424
568
 
425
569
  @staticmethod
426
570
  def groupcollision(group, shape):
571
+ """Check if a group and any shape are colliding."""
427
572
  for child in group.grouped:
428
573
  if is_colliding(child, shape):
429
574
  return True
@@ -434,6 +579,15 @@ class CollisionManager:
434
579
 
435
580
 
436
581
  def check_args(func, name):
582
+ """Validate that a decorator function takes no arguments.
583
+
584
+ Args:
585
+ func: The function to validate
586
+ name: Name of the decorator (for error messages)
587
+
588
+ Raises:
589
+ ValueError: If function has any parameters
590
+ """
437
591
  sig = signature(func)
438
592
  param_names = list(sig.parameters)
439
593
  if str(sig) != "()":
@@ -445,6 +599,13 @@ def check_args(func, name):
445
599
  # decorartors like this get weird: if you want to be able to pass arguments in you need to handle 2 cases
446
600
  # if theres no arguments then it just takes the function as the argument
447
601
  def on_tick(func: Callable):
602
+ """Decorator: call function every frame (60 times per second).
603
+
604
+ Usage:
605
+ @on_tick
606
+ def update():
607
+ pass # Runs every frame
608
+ """
448
609
  name = currentframe().f_code.co_name
449
610
  check_args(func, name)
450
611
  _ontick.append(func)
@@ -452,6 +613,15 @@ def on_tick(func: Callable):
452
613
 
453
614
 
454
615
  def on_press(target: Callable | str):
616
+ """Decorator: call function when a key is pressed.
617
+
618
+ Usage:
619
+ @on_press # Any key
620
+ def any_key(): pass
621
+
622
+ @on_press("space, enter") # Specific keys
623
+ def special(): pass
624
+ """
455
625
  if callable(target):
456
626
  func = target
457
627
  name = currentframe().f_code.co_name
@@ -489,6 +659,13 @@ def on_press(target: Callable | str):
489
659
 
490
660
 
491
661
  def on_hold(target: Callable | str):
662
+ """Decorator: call function every frame while a key is held down.
663
+
664
+ Usage:
665
+ @on_hold("w")
666
+ def move_up():
667
+ pass # Runs each frame while 'w' is held
668
+ """
492
669
  if callable(target):
493
670
  func = target
494
671
  name = currentframe().f_code.co_name
@@ -526,7 +703,15 @@ def on_hold(target: Callable | str):
526
703
 
527
704
 
528
705
  def on_click(target: Callable | Shape):
529
-
706
+ """Decorator: call function when mouse is clicked.
707
+
708
+ Usage:
709
+ @on_click # Any click
710
+ def click(): pass
711
+
712
+ @on_click(my_shape) # Click on specific shape
713
+ def shape_click(): pass
714
+ """
530
715
  if callable(target):
531
716
  name = currentframe().f_code.co_name
532
717
  check_args(target, name)
@@ -544,6 +729,12 @@ def on_click(target: Callable | Shape):
544
729
 
545
730
 
546
731
  def on_hover(shape: Shape):
732
+ """Decorator: call function every frame mouse hovers over a shape.
733
+
734
+ Usage:
735
+ @on_hover(my_circle)
736
+ def hover(): pass
737
+ """
547
738
  def decorator(func: Callable):
548
739
  name = currentframe().f_code.co_name
549
740
  check_args(func, name)
@@ -553,20 +744,56 @@ def on_hover(shape: Shape):
553
744
  return decorator
554
745
 
555
746
 
747
+ def on_drag(shape: Shape):
748
+ """Decorator: call function every frame a draggable shape is being dragged.
749
+
750
+ Usage:
751
+ @on_drag(my_rect)
752
+ def dragging(): pass
753
+ """
754
+ def decorator(func: Callable):
755
+ name = currentframe().f_code.co_name
756
+ check_args(func, name)
757
+ _dragging_funcs[shape] = func
758
+ return func
759
+
760
+ return decorator
761
+
762
+
556
763
  def set_bg(color: str):
764
+ """Set the background color of the window.
765
+
766
+ Args:
767
+ color: Color as hex string (#RRGGBB) or name (e.g., 'white', 'red')
768
+ """
557
769
  global _bgcolor
558
770
  _bgcolor = color
559
771
 
560
772
 
561
773
  def clear_screen():
774
+ """Remove all shapes from the screen."""
562
775
  _shapes.clear()
563
776
 
564
777
 
565
778
  def erase(obj):
779
+ """Remove a specific shape from the screen.
780
+
781
+ Args:
782
+ obj: The shape object to remove
783
+ """
566
784
  _shapes.remove(obj)
567
785
 
568
786
 
569
787
  def is_colliding(shape1: Shape, shape2: Shape) -> bool:
788
+ """Check if two shapes are colliding.
789
+
790
+ Args:
791
+ shape1: First shape
792
+ shape2: Second shape
793
+
794
+ Returns:
795
+ bool: True if shapes overlap, False otherwise
796
+ """
570
797
  shapeName1 = shape1.__class__.__name__.lower()
571
798
  shapeName2 = shape2.__class__.__name__.lower()
572
799
  if "group" == shapeName1 or "group" == shapeName2:
@@ -592,7 +819,16 @@ def run(
592
819
  resizable: bool = True,
593
820
  caption: str = "SG window",
594
821
  ):
595
-
822
+ """Start the graphics window and begin the main game loop.
823
+
824
+ This function blocks until the window is closed.
825
+
826
+ Args:
827
+ width: Window width in pixels (default: 200)
828
+ height: Window height in pixels (default: 200)
829
+ resizable: Whether the window can be resized by user (default: True)
830
+ caption: Window title bar text (default: "SG window")
831
+ """
596
832
  global _bgcolor
597
833
 
598
834
  if resizable:
@@ -649,6 +885,7 @@ def run(
649
885
  else:
650
886
  _dragging_shape.x = mouse.x
651
887
  _dragging_shape.y = mouse.y
888
+ _dragging_funcs[_dragging_shape]()
652
889
 
653
890
  _move_shape(_dragging_shape)
654
891
 
@@ -677,6 +914,8 @@ def run(
677
914
  screen.fill(_bgcolor)
678
915
 
679
916
  for shape in _shapes:
917
+ if not shape.visible:
918
+ continue
680
919
  shapeName = shape.__class__.__name__.lower()
681
920
  if shapeName == "circle":
682
921
  pygame.draw.circle(
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: simple-graphics-lib
3
- Version: 0.0.8
3
+ Version: 0.0.9
4
4
  Summary: A simple graphics library for python learners
5
5
  Author-email: Max-Hillyer <maxhillyer7012@gmail.com>
6
6
  License-Expression: MIT
@@ -63,6 +63,8 @@ Arguments:
63
63
  | height | int | the height of the rect | 10 |
64
64
  | color | str | the color of the rect | "black" |
65
65
  | outline | bool | whether the rect is just an outline | False |
66
+ | draggable | bool | whether the rect can be dragged | False |
67
+ | visible | bool | whether the rect is drawn on screen | True |
66
68
 
67
69
  Methods:
68
70
  | Method | Purpose | Arguments | Returns |
@@ -80,6 +82,8 @@ Arguments:
80
82
  | radius | int | the radius of the circle | 10 |
81
83
  | color | str | the color of the circle | "black" |
82
84
  | outline | bool | whether the circle is just an outline | False |
85
+ | draggable | bool | whether the circle can be dragged | False |
86
+ | visible | bool | whether the circle is drawn on screen | True |
83
87
 
84
88
  Methods:
85
89
  | Method | Purpose | Arguments | Returns |
@@ -94,6 +98,8 @@ Arguments:
94
98
  | points | list[tuple] | the vertices of the polygon | None |
95
99
  | color | str | the color of the polygon | "black" |
96
100
  | outline | bool | whther the polygon is just an outline | False |
101
+ | draggable | bool | whether the polygon can be dragged | False |
102
+ | visible | bool | whether the polygon is drawn on screen | True |
97
103
 
98
104
  Methods:
99
105
  | Method | Purpose | Arguments | Returns |
@@ -107,6 +113,8 @@ Arguments:
107
113
  | points | list[tuple] |the points that the line will connect | None |
108
114
  | width | int | the width of the line | 10 |
109
115
  | color | str | the color of the line | "black" |
116
+ | draggable | bool | whether the line can be dragged | False |
117
+ | visible | bool | whether the line is drawn on screen | True |
110
118
 
111
119
  Methods:
112
120
  | Method | Purpose | Arguments | Returns |
@@ -122,6 +130,8 @@ Arguments:
122
130
  | text | str | the text of the text | None |
123
131
  | color | str | the color of the text | "black" |
124
132
  | size | int | the size of the text | 36 |
133
+ | draggable | bool | whether the text can be dragged | False |
134
+ | visible | bool | whether the text is drawn on screen | True |
125
135
 
126
136
  Methods:
127
137
  | Method | Purpose | Arguments | Returns |
@@ -137,6 +147,8 @@ Arguments:
137
147
  | img_path | str | the path to the image | None |
138
148
  | width | int | the width of the image | the width from the image path |
139
149
  | height | int | the height of the image | the height from the image path |
150
+ | draggable | bool | whether the image can be dragged | False |
151
+ | visible | bool | whether the image is drawn on screen | True |
140
152
 
141
153
  Methods:
142
154
  | Method | Purpose | Arguments | Returns |
@@ -160,7 +172,8 @@ group.color = "green"
160
172
  Arguments:
161
173
  | Argument | Type | Role | Default |
162
174
  | :--- | :---: | :---: | ---: |
163
- | *shapes | list[Shape] | the shapes to group | None |
175
+ | *shapes | list[Shape] | the shapes to group | None |
176
+ | visible | bool | whether shapes in group are drawn on screen | True |
164
177
 
165
178
  Methods:
166
179
  | Method | Purpose | Arguments | Returns |
@@ -319,6 +332,20 @@ r1 = Rect(200,200, 100, 100)
319
332
  def p():
320
333
  print("hovering")
321
334
 
335
+ run(400,400)
336
+ ```
337
+
338
+ ### on_drag
339
+ functions defined with the `@on_drag` decorator will run whenever the specified object is being dragged
340
+
341
+ the function below will run whenevr the r1 rect is being dragged
342
+ ```python
343
+ r1 = Rect(200,200,draggable = True)
344
+
345
+ @on_drag(r1)
346
+ def do_something():
347
+ print("dragging r1")
348
+
322
349
  run(400,400)
323
350
  ```
324
351
  ---