Canvas¶

The Canvas is the root object used for drawing by a Widget. Check the class documentation for more information about the usage of Canvas.

class kivy.graphics.instructions.Callback(callback=None, **kwargs)¶

Bases: kivy.graphics.instructions.Instruction

A Callback is an instruction that will be called when the drawing operation is performed. When adding instructions to a canvas, you can do this:

with self.canvas:
    Color(1, 1, 1)
    Rectangle(pos=self.pos, size=self.size)
    Callback(self.my_callback)

The definition of the callback must be:

def my_callback(self, instr):
    print('I have been called!')

Warning

Note that if you perform many and/or costly calls to callbacks, you might potentially slow down the rendering performance significantly.

The updating of your canvas does not occur until something new happens. From your callback, you can ask for an update:

with self.canvas:
    self.cb = Callback(self.my_callback)
# then later in the code
self.cb.ask_update()

If you use the Callback class to call rendering methods of another toolkit, you will have issues with the OpenGL context. The OpenGL state may have been manipulated by the other toolkit, and as soon as program flow returns to Kivy, it will just break. You can have glitches, crashes, black holes might occur, etc. To avoid that, you can activate the reset_context option. It will reset the OpenGL context state to make Kivy’s rendering correct after the call to your callback.

Warning

The reset_context is not a full OpenGL reset. If you have issues regarding that, please contact us.

ask_update(self)¶: Inform the parent canvas that we’d like it to update on the next frame. This is useful when you need to trigger a redraw due to some value having changed for example.

New in version 1.0.4.

callback¶: Property for getting/setting func.

reset_context¶: Set this to True if you want to reset the OpenGL context for Kivy after the callback has been called.

class kivy.graphics.instructions.Canvas(**kwargs)¶

Bases: kivy.graphics.instructions.CanvasBase

instructions that you want to be used for drawing.

Note

The Canvas supports Python’s with statement and its enter & exit semantics.

Usage of a canvas without the with statement:

self.canvas.add(Color(1., 1., 0))
self.canvas.add(Rectangle(size=(50, 50)))

Usage of a canvas with Python’s with statement:

with self.canvas:
    Color(1., 1., 0)
    Rectangle(size=(50, 50))

add(self, Instruction c)¶: Append an Instruction to our list. If the canvas contains an after group, then this instruction is inserted just before the after group, which remains last. This is different from how insert() works, which can insert anywhere.

after¶: Property for getting the ‘after’ group.

ask_update(self)¶: Inform the canvas that we’d like it to update on the next frame. This is useful when you need to trigger a redraw due to some value having changed for example.

before¶: Property for getting the ‘before’ group.

clear(self)¶: Clears every Instruction in the canvas, leaving it clean.

draw(self)¶: Apply the instruction to our window.

has_after¶: Property to see if the after group has already been created.

New in version 1.7.0.

has_before¶: Property to see if the before group has already been created.

New in version 1.7.0.

opacity¶

Property to get/set the opacity value of the canvas.

New in version 1.4.1.

The opacity attribute controls the opacity of the canvas and its children. Be careful, it’s a cumulative attribute: the value is multiplied to the current global opacity and the result is applied to the current context color.

For example: if your parent has an opacity of 0.5 and a child has an opacity of 0.2, the real opacity of the child will be 0.5 * 0.2 = 0.1.

Then, the opacity is applied on the shader as:

frag_color = color * vec4(1.0, 1.0, 1.0, opacity);

remove(self, Instruction c)¶

class kivy.graphics.instructions.CanvasBase¶

Bases: kivy.graphics.instructions.InstructionGroup

CanvasBase provides the context manager methods for the Canvas.

class kivy.graphics.instructions.ContextInstruction(**kwargs)¶

Bases: kivy.graphics.instructions.Instruction

that don’t have a direct visual representation, but instead modify the current Canvas’ state, e.g. texture binding, setting color parameters, matrix manipulation and so on.

class kivy.graphics.instructions.Instruction(**kwargs)¶

Bases: kivy.event.ObjectWithUid

usage only, don’t use it directly.

flag_data_update(self)¶

flag_update(do_parent=1)¶

Indicate that the instruction needs to be redrawn on the next frame.

Normally, you should use kivy.graphics.canvas.Canvas.ask_update() instead, but flag_update is necessary if this Instruction is in a kivy.graphics.fbo.Fbo.

Parameters:: do_parent – Whether to flag the parent instruction (such as a kivy.graphics.instructions.InstructionGroup) for update as well. True by default.

group¶: group: unicode

proxy_ref¶: Return a proxy reference to the Instruction i.e. without creating a reference of the widget. See weakref.proxy for more information.

New in version 1.7.2.

class kivy.graphics.instructions.InstructionGroup(**kwargs)¶

Bases: kivy.graphics.instructions.Instruction

of graphics instructions. It can be used directly as follows:

blue = InstructionGroup() blue.add(Color(0, 0, 1, 0.2)) blue.add(Rectangle(pos=self.pos, size=(100, 100)))

green = InstructionGroup() green.add(Color(0, 1, 0, 0.4)) green.add(Rectangle(pos=(100, 100), size=(100, 100)))

# Here, self should be a Widget or subclass [self.canvas.add(group) for group in [blue, green]]

add(self, Instruction c)¶: Add a new Instruction to our list.

children¶: children: list

clear(self)¶: Remove all the Instructions.

get_group(self, unicode groupname)¶: Return an iterable for all the Instructions with a specific group name.

indexof(self, Instruction c)¶

insert(self, int index, Instruction c)¶: Insert a new Instruction into our list at index.

length(self)¶

remove(self, Instruction c)¶: Remove an existing Instruction from our list.

remove_group(self, unicode groupname)¶: Remove all Instructions with a specific group name.

class kivy.graphics.instructions.RenderContext(*args, **kwargs)¶

Bases: kivy.graphics.instructions.Canvas

The vertex shader
The fragment shader
The default texture
The state stack (color, texture, matrix…)

shader¶: Return the shader attached to the render context.

use_parent_frag_modelview¶: If True, the parent fragment modelview matrix will be used.

New in version 1.10.1: rc = RenderContext(use_parent_frag_modelview=True)

use_parent_modelview¶

If True, the parent modelview matrix will be used.

New in version 1.7.0.

Before:

rc['modelview_mat'] = Window.render_context['modelview_mat']

Now:

rc = RenderContext(use_parent_modelview=True)

use_parent_projection¶

If True, the parent projection matrix will be used.

New in version 1.7.0.

Before:

rc['projection_mat'] = Window.render_context['projection_mat']

Now:

rc = RenderContext(use_parent_projection=True)

class kivy.graphics.instructions.VertexInstruction(**kwargs)¶

Bases: kivy.graphics.instructions.Instruction

that have a direct visual representation on the canvas, such as Rectangles, Triangles, Lines, Ellipse and so on.

source¶

This property represents the filename to load the texture from. If you want to use an image as source, do it like this:

with self.canvas:
    Rectangle(source='mylogo.png', pos=self.pos, size=self.size)

Here’s the equivalent in Kivy language:

<MyWidget>:
    canvas:
        Rectangle:
            source: 'mylogo.png'
            pos: self.pos
            size: self.size

Note

The filename will be searched for using the kivy.resources.resource_find() function.

tex_coords¶

This property represents the texture coordinates used for drawing the vertex instruction. The value must be a list of 8 values.

A texture coordinate has a position (u, v), and a size (w, h). The size can be negative, and would represent the ‘flipped’ texture. By default, the tex_coords are:

[u, v, u + w, v, u + w, v + h, u, v + h]

You can pass your own texture coordinates if you want to achieve fancy effects.

Warning

The default values just mentioned can be negative. Depending on the image and label providers, the coordinates are flipped vertically because of the order in which the image is internally stored. Instead of flipping the image data, we are just flipping the texture coordinates to be faster.

texture¶

Property that represents the texture used for drawing this Instruction. You can set a new texture like this:

from kivy.core.image import Image

texture = Image('logo.png').texture
with self.canvas:
    Rectangle(texture=texture, pos=self.pos, size=self.size)

Usually, you will use the source attribute instead of the texture.

« BoxShadow

CGL: standard C interface for OpenGL »

Version

Quick search

Table Of Contents

Canvas¶