Edit on GitHub

kvex

Kvex

Kvex (pronounced "Kay-vex") is a Kivy extension for desktop applications.

Documentation is available via the MouseFox project.

Features

Kivy is arguably the best GUI framework for Python, and the list of things that can be improved is short. Keeping this in mind, Kvex does not intend to "improve" Kivy but rather make it more convenient to use programatically, in particular for desktop applications.

Convenient API for programmatic use
Theming

Limitations

Rather inconsiderate of Kivy's kvlang

Install

pip install git+https://github.com/ArielHorwitz/kvex.git

Using Kvex

Easy importing

Kvex provides a single namespace for many Kivy objects, enabling a single import for a large part of the API:

import kvex.kivy as kv

kv.App
kv.AnchorLayout
kv.Button
kv.SliderTransition
kv.Rectangle
kv.Clock

Virtually all of the widgets and functions that Kvex offers are available from a single import:

import kvex as kx

kx.XApp
kx.XAnchor
kx.XButton
kx.XThemed
kx.wrap
kx.schedule_once
kx.snooze_trigger

Widgets

Kvex widgets use the kvex.widgets.widget.XWidget mixin class. It provides several convenience methods for Kivy widgets. These include an intuitive way to set size with XWidget.set_size and a quick and easy way to create a background with XWidget.make_bg.

Kvex offers some more complex widgets commonly required by desktop applications. Some such examples are:

Themes

Many Kvex widgets use the kvex.behaviors.XThemed mixin class. It enables using a consistent color palette across widgets. The theme is managed by kvex.app.XApp:

import kx

app = kx.XApp()
app.set_theme("mousefox")

Each theme has several subthemes (which are essentially labelled color palettes) that can be used interchangeably (see kvex.colors.SubTheme). Each of these subthemes has background, foreground, and accent colors to be used by widgets. Everything should look fine as long as you match background and foreground colors from the same subtheme.

When creating widgets:

with self.app.subtheme_context("secondary"):  # Set default subtheme
    # All widgets in this code block will default to "secondary"
    label = kx.XLabel(text="Secondary fg on secondary bg")
    label_frame = kx.fwrap(label)  # Wrap label in a themed anchor widget

When subclassing widgets:

import kx
import kx.kivy as kv

class MyThemedLabel(kx.Themed, kv.Label):
    # Example of a themed label.

    def on_subtheme(self, subtheme: kx.SubTheme):
        # Set the label's background and foreground colors.
        self.make_bg(subtheme.bg)
        self.color = subtheme.fg.rgba

my_label = MyThemedLabel(
    text="Secondary fg on secondary bg",
    subtheme_name="secondary",
)

View Source

  1""".. include:: ../README.md
  2
  3# Install
  4```bash
  5pip install git+https://github.com/ArielHorwitz/kvex.git
  6```
  7
  8# Using Kvex
  9
 10## Easy importing
 11Kvex provides a single namespace for many Kivy objects, enabling a single import for a
 12large part of the API:
 13```python3
 14import kvex.kivy as kv
 15
 16kv.App
 17kv.AnchorLayout
 18kv.Button
 19kv.SliderTransition
 20kv.Rectangle
 21kv.Clock
 22```
 23
 24Virtually all of the widgets and functions that Kvex offers are available from a single
 25import:
 26```python3
 27import kvex as kx
 28
 29kx.XApp
 30kx.XAnchor
 31kx.XButton
 32kx.XThemed
 33kx.wrap
 34kx.schedule_once
 35kx.snooze_trigger
 36```
 37
 38## Widgets
 39Kvex widgets use the `kvex.widgets.widget.XWidget` mixin class. It provides several
 40convenience methods for Kivy widgets. These include an intuitive way to set size with
 41`XWidget.set_size` and a quick and easy way to create a background with
 42`XWidget.make_bg`.
 43
 44Kvex offers some more complex widgets commonly required by desktop applications. Some
 45such examples are:
 46* `kvex.widgets.hotkeycontroller.XHotkeyController`
 47* `kvex.widgets.inputpanel.XInputPanel`
 48* `kvex.widgets.buttonbar.XButtonBar`
 49
 50
 51## Themes
 52Many Kvex widgets use the `kvex.behaviors.XThemed` mixin class. It enables using a
 53consistent color palette across widgets. The theme is managed by `kvex.app.XApp`:
 54```python3
 55import kx
 56
 57app = kx.XApp()
 58app.set_theme("mousefox")
 59```
 60
 61Each theme has several subthemes (which are essentially labelled color palettes) that
 62can be used interchangeably (see `kvex.colors.SubTheme`). Each of these subthemes has
 63background, foreground, and accent colors to be used by widgets. Everything should look
 64fine as long as you match background and foreground colors from the same subtheme.
 65
 66When creating widgets:
 67```python3
 68with self.app.subtheme_context("secondary"):  # Set default subtheme
 69    # All widgets in this code block will default to "secondary"
 70    label = kx.XLabel(text="Secondary fg on secondary bg")
 71    label_frame = kx.fwrap(label)  # Wrap label in a themed anchor widget
 72```
 73
 74When subclassing widgets:
 75```python3
 76import kx
 77import kx.kivy as kv
 78
 79class MyThemedLabel(kx.Themed, kv.Label):
 80    # Example of a themed label.
 81
 82    def on_subtheme(self, subtheme: kx.SubTheme):
 83        # Set the label's background and foreground colors.
 84        self.make_bg(subtheme.bg)
 85        self.color = subtheme.fg.rgba
 86
 87my_label = MyThemedLabel(
 88    text="Secondary fg on secondary bg",
 89    subtheme_name="secondary",
 90)
 91```
 92"""  # noqa: D415
 93
 94# flake8: noqa
 95# Ignoring flake8 errors E402,F401,F403 because of late imports and unused imports
 96
 97import os as _os
 98
 99# Kivy configuration must be done before importing kivy
100_os.environ["KIVY_NO_ARGS"] = "1"  # no consuming script arguments
101_os.environ["KCFG_KIVY_LOG_LEVEL"] = "warning"  # no spamming console on startup
102
103
104from .kivy import *
105from .util import *
106from .colors import *
107from .assets import *
108from .widgets import *
109from .behaviors import *
110from .app import *