0
# Application Framework
1

2
Core application classes and theming system for Material Design applications. This includes the main app class that integrates Material Design theming, the theme management system, and all Material Design resource definitions including colors, icons, and typography.
3

4
## Capabilities
5

6
### Main Application Class
7

8
The main application class that provides Material Design theming integration and serves as the entry point for KivyMD applications.
9

10
```python { .api }
11
class MDApp:
12
    """
13
    Main application class with integrated Material Design theming.
14
    
15
    This class extends Kivy's App class with Material Design theming capabilities.
16
    It automatically sets up the theme manager and provides access to Material Design
17
    resources throughout the application.
18
    """
19
    theme_cls: ThemeManager  # Theme manager instance
20
    icon: str  # App icon path (default: "kivymd/images/logo/kivymd-icon-512.png")
21
    
22
    def build(self):
23
        """
24
        Build and return the root widget.
25
        
26
        Returns:
27
            Widget: Root widget of the application
28
        """
29
        
30
    def on_start(self):
31
        """Called when the application starts."""
32
        
33
    def on_stop(self):
34
        """Called when the application stops."""
35
        
36
    def load_all_kv_files(self, path_to_directory: str):
37
        """
38
        Load all KV files from specified directory recursively.
39
        
40
        Searches through all subdirectories and loads any .kv files found.
41
        Useful for automatically loading UI definitions.
42
        
43
        Args:
44
            path_to_directory (str): Path to directory containing KV files
45
        """
46
        
47
    def fps_monitor_start(self):
48
        """
49
        Start FPS monitoring display.
50
        
51
        Shows real-time FPS counter on screen for performance monitoring.
52
        Available through FpsMonitoring mixin.
53
        """
54
```
55

56
### Theme Management
57

58
Central theming system that manages Material Design colors, typography, and visual specifications across the entire application.
59

60
```python { .api }
61
class ThemeManager:
62
    """
63
    Central theme management system for Material Design theming.
64
    
65
    Manages all aspects of Material Design theming including color palettes,
66
    typography, spacing, and visual specifications.
67
    """
68
    
69
    # Color theming
70
    primary_palette: str  # Primary color palette name (e.g., "Blue", "Red")
71
    accent_palette: str   # Accent color palette name
72
    theme_style: str      # Theme style: "Light" or "Dark"
73
    material_style: str   # Material Design version: "M2" or "M3"
74
    
75
    # Color hue properties
76
    primary_hue: str      # Primary palette hue (e.g., "500")
77
    primary_light_hue: str # Light primary hue
78
    primary_dark_hue: str  # Dark primary hue
79
    accent_hue: str       # Accent palette hue
80
    accent_light_hue: str # Light accent hue
81
    accent_dark_hue: str  # Dark accent hue
82
    
83
    # Color properties
84
    primary_color: list      # Primary color as RGBA
85
    primary_light: list      # Light primary color as RGBA
86
    primary_dark: list       # Dark primary color as RGBA
87
    accent_color: list       # Accent color as RGBA
88
    bg_darkest: list        # Darkest background color
89
    bg_dark: list           # Dark background color
90
    bg_normal: list         # Normal background color
91
    bg_light: list          # Light background color
92
    
93
    # Text colors
94
    text_color: list        # Primary text color
95
    secondary_text_color: list  # Secondary text color
96
    disabled_hint_text_color: list  # Disabled text color
97
    divider_color: list     # Divider color
98
    error_color: list       # Error color
99
    
100
    # Animation properties
101
    theme_style_switch_animation: bool  # Enable theme switching animation
102
    theme_style_switch_animation_duration: float  # Animation duration
103
    
104
    # Font styles
105
    font_styles: dict       # Complete font style definitions
106
    
107
    # Material Design specifications
108
    device_orientation: str  # "portrait" or "landscape"
109
    standard_increment: int  # Standard increment in dp
110
    horizontal_margins: int  # Horizontal margins in dp
111
    
112
    def set_colors(self, primary: str, accent: str, theme_style: str = "Light",
113
                   light_primary: str = None, light_accent: str = None,
114
                   dark_primary: str = None, dark_accent: str = None, 
115
                   primary_hue: str = None):
116
        """
117
        Set comprehensive theme colors.
118
        
119
        Args:
120
            primary (str): Primary palette name
121
            accent (str): Accent palette name  
122
            theme_style (str): "Light" or "Dark"
123
            light_primary (str): Light primary palette name
124
            light_accent (str): Light accent palette name
125
            dark_primary (str): Dark primary palette name  
126
            dark_accent (str): Dark accent palette name
127
            primary_hue (str): Primary color hue
128
        """
129
        
130
class ThemableBehavior:
131
    """
132
    Mixin behavior that provides theme integration for widgets.
133
    
134
    This behavior should be inherited by all widgets that need access
135
    to theme properties and automatic theme updates.
136
    """
137
    theme_cls: ThemeManager  # Reference to theme manager
138
    device_ios: bool        # Whether running on iOS device
139
    widget_style: str       # Widget style: "android", "ios", or "desktop"  
140
    opposite_colors: bool   # Use opposite color theming
141
    
142
    def theme_cls_bind(self):
143
        """Bind to theme manager for automatic updates."""
144
        
145
    def dec_disabled(self):
146
        """Cleanup method called when widget is disabled."""
147
```
148

149
### Color System
150

151
Complete Material Design color palette system with all standard colors and utilities for color manipulation.
152

153
```python { .api }
154
# Color palette dictionary - contains all Material Design colors
155
colors: dict  # Complete color palette with all hues
156

157
# Color palette names
158
palette: list  # Available palette names: ["Red", "Pink", "Purple", ...]
159

160
# Color hues
161
hue: list  # Available hues: ["50", "100", "200", ..., "900", "A100", "A200", "A400", "A700"]
162

163
# Theme-specific colors
164
light_colors: dict  # Light theme color specifications
165
text_colors: dict   # Text color specifications for different themes
166
theme_colors: list  # Available theme color names
167

168
def get_color_from_hex(hex_color: str) -> list:
169
    """
170
    Convert hex color to RGBA list.
171
    
172
    Args:
173
        hex_color (str): Hex color string (e.g., "#FF5722")
174
        
175
    Returns:
176
        list: RGBA color as [r, g, b, a] normalized to 0-1
177
    """
178
```
179

180
### Icon System
181

182
Complete Material Design Icons system with over 7000+ icons available as unicode characters.
183

184
```python { .api }
185
# Material Design Icons dictionary
186
md_icons: dict  # Icon name to unicode mapping (7000+ icons)
187

188
class MDIcon:
189
    """
190
    Material Design icon display widget.
191
    
192
    Displays Material Design icons using the md_icons dictionary.
193
    """
194
    icon: str  # Icon name from md_icons
195
    theme_icon_color: str  # Icon color theme
196
    
197
    def set_icon(self, icon_name: str):
198
        """
199
        Set the icon.
200
        
201
        Args:
202
            icon_name (str): Icon name from md_icons dictionary
203
        """
204
```
205

206
### Typography System
207

208
Material Design typography system with all standard font styles and text specifications.
209

210
```python { .api }
211
# Font definitions
212
fonts: list  # Font definitions for Material Design fonts
213
theme_font_styles: list  # Available font styles
214

215
# Font style names and specifications
216
FONT_STYLES = {
217
    "H1": {"font_size": "96sp", "font_weight": "light"},
218
    "H2": {"font_size": "60sp", "font_weight": "light"},
219
    "H3": {"font_size": "48sp", "font_weight": "normal"},
220
    "H4": {"font_size": "34sp", "font_weight": "normal"},
221
    "H5": {"font_size": "24sp", "font_weight": "normal"},
222
    "H6": {"font_size": "20sp", "font_weight": "medium"},
223
    "Subtitle1": {"font_size": "16sp", "font_weight": "normal"},
224
    "Subtitle2": {"font_size": "14sp", "font_weight": "medium"},
225
    "Body1": {"font_size": "16sp", "font_weight": "normal"},
226
    "Body2": {"font_size": "14sp", "font_weight": "normal"},
227
    "Button": {"font_size": "14sp", "font_weight": "medium"},
228
    "Caption": {"font_size": "12sp", "font_weight": "normal"},
229
    "Overline": {"font_size": "10sp", "font_weight": "normal"}
230
}
231
```
232

233
### Material Design Specifications
234

235
Material Design specification constants for consistent spacing, sizing, and layout.
236

237
```python { .api }
238
# Device and platform detection
239
DEVICE_IOS: bool  # True if running on iOS
240
DEVICE_TYPE: str  # "desktop", "tablet", or "mobile"
241

242
# Layout specifications
243
MAX_NAV_DRAWER_WIDTH: int  # Maximum navigation drawer width in dp
244
HORIZ_MARGINS: int  # Standard horizontal margins in dp
245
STANDARD_INCREMENT: int  # Standard increment for spacing in dp
246

247
# Component specifications
248
PORTRAIT_TOOLBAR_HEIGHT: int  # Toolbar height in portrait mode in dp
249
LANDSCAPE_TOOLBAR_HEIGHT: int  # Toolbar height in landscape mode in dp
250
TOUCH_TARGET_HEIGHT: int  # Minimum touch target height in dp
251

252
# Elevation specifications
253
ELEVATION_LEVELS: dict  # Standard elevation levels for components
254
```
255

256
### Package Constants
257

258
Core package constants and utility paths for accessing KivyMD resources.
259

260
```python { .api }
261
__version__: str  # KivyMD version string
262

263
# Resource paths
264
path: str  # Path to KivyMD package directory
265
fonts_path: str  # Path to fonts directory
266
images_path: str  # Path to images directory
267
uix_path: str  # Path to UI components directory
268
glsl_path: str  # Path to GLSL shaders directory
269
```