Rename insertion_layer and working_layer to canvas_layer

examples/imitating_the_screen_manager.py

@@ -46,9 +46,9 @@ async def main(self):
             await ak.event(btn, 'on_release')
             with (
                 ak.block_touch_events(sm),
-                ak.stencil_widget_mask(sm, relative=True, working_layer='outer'),
+                ak.stencil_widget_mask(sm, relative=True, canvas_layer="outer"),
             ):
-                async with transition.slide(sm, working_layer='inner_outer', duration=0.8):
+                async with transition.slide(sm, canvas_layer="inner_outer", duration=0.8):
                     sm.remove_widget(current_screen)
                     current_screen = next(screens)
                     sm.add_widget(current_screen)

examples/stencil_mask.py

@@ -31,7 +31,7 @@ def on_start(self):
     async def main(self):
         await ak.n_frames(2)
         label = self.root.ids.label.__self__
-        with ak.stencil_widget_mask(label, working_layer="outer"):
+        with ak.stencil_widget_mask(label, canvas_layer="outer"):
             for text in itertools.cycle('ABC'):
                 async with slide_transition(label, out_curve='in_back', in_curve='out_back'):
                     label.text = text

sphinx/submod-transition.rst

@@ -40,9 +40,9 @@ and clips its drawing area. To replicate those behaviors as well:
 
     with (
         ak.block_touch_events(layout),
-        ak.stencil_widget_mask(layout, relative=True, working_layer="outer"),
+        ak.stencil_widget_mask(layout, relative=True, canvas_layer="outer"),
     ):
-        async with transition.slide(layout, working_layer="inner_outer"):
+        async with transition.slide(layout, canvas_layer="inner_outer"):
             layout.remove_widget(screen1)
             layout.add_widget(screen2)
 

src/asynckivy/_etc.py

@@ -17,7 +17,7 @@
 
 @contextmanager
 def sandwich_canvas(target: Canvas, top_bun: Instruction, bottom_bun: Instruction,
-                    *, insertion_layer: CanvasLayer="inner"):
+                    *, canvas_layer: CanvasLayer="inner"):
     '''
     Returns a context manager that sandwiches the ``target``'s graphics instructions between the
     ``top_bun`` and ``bottom_bun``.
@@ -28,7 +28,7 @@ def sandwich_canvas(target: Canvas, top_bun: Instruction, bottom_bun: Instructio
         with sandwich_canvas(label.canvas, Translate(20, 0), Translate(-20, 0)):
             ...
 
-    The ``insertion_layer`` parameter controls where ``top_bun`` and ``bottom_bun`` are inserted within the target
+    The ``canvas_layer`` parameter controls where ``top_bun`` and ``bottom_bun`` are inserted within the target
     canvas. If set to "inner" (the default), they are inserted into the **outer side** of the **inner** canvas:
 
     .. code-block:: yaml
@@ -76,14 +76,14 @@ def sandwich_canvas(target: Canvas, top_bun: Instruction, bottom_bun: Instructio
     .. versionadded:: 0.10.0
     '''
     c = target
-    if insertion_layer == "inner":
+    if canvas_layer == "inner":
         c.insert(1 if c.has_before else 0, top_bun)
         c.add(bottom_bun)
         before = after = c
     else:
         before = c.before
         after = c.after
-        if insertion_layer == "outer":
+        if canvas_layer == "outer":
             before.insert(0, top_bun)
             after.add(bottom_bun)
         else:  # inner_outer
@@ -97,7 +97,7 @@ def sandwich_canvas(target: Canvas, top_bun: Instruction, bottom_bun: Instructio
 
 
 @contextmanager
-def transform(widget, *, working_layer: CanvasLayer="inner") -> Iterator[InstructionGroup]:
+def transform(widget, *, canvas_layer: CanvasLayer="inner") -> Iterator[InstructionGroup]:
     '''
     Returns a context manager that helps apply transformations to the given widget.
 
@@ -110,18 +110,18 @@ async def rotate_widget(widget, *, angle=360.):
                 ig.add(rotate := Rotate(origin=widget.center))
                 await anim_attrs(rotate, angle=angle)
 
-    :param working_layer: Controls which part of the widget's canvas is affected by the transformation.
+    :param canvas_layer: Controls which part of the widget's canvas is affected by the transformation.
         See :func:`sandwich_canvas` for details.
 
     .. versionchanged:: 0.10.0
-        The ``use_outer_canvas`` parameter was replaced with the ``working_layer`` parameter.
+        The ``use_outer_canvas`` parameter was replaced with the ``canvas_layer`` parameter.
     '''
 
     top_bun = InstructionGroup()
     top_bun.add(PushMatrix())
     top_bun.add(user_space := InstructionGroup())
     bottom_bun = PopMatrix()
-    with sandwich_canvas(widget.canvas, top_bun, bottom_bun, insertion_layer=working_layer):
+    with sandwich_canvas(widget.canvas, top_bun, bottom_bun, canvas_layer=canvas_layer):
         yield user_space
 
 
@@ -371,7 +371,7 @@ def _update_follower_ver_seq(getattr, setattr, math_exp, zip, target_obj, target
 
 
 @contextmanager
-def stencil_mask(widget, *, working_layer: CanvasLayer="inner") -> Iterator[InstructionGroup]:
+def stencil_mask(widget, *, canvas_layer: CanvasLayer="inner") -> Iterator[InstructionGroup]:
     '''
     Returns a context manager that allows restricting the drawing area of a specified widget to an arbitrary shape.
 
@@ -398,15 +398,15 @@ def stencil_mask(widget, *, working_layer: CanvasLayer="inner") -> Iterator[Inst
             ...
 
     Since this use case is so common, :func:`stencil_widget_mask` is provided as a shorthand.
-    Also, note that if the ``widget`` is a relative-type widget and the ``working_layer`` is not "outer",
+    Also, note that if the ``widget`` is a relative-type widget and the ``canvas_layer`` is not "outer",
     line A above must be removed.
 
-    :param working_layer: Controls which part of the widget's canvas is affected by the restriction.
+    :param canvas_layer: Controls which part of the widget's canvas is affected by the restriction.
         See :func:`sandwich_canvas` for details.
 
     .. versionadded:: 0.9.1
     .. versionchanged:: 0.10.0
-        The ``use_outer_canvas`` parameter was replaced with the ``working_layer`` parameter.
+        The ``use_outer_canvas`` parameter was replaced with the ``canvas_layer`` parameter.
     '''
     IG = InstructionGroup
     shared_part = IG()
@@ -418,12 +418,12 @@ def stencil_mask(widget, *, working_layer: CanvasLayer="inner") -> Iterator[Inst
     bottom_bun.add(StencilUnUse())
     bottom_bun.add(shared_part)
     bottom_bun.add(StencilPop())
-    with sandwich_canvas(widget.canvas, top_bun, bottom_bun, insertion_layer=working_layer):
+    with sandwich_canvas(widget.canvas, top_bun, bottom_bun, canvas_layer=canvas_layer):
         yield shared_part
 
 
 @contextmanager
-def stencil_widget_mask(widget, *, working_layer="inner", relative=False) -> Iterator[InstructionGroup]:
+def stencil_widget_mask(widget, *, canvas_layer="inner", relative=False) -> Iterator[InstructionGroup]:
     '''
     Returns a context manager that restricts the drawing area to the widget's own area.
 
@@ -433,18 +433,18 @@ def stencil_widget_mask(widget, *, working_layer="inner", relative=False) -> Ite
             ...
 
     :param relative: Must be set to True if the ``widget`` is a relative-type widget.
-    :param working_layer: Controls which part of the widget's canvas is affected by the restriction.
+    :param canvas_layer: Controls which part of the widget's canvas is affected by the restriction.
         See :func:`sandwich_canvas` for details.
 
     .. versionadded:: 0.9.1
     .. versionchanged:: 0.10.0
-        The ``use_outer_canvas`` parameter was replaced with the ``working_layer`` parameter.
+        The ``use_outer_canvas`` parameter was replaced with the ``canvas_layer`` parameter.
     '''
     rect = Rectangle()
     with (
-        sync_attr((widget, 'pos'), (rect, 'pos')) if (not relative) or working_layer == "outer" else nullcontext(),
+        sync_attr((widget, 'pos'), (rect, 'pos')) if (not relative) or canvas_layer == "outer" else nullcontext(),
         sync_attr((widget, 'size'), (rect, 'size')),
-        stencil_mask(widget, working_layer=working_layer) as drawable_area,
+        stencil_mask(widget, canvas_layer=canvas_layer) as drawable_area,
     ):
         drawable_area.add(rect)
         yield drawable_area

src/asynckivy/modal.py

@@ -97,7 +97,7 @@ async def __call__(self, dialog: Widget, parent: FloatLayout, window: WindowBase
             with bg_canvas:
                 bg_color = Color(*self.background_color[:3], 0.)
                 Rectangle(size=parent.size)
-            with ak.transform(dialog, working_layer="outer") as ig:
+            with ak.transform(dialog, canvas_layer="outer") as ig:
                 x_dist = y_dist = 0.
                 match self.in_direction:
                     case 'down':

src/asynckivy/transition.py

@@ -86,7 +86,7 @@ async def fade_multiple(*widgets, duration=1., out_curve=linear, in_curve=linear
 async def slide(target: Wow=Window, *, duration=1., out_curve='in_back', in_curve='out_back',
                 x_direction: Literal['left', 'right', None]='left',
                 y_direction: Literal['down', 'up', None]=None,
-                working_layer="inner"):
+                canvas_layer="inner"):
     '''
     Slides the ``target`` out, executes the code inside the with-block, and then slides it back in.
 
@@ -105,7 +105,7 @@ async def slide(target: Wow=Window, *, duration=1., out_curve='in_back', in_curv
     elif y_direction == 'down':
         y_dist = -y_dist
 
-    with transform(target, working_layer=working_layer) as ig:
+    with transform(target, canvas_layer=canvas_layer) as ig:
         ig.add(mat := Translate())
         half_d = duration / 2
         await anim_attrs(mat, d=half_d, t=out_curve, x=x_dist, y=y_dist)
@@ -117,13 +117,13 @@ async def slide(target: Wow=Window, *, duration=1., out_curve='in_back', in_curv
 
 @asynccontextmanager
 async def scale(target: Wow=Window, *, duration=1, out_curve='out_quad', in_curve='in_quad',
-                working_layer="inner"):
+                canvas_layer="inner"):
     '''
     Shrinks the ``target``, executes the code inside the with-block, and then restores it to its original size.
 
     .. versionadded:: 0.9.0
     '''
-    with transform(target, working_layer=working_layer) as ig:
+    with transform(target, canvas_layer=canvas_layer) as ig:
         ig.add(mat := Scale(origin=target.center))
         half_d = duration / 2
         await anim_attrs(mat, d=half_d, t=out_curve, xyz=(0, 0, 1))

tests/test_sandwich_canvas.py

@@ -40,7 +40,7 @@ def test_inner(canvas):
     from kivy.graphics import PushMatrix, PopMatrix
     from asynckivy import sandwich_canvas
     c = canvas
-    with sandwich_canvas(c, top_bun=PushMatrix(), bottom_bun=PopMatrix(), insertion_layer="inner"):
+    with sandwich_canvas(c, top_bun=PushMatrix(), bottom_bun=PopMatrix(), canvas_layer="inner"):
         assert list_children(c) == ['CanvasBase', 'PushMatrix', 'Color', 'PopMatrix', 'CanvasBase']
         assert list_children(c.before) == ['Color', ]
         assert list_children(c.after) == ['Color', ]
@@ -53,7 +53,7 @@ def test_outer(canvas):
     from kivy.graphics import PushMatrix, PopMatrix
     from asynckivy import sandwich_canvas
     c = canvas
-    with sandwich_canvas(c, top_bun=PushMatrix(), bottom_bun=PopMatrix(), insertion_layer="outer"):
+    with sandwich_canvas(c, top_bun=PushMatrix(), bottom_bun=PopMatrix(), canvas_layer="outer"):
         assert list_children(c) == ['CanvasBase', 'Color', 'CanvasBase']
         assert list_children(c.before) == ['PushMatrix', 'Color', ]
         assert list_children(c.after) == ['Color', 'PopMatrix', ]
@@ -66,7 +66,7 @@ def test_inner_outer(canvas):
     from kivy.graphics import PushMatrix, PopMatrix
     from asynckivy import sandwich_canvas
     c = canvas
-    with sandwich_canvas(c, top_bun=PushMatrix(), bottom_bun=PopMatrix(), insertion_layer="inner_outer"):
+    with sandwich_canvas(c, top_bun=PushMatrix(), bottom_bun=PopMatrix(), canvas_layer="inner_outer"):
         assert list_children(c) == ['CanvasBase', 'Color', 'CanvasBase']
         assert list_children(c.before) == ['Color', 'PushMatrix', ]
         assert list_children(c.after) == ['PopMatrix', 'Color', ]
@@ -80,7 +80,7 @@ def test_inner_no_before_nor_after():
     from asynckivy import sandwich_canvas
     c = Canvas()
     c.add(Color())
-    with sandwich_canvas(c, top_bun=PushMatrix(), bottom_bun=PopMatrix(), insertion_layer="inner"):
+    with sandwich_canvas(c, top_bun=PushMatrix(), bottom_bun=PopMatrix(), canvas_layer="inner"):
         assert list_children(c) == ['PushMatrix', 'Color', 'PopMatrix', ]
         assert not c.has_before
         assert not c.has_after

tests/test_transform.py

@@ -20,7 +20,7 @@ def list_children(canvas):
 def test_outer(widget):
     from asynckivy import transform
     c = widget.canvas
-    with transform(widget, working_layer="outer"):
+    with transform(widget, canvas_layer="outer"):
         assert list_children(c) == ['CanvasBase', 'Color', 'CanvasBase']
         assert list_children(c.before) == ['InstructionGroup', 'Color', ]
         assert list_children(c.before.children[0]) == ['PushMatrix', 'InstructionGroup', ]
@@ -33,7 +33,7 @@ def test_outer(widget):
 def test_inner_outer(widget):
     from asynckivy import transform
     c = widget.canvas
-    with transform(widget, working_layer="inner_outer"):
+    with transform(widget, canvas_layer="inner_outer"):
         assert list_children(c) == ['CanvasBase', 'Color', 'CanvasBase']
         assert list_children(c.before) == ['Color', 'InstructionGroup', ]
         assert list_children(c.before.children[1]) == ['PushMatrix', 'InstructionGroup', ]
@@ -46,7 +46,7 @@ def test_inner_outer(widget):
 def test_inner(widget):
     from asynckivy import transform
     c = widget.canvas
-    with transform(widget, working_layer="inner"):
+    with transform(widget, canvas_layer="inner"):
         assert list_children(c) == ['CanvasBase', 'InstructionGroup', 'Color', 'PopMatrix', 'CanvasBase']
         assert list_children(c.before) == ['Color', ]
         assert list_children(c.children[1]) == ['PushMatrix', 'InstructionGroup', ]