ae.kivy_relief_canvas

inner/outer elliptic/square reliefs for any kivy widget

the ReliefCanvas mixin class of this ae namespace portion can be added to any square or elliptic Kivy widget to draw an inner and/or outer relief, in order to convert your widget to have an outstanding or sunken 3D-appearance.

Module Attributes

ReliefColors

tuple of (top, bottom) relief colors or empty tuple

ReliefBrightness

top and bottom brightness/darken factor

Functions

relief_colors([color_or_ink, darken_factors])

calculate the (top and bottom) colors used for the relief lines/drawings.

Classes

ReliefCanvas(**kwargs)

relief canvas mixin class.

ReliefColors

tuple of (top, bottom) relief colors or empty tuple

alias of Union[Tuple[Union[Tuple[float, float, float], List[float]], Union[Tuple[float, float, float], List[float]]], Tuple]

ReliefBrightness

top and bottom brightness/darken factor

alias of Tuple[float, float]

relief_colors(color_or_ink=(0, 0, 0), darken_factors=(0.6, 0.3))[source]

calculate the (top and bottom) colors used for the relief lines/drawings.

Parameters:
  • color_or_ink (Union[Tuple[float, float, float], List[float], Tuple[float, float, float, float]]) –

    color used to calculate the relief colors from, which will first be lightened until one of the color parts (R, G or B) reach the value 1.0; then darken factors will be applied to the color parts. If not passed then grey colors will be returned.

    Note

    if the alpha value of paramref:~relief_colors.color_or_ink is zero then no relief colors will be calculated and an empty tuple will be returned (disabling relief).

  • darken_factors (Tuple[float, float]) – two factors to darken (1) the top and (2) the bottom relief color parts.

Return type:

Union[Tuple[Union[Tuple[float, float, float], List[float]], Union[Tuple[float, float, float], List[float]]], Tuple]

Returns:

tuple with darkened colors calculated from color_or_ink and darken_factors or an empty tuple if the alpha value of color_or_ink has a zero value.

class ReliefCanvas(**kwargs)[source]

Bases: object

relief canvas mixin class.

to activate the drawing of a relief you have to specify two colors, one for the top part and another one for the bottom 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 surface color of the widget:

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 get 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 simply 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 the inner surface of a square widget. 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: Union[Tuple[Union[Tuple[float, float, float], List[float]], Union[Tuple[float, float, float], List[float]]], Tuple]

list/tuple of ellipse inner (top, bottom) 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: Union[Tuple[Union[Tuple[float, float, float], List[float]], Union[Tuple[float, float, float], List[float]]], Tuple]

list/tuple of ellipse outer (top, bottom) 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, bottom) 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: Union[Tuple[Union[Tuple[float, float, float], List[float]], Union[Tuple[float, float, float], List[float]]], Tuple]

list/tuple of square outer (top, bottom) 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.