Skip to content

Commit 98a948e

Browse files
bodenbergbodenberg
committed
2.0.0
1 parent dea4a84 commit 98a948e

File tree

311 files changed

+48574
-42705
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

311 files changed

+48574
-42705
lines changed

‎Android/BENCHMARK.md‎

Lines changed: 0 additions & 671 deletions
This file was deleted.

‎Android/PROMPT_ANDROID.md‎

Lines changed: 50 additions & 197 deletions
Original file line numberDiff line numberDiff line change
@@ -1,224 +1,77 @@
1-
---
2-
layout: default
3-
title: "AI Prompt for AppDimens Library"
4-
---
1+
# AppDimens Android - Development Prompt
52

6-
# AI Prompt for AppDimens Library
3+
**Quick Reference for AI Assistants and Developers**
4+
*Version: 2.0.0*
75

8-
> **Languages:** English | [Português (BR)](LANG/pt-BR/PROMPT_ANDROID.md) | [Español](LANG/es/PROMPT_ANDROID.md)
6+
---
97

10-
You are an expert Android developer AI. Your task is to understand and effectively use the AppDimens library, a sophisticated dimension management system for Android Views and Jetpack Compose. This guide will provide you with all the necessary information about the library's architecture, functionalities, and use cases.
8+
## Core Principles
119

12-
## 1. Installation / Setup
10+
1. **Use BALANCED ⭐ for 95% of UI elements** (primary recommendation)
11+
2. **Use DEFAULT for phone-only apps** (secondary recommendation)
12+
3. **Use PERCENTAGE for large containers only** (specific use)
13+
4. **13 strategies available** for all use cases
14+
5. **5x performance** vs v1.x
1315

14-
Github: [AppDimens Repository](https://github.com/Bodenberg/AppDimens)
16+
---
1517

16-
Since this is a multi-module project, you will need to add the AppDimens modules as project dependencies in your `build.gradle.kts` (or `build.gradle`) file.
18+
## API Quick Reference
1719

18-
```kotlin
19-
dependencies {
20-
// Core (Dynamic + Fixed)
21-
implementation("io.github.bodenberg:appdimens-dynamic:1.1.0")
22-
23-
// SDP & SSP scaling (optional)
24-
implementation("io.github.bodenberg:appdimens-sdps:1.1.0")
25-
implementation("io.github.bodenberg:appdimens-ssps:1.1.0")
26-
27-
// All in one
28-
implementation("io.github.bodenberg:appdimens-all:1.1.0")
29-
30-
// Game development (separate dependency)
31-
implementation("io.github.bodenberg:appdimens-games:1.1.0")
32-
}
33-
34-
mavenCentral() // or maven { url 'https://jitpack.io' }
35-
```
20+
### Jetpack Compose
3621

3722
```kotlin
38-
dependencies {
39-
// Core (Dynamic + Fixed)
40-
implementation("io.github.bodenberg:appdimens-dynamic:1.1.0")
41-
42-
// SDP & SSP scaling (optional)
43-
implementation("io.github.bodenberg:appdimens-sdps:1.1.0")
44-
implementation("io.github.bodenberg:appdimens-ssps:1.1.0")
45-
46-
// All in one
47-
implementation("io.github.bodenberg:appdimens-all:1.1.0")
48-
49-
// Game development (separate dependency)
50-
implementation("io.github.bodenberg:appdimens-games:1.1.0")
51-
}
52-
53-
mavenCentral()
54-
```
55-
56-
## 2. Library Initialization
57-
58-
AppDimens does not require any manual initialization. The library is designed to work out of the box without any setup in your `Application` class.
59-
60-
## 3. Core Concepts
61-
62-
### 3.1. What is AppDimens?
63-
64-
AppDimens is a library that provides a responsive and mathematically refined way to manage dimensions (Dp, Sp, Px) in Android applications. It ensures layout consistency across various screen sizes and ratios by treating standard Dp values as a base that is dynamically scaled.
65-
66-
### 3.2. Key Modules
67-
68-
The AppDimens library is structured into the following key modules:
69-
70-
- **`appdimens_library`**: The base module containing fundamental classes and enums like `ScreenType` and `DpQualifier`.
71-
- **`appdimens_dynamic`**: The core module that implements the two main scaling models: **Fixed (FX)** and **Dynamic (DY)**. It provides separate implementations for both Android Views (`/code`) and Jetpack Compose (`/compose`).
72-
- **`appdimens_sdps`**: A module that offers a traditional SDP (Scalable DP) approach, allowing you to define dimensions that scale based on screen width, height, or smallest width. It also supports custom dimension values for different UI modes (e.g., TV, Watch).
73-
- **`appdimens_ssps`**: Similar to `appdimens_sdps`, but for SSP (Scalable SP), focusing on text size scaling.
74-
- **`appdimens_games`**: A specialized module for Android game development with C++/NDK support, providing native performance, OpenGL ES utilities, and game-specific dimension calculations.
75-
- **`appdimens_all`**: A module that combines all the `appdimens` functionalities into a single dependency (excluding the games module).
76-
- **`app`**: A sample application module that demonstrates how to use the AppDimens library in a real-world scenario.
77-
78-
### 3.3. Scaling Models: Fixed (FX) vs. Dynamic (DY)
79-
80-
The library's core functionality revolves around two primary scaling models:
81-
82-
| Feature | Fixed (FX) | Dynamic (DY) |
83-
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
84-
| **Philosophy** | **Logarithmic Adjustment**: Subtle, refined scaling that decelerates on very large screens. Recommended for most UI components. | **Proportional Adjustment**: Aggressive, percentage-based scaling that maintains a constant proportion to the screen size. |
85-
| **Use Case** | Ideal for components where visual comfort is key, such as button heights, paddings, icons, and title fonts. | Best suited for layout elements that need to fill a consistent fraction of the available space, like the width of cards in a grid. |
86-
| **Implementation** | Available in `appdimens_dynamic` for both [Views](appdimens_dynamic/src/main/java/com/appdimens/dynamic/code/AppDimens.kt) and [Compose](appdimens_dynamic/src/main/java/com/appdimens/dynamic/compose/AppDimens.kt). | Available in `appdimens_dynamic` for both [Views](appdimens_dynamic/src/main/java/com/appdimens/dynamic/code/AppDimens.kt) and [Compose](appdimens_dynamic/src/main/java/com/appdimens/dynamic/compose/AppDimens.kt). |
87-
88-
## 4. How to Use AppDimens
89-
90-
### 4.1. Jetpack Compose
91-
92-
In Jetpack Compose, AppDimens is primarily used through a set of convenient extension functions on `Int`, `Float`, `Dp`, and `TextUnit`.
93-
94-
#### 4.1.1. `appdimens_dynamic`
95-
96-
The `appdimens_dynamic` module provides a rich set of extensions for both **Fixed** and **Dynamic** scaling.
97-
98-
**Fixed Scaling (FX):**
99-
100-
- Use the `.fxdp`, `.fxsp`, `.fxem`, and `.fxpx` extensions for subtle, logarithmically-scaled dimensions.
101-
- **Example**: `16.dp.fxdp` will provide a slightly larger Dp value on a tablet compared to a phone.
23+
// PRIMARY: BALANCED ⭐
24+
16.balanced().dp
25+
16.balanced().sp
10226

103-
**Dynamic Scaling (DY):**
27+
// SECONDARY: DEFAULT
28+
16.defaultDp
29+
16.defaultSp
10430

105-
- Use the `.dydp`, `.dysp`, `.dyem`, and `.dypx` extensions for proportional, percentage-based scaling.
106-
- **Example**: `100.dp.dydp` will scale the dimension to maintain the same percentage of the screen width.
31+
// Containers: PERCENTAGE
32+
300.percentageDp.dp
10733

108-
**Percentage-Based Dimensions:**
34+
// Others
35+
16.logarithmic().sp
36+
16.power(0.75f).sp
37+
fluidSp(14f, 20f)
10938

110-
You can also create dimensions based on a percentage of the screen size:
111-
112-
- `AppDimens.dynamicPercentageDp(0.5f)` will return a Dp value equivalent to 50% of the screen's smaller dimension.
113-
114-
#### 4.1.2. `appdimens_sdps` and `appdimens_ssps`
115-
116-
These modules provide a more traditional, resource-based scaling approach.
117-
118-
- **SDP**: Use the `.sdp`, `.hdp`, and `.wdp` extensions to scale dimensions based on the smallest width, height, or width of the screen, respectively.
119-
- **SSP**: Use the `.ssp`, `.hsp`, and `.wsp` extensions for scalable text sizes. You can also use `.sem`, `.hem`, and `.wem` for non-font-scaled text.
120-
- **Custom Scaling**: Both modules offer a `scaledDp()` and `scaledSp()` builder to define custom dimensions for different screen configurations (e.g., for `UiModeType.TELEVISION`).
121-
122-
### 4.2. Android Views (XML & Kotlin)
123-
124-
For traditional Android Views, AppDimens provides a `AppDimens` singleton object that acts as a gateway to the scaling functions.
125-
126-
**`appdimens_dynamic`:**
127-
128-
- **Fixed Scaling**: `AppDimens.fixed(16f).dp`
129-
- **Dynamic Scaling**: `AppDimens.dynamic(100f).dp`
130-
- **Data Binding**: The `app` module demonstrates the use of `DimensBindingAdapters` to apply AppDimens directly in XML layouts.
131-
132-
## 5. Data Binding Usage
39+
// Smart API
40+
AppDimens.from(48).smart().forElement(ElementType.BUTTON).dp
41+
```
13342

134-
To use AppDimens with Data Binding, you can create custom `BindingAdapter` functions. The `app` module provides a sample implementation in `DimensBindingAdapters.kt`.
43+
### XML (SDP/SSP)
13544

13645
```xml
137-
<layout xmlns:android="http://schemas.android.com/apk/res/android"
138-
xmlns:app="http://schemas.android.com/apk/res-auto">
139-
140-
<data>
141-
<import type="com.appdimens.dynamic.code.AppDimens"/>
142-
</data>
143-
144-
<LinearLayout
145-
android:layout_width="match_parent"
146-
android:layout_height="match_parent"
147-
android:orientation="vertical"
148-
app:dynamicHeightDp="@{100f}"
149-
app:dynamicWidthDp="@{100f}">
150-
151-
<TextView
152-
android:layout_width="wrap_content"
153-
android:layout_height="wrap_content"
154-
android:text="Title with Dynamic Font"
155-
app:dynamicTextSizeDp="@{20f}"/>
156-
157-
</LinearLayout>
158-
</layout>
46+
<TextView
47+
android:textSize="@dimen/_18ssp"
48+
android:padding="@dimen/_16sdp"
49+
android:layout_width="@dimen/_300sdp" />
15950
```
16051

161-
## 6. Advanced Features
162-
163-
### 6.1. `DpQualifier` and `UiModeType`
164-
165-
The library allows for fine-grained control over dimension scaling:
166-
167-
- **`DpQualifier`**: An enum to specify whether the scaling should be based on `SMALL_WIDTH`, `WIDTH`, or `HEIGHT`.
168-
- **`UiModeType`**: An enum to apply different scaling factors for specific device types, such as `TELEVISION`, `CAR`, or `WATCH`.
169-
170-
### 6.2. Physical Units (`AppDimensPhysicalUnits`)
171-
172-
The `appdimens_dynamic` module includes a utility, `AppDimensPhysicalUnits`, for converting physical units (mm, cm, inch) to pixels. This is particularly useful for applications that require real-world precision, such as on wearables.
173-
174-
### 6.3. Layout Utilities (`calculateAvailableItemCount`)
175-
176-
AppDimens provides a `calculateAvailableItemCount` function to dynamically determine the number of items that can fit within a container. This is extremely useful for calculating the `spanCount` in a `GridLayoutManager` or `LazyVerticalGrid`.
177-
178-
## 7. Game Development with AppDimens Games
179-
180-
The `appdimens_games` module provides specialized functionality for Android game development:
52+
---
18153

182-
### 7.1. Key Features
183-
- **Native C++/NDK Performance**: High-performance dimension calculations for game engines
184-
- **Game-Specific Methods**: Pre-configured calculations for buttons, players, enemies, and UI elements
185-
- **OpenGL ES Integration**: Utilities for OpenGL ES rendering and viewport management
186-
- **Vector and Rectangle Operations**: Mathematical operations for game objects
54+
## Dependencies
18755

188-
### 7.2. Usage Example
18956
```kotlin
190-
class GameActivity : Activity() {
191-
private lateinit var appDimensGames: AppDimensGames
192-
193-
override fun onCreate(savedInstanceState: Bundle?) {
194-
super.onCreate(savedInstanceState)
195-
196-
// Initialize games manager
197-
appDimensGames = AppDimensGames.getInstance()
198-
appDimensGames.initialize(this)
199-
200-
// Calculate game-specific dimensions
201-
val buttonSize = appDimensGames.calculateButtonSize(48f)
202-
val playerSize = appDimensGames.calculatePlayerSize(64f)
203-
val enemySize = appDimensGames.calculateEnemySize(32f)
204-
val uiSize = appDimensGames.calculateUISize(24f)
205-
}
206-
}
57+
implementation("io.github.bodenberg:appdimens-dynamic:2.0.0") // Core (13 strategies)
58+
implementation("io.github.bodenberg:appdimens-sdps:2.0.0") // SDP (XML)
59+
implementation("io.github.bodenberg:appdimens-ssps:2.0.0") // SSP (XML)
60+
implementation("io.github.bodenberg:appdimens-all:2.0.0") // All-in-one
61+
implementation("io.github.bodenberg:appdimens-games:2.0.0") // Games (C++/NDK)
20762
```
20863

209-
## 8. When to Use Each Module
210-
211-
- **`appdimens_dynamic`**: The recommended default for most use cases. It offers a powerful and flexible way to manage dimensions with its **Fixed** and **Dynamic** scaling models.
212-
- **`appdimens_sdps` / `appdimens_ssps`**: Use these when you prefer a more traditional, resource-based scaling approach, or when you need to define specific dimension values for different device types (e.g., a larger font on TVs).
213-
- **`appdimens_games`**: Use this for Android game development when you need native performance and game-specific utilities.
214-
- **`appdimens_all`**: Use this if you want to include all the functionalities of the AppDimens library with a single dependency (excluding games module).
215-
216-
## 9. Performance Considerations
64+
---
21765

218-
AppDimens is optimized for high performance. Dimension values are calculated once and cached to prevent recalculation overhead during screen redraws (recompositions or layout passes). The impact on app startup time is minimal.
66+
## Strategy Selection
21967

220-
## 10. Guide to Testability
68+
- Multi-device → BALANCED ⭐
69+
- Phone-only → DEFAULT
70+
- Containers → PERCENTAGE
71+
- TV → LOGARITHMIC
72+
- Typography → FLUID
73+
- Games → FIT/FILL
22174

222-
For UI (instrumentation) tests, AppDimens will function normally, adapting to the screen dimensions of the test device or emulator. For unit tests, where a real `Context` is unavailable, you can mock the `AppDimens` class or its extension functions to return deterministic values, ensuring your tests are predictable.
75+
---
22376

224-
By following this guide, you should be able to effectively use the AppDimens library to create responsive and visually consistent Android applications. Remember to analyze the context of the user's request to determine the most appropriate scaling model and module to use.
77+
**Full Documentation:** [../DOCS/README.md](../DOCS/README.md)

0 commit comments

Comments
 (0)