ae.kivy_relief_canvas

class ReliefCanvas(**kwargs)[source]

Bases: object

relief canvas mixin class for any square or elliptic/circled widget.

to activate the drawing of a relief, you have to specify two colors, one for the top part and another one for the bottom-right part of the relief, which are both stored in a single kivy property. the function relief_colors() can be used to calculate lightened and darkened values of the widget surface color:

MySquareRaisedWidgetWithColoredSurface:
    surface_color: 0.9, 0.6, 0.3, 1.0
    relief_square_outer_colors: relief_colors(color_or_ink=self.surface_color)

this will result in a raised widget with a square outer relief where the top/left relief color gets a lightened value and the bottom-right relief a darkened value of the color specified by surface_color.

using the default values will result in raised widgets with the inner part sunken, simulating the light source in the top left window border/corner. to make a sunken widget for the same light source position, you have to flip the items of the darken_factors argument of the relief_colors() function.

the following example shows this for a round/elliptic button widget:

MyRoundSunkenButton:
    relief_ellipse_outer_colors: relief_colors(darken_factors=(0.3, 0.6))

the other color attributes of this mixin class control the relief colors for the inner part of a square-shaped widget (relief_square_inner_colors) and for the inner part of an elliptic shape widget (relief_ellipse_inner_colors).

the depth of the outer raise/sunk effect can be controlled with the relief_square_outer_lines property/attribute. relief_square_inner_lines controls the raise/sunk depth of a square widgets inner surface. relief_ellipse_inner_lines and relief_ellipse_outer_lines are doing the same for widgets with a round/elliptic shape.

the properties relief_square_inner_offset and relief_ellipse_inner_offset are specifying the width of the widget border (the part between the outer and the inner relief) in pixels.

Note

at least one of the classes that is mixing in this class has to inherit from Widget (or EventDispatcher) to get the widgets pos, size, canvas properties and the bind method.

relief_pos_size

list/tuple of optional relief position and size (x, y, width, height) in pixels.

if not specified or empty list/tuple, than the pos/size values of the mixing-in widget will be used instead.

relief_pos_size is a ListProperty and defaults to an empty list.

relief_ellipse_inner_colors: tuple[tuple[float, float, float] | list[float], tuple[float, float, float] | list[float]] | tuple

list/tuple of ellipse inner (top-left, bottom-right) rgb colors.

relief_ellipse_inner_colors is a ObjectProperty and defaults to an empty tuple.

relief_ellipse_inner_lines

number of ellipse inner lines/pixels to be drawn.

relief_ellipse_inner_lines is a NumericProperty and defaults to ‘3sp’.

relief_ellipse_inner_offset

number of pixels left unchanged at the border of the inner elliptic surface before the inner relief starts.

relief_ellipse_inner_offset is a NumericProperty and defaults to ‘1sp’.

relief_ellipse_outer_colors: tuple[tuple[float, float, float] | list[float], tuple[float, float, float] | list[float]] | tuple

list/tuple of ellipse outer (top-left, bottom-right) rgb colors.

relief_ellipse_outer_colors is a ObjectProperty and defaults to an empty tuple.

relief_ellipse_outer_lines

number of ellipse outer lines/pixels to be drawn.

relief_ellipse_outer_lines is a NumericProperty and defaults to ‘3sp’.

relief_square_inner_colors

list/tuple of square inner (top-left, bottom-right) rgb colors.

relief_square_inner_colors is a ObjectProperty and defaults to an empty tuple.

relief_square_inner_lines

number of square inner lines/pixels to be drawn.

relief_square_inner_lines is a NumericProperty and defaults to ‘3sp’.

relief_square_inner_offset

number of pixels left unchanged at the border of the square inner surface before the inner relief starts.

relief_square_inner_offset is a NumericProperty and defaults to ‘1sp’.

relief_square_outer_colors: tuple[tuple[float, float, float] | list[float], tuple[float, float, float] | list[float]] | tuple

list/tuple of square outer (top-left, bottom-right) rgb colors.

relief_square_outer_colors is a ObjectProperty and defaults to an empty tuple.

relief_square_outer_lines: NumericProperty

number of square outer lines/pixels to be drawn.

relief_square_outer_lines is a NumericProperty and defaults to ‘3sp’.

bind: Any

canvas: Any

pos: list

size: list

__init__(**kwargs)[source]

_relief_refresh(*_args)[source]: pos/size or color changed event handler.

_relief_ellipse_inner_refresh(add_instruction, top_color, bottom_color, wid_x, wid_y, wid_width, wid_height)[source]: ellipse pos/size or color-changed event handler.

_relief_ellipse_outer_refresh(add_instruction, top_color, bottom_color, wid_x, wid_y, wid_width, wid_height)[source]: ellipse pos/size or color-changed event handler.

_relief_square_inner_refresh(add_instruction, top_color, bottom_color, wid_x, wid_y, wid_width, wid_height)[source]: square pos/size or color changed event handler.

_relief_square_outer_refresh(add_instruction, top_color, bottom_color, wid_x, wid_y, wid_width, wid_height)[source]: square pos/size or color changed event handler.

ae.kivy_relief_canvas

inner/outer elliptic/square reliefs for any kivy widget