mirror of
https://github.com/chenasraf/flame_ui.git
synced 2026-05-18 01:39:01 +00:00
docs: update README.md
This commit is contained in:
14
.editorconfig
Normal file
14
.editorconfig
Normal file
@@ -0,0 +1,14 @@
|
||||
[*]
|
||||
tab_width = 2
|
||||
indent_size = 2
|
||||
indent_style = space
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
|
||||
[*.md]
|
||||
trim_trailing_whitespace = false
|
||||
|
||||
[Makefile]
|
||||
tab_width = 4
|
||||
indent_size = 4
|
||||
indent_style = tab
|
||||
15
.prettierrc
Normal file
15
.prettierrc
Normal file
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"printWidth": 100,
|
||||
"semi": false,
|
||||
"singleQuote": true,
|
||||
"trailingComma": "all",
|
||||
"overrides": [
|
||||
{
|
||||
"files": "*.md",
|
||||
"options": {
|
||||
"printWidth": 100,
|
||||
"proseWrap": "always"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
156
README.md
156
README.md
@@ -1,8 +1,10 @@
|
||||
# Flame UI
|
||||
|
||||
A reusable component library for [Flame](https://flame-engine.org/) games, built with modularity and developer ergonomics in mind.
|
||||
A reusable component library for [Flame](https://flame-engine.org/) games, built with modularity and
|
||||
developer ergonomics in mind.
|
||||
|
||||
This package includes stylized UI primitives like text inputs, buttons, modals, lists, and scrollable layouts — all tailored for Flame.
|
||||
This package includes stylized UI primitives like text inputs, buttons, modals, lists, and
|
||||
scrollable layouts — all tailored for Flame.
|
||||
|
||||
---
|
||||
|
||||
@@ -10,155 +12,85 @@ This package includes stylized UI primitives like text inputs, buttons, modals,
|
||||
|
||||
Add this to your main app’s `pubspec.yaml`:
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
flame_ui:
|
||||
path: packages/flame_ui
|
||||
````
|
||||
```sh
|
||||
flutter pub add flame_ui
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Components
|
||||
|
||||
Each component is fully documented in its own file. Below is a high-level overview of what’s
|
||||
available.
|
||||
|
||||
---
|
||||
|
||||
### `ModalComponent`
|
||||
|
||||
A flexible modal window with a scrollable content area and optional title/footer.
|
||||
A flexible modal window that wraps any component in a styled, scrollable dialog.
|
||||
|
||||
```dart
|
||||
ModalComponent({
|
||||
required PositionComponent scrollContent,
|
||||
required Vector2 size,
|
||||
required Vector2 position,
|
||||
String? title,
|
||||
EdgeInsets padding = const EdgeInsets.all(8),
|
||||
double? contentHeight,
|
||||
bool autoContentHeight = true,
|
||||
TextStyle? titleStyle,
|
||||
double titleSpacing = 2,
|
||||
Paint? paint,
|
||||
Sprite? closeIcon,
|
||||
VoidCallback? onClose,
|
||||
VoidCallback? onAfterLoad,
|
||||
PositionComponent? footer,
|
||||
double defaultFooterHeight = 32,
|
||||
});
|
||||
```
|
||||
- Supports a title, scrollable content, and optional footer.
|
||||
- Customize layout via padding, title spacing, and content height behavior.
|
||||
- Optional close icon and callback hooks (`onClose`, `onAfterLoad`).
|
||||
|
||||
---
|
||||
|
||||
### `RectButtonComponent`
|
||||
|
||||
A simple rectangular button with customizable label and colors.
|
||||
A tappable rectangular button with a customizable label.
|
||||
|
||||
```dart
|
||||
RectButtonComponent({
|
||||
required VoidCallback onPressed,
|
||||
required String label,
|
||||
required Vector2 size,
|
||||
required Vector2 position,
|
||||
Color color = Colors.red,
|
||||
Color? pressedColor,
|
||||
Color textColor = Colors.white,
|
||||
});
|
||||
```
|
||||
- Supports background color, text color, and pressed state color.
|
||||
- Designed for quick interaction without layout boilerplate.
|
||||
|
||||
---
|
||||
|
||||
### `TextFieldComponent`
|
||||
|
||||
A custom input field that uses a hidden Flutter `TextField` overlay for virtual keyboard support.
|
||||
A virtual keyboard–enabled text field powered by an overlayed Flutter `TextField`.
|
||||
|
||||
```dart
|
||||
TextFieldComponent({
|
||||
required Vector2 position,
|
||||
required Vector2 size,
|
||||
Sprite? background,
|
||||
NineTileBox? backgroundNineTile,
|
||||
Sprite? focusedBackground,
|
||||
NineTileBox? focusedBackgroundNineTile,
|
||||
TextStyle textStyle = const TextStyle(color: Colors.white, fontSize: 12),
|
||||
OnTextChanged? onChanged,
|
||||
String? hintText,
|
||||
EdgeInsets padding = EdgeInsets.zero,
|
||||
TextEditingController? controller,
|
||||
});
|
||||
```
|
||||
- Supports `Sprite` or `NineTileBox` backgrounds for normal and focused states.
|
||||
- Customizable text style, hint text, and internal padding.
|
||||
- Supports external controller and `onChanged` callback.
|
||||
|
||||
---
|
||||
|
||||
### `GridComponent`
|
||||
|
||||
A fixed-size grid layout for uniformly sized components.
|
||||
A layout component for arranging children in a uniform grid.
|
||||
|
||||
```dart
|
||||
GridComponent({
|
||||
required List<PositionComponent> childrenComponents,
|
||||
required Vector2 childSize,
|
||||
Vector2? spacing,
|
||||
required Vector2 size,
|
||||
required Vector2 position,
|
||||
});
|
||||
```
|
||||
- Fixed-size cells with optional spacing.
|
||||
- Automatically places components row by row.
|
||||
|
||||
---
|
||||
|
||||
### `ScrollableAreaComponent`
|
||||
|
||||
A vertically scrollable container with clipping and drag support.
|
||||
A vertical scroll container that clips its contents and handles drag gestures.
|
||||
|
||||
```dart
|
||||
ScrollableAreaComponent({
|
||||
required PositionComponent content,
|
||||
required Vector2 size,
|
||||
required Vector2 position,
|
||||
double? contentHeight,
|
||||
bool autoContentHeight = true,
|
||||
});
|
||||
```
|
||||
- Use when your content may overflow vertically (e.g., on small watch screens).
|
||||
- Dynamically adjusts scroll limits based on content size.
|
||||
|
||||
---
|
||||
|
||||
### `ListComponent`
|
||||
|
||||
A vertical list of fixed-height children with optional spacing and width.
|
||||
A vertical list layout for displaying uniform-height items.
|
||||
|
||||
```dart
|
||||
ListComponent({
|
||||
required List<PositionComponent> childrenComponents,
|
||||
required double childHeight,
|
||||
double? spacing,
|
||||
double? width,
|
||||
Vector2? size,
|
||||
Vector2? position,
|
||||
});
|
||||
```
|
||||
- Supports spacing between items and optional custom width.
|
||||
- Designed for use with `ListItemComponent` or similar items.
|
||||
|
||||
---
|
||||
|
||||
### `ListItemComponent`
|
||||
|
||||
A list row with a title, optional subtitle, icon, and trailing action.
|
||||
A reusable list row for text and optional leading/trailing content.
|
||||
|
||||
```dart
|
||||
ListItemComponent({
|
||||
required String title,
|
||||
String? subtitle,
|
||||
SpriteComponent? icon,
|
||||
PositionComponent? action,
|
||||
VoidCallback? onPressed,
|
||||
EdgeInsets padding = const EdgeInsets.all(2),
|
||||
double spacing = 4,
|
||||
TextStyle titleStyle = const TextStyle(fontSize: 10, color: Colors.white),
|
||||
TextStyle subtitleStyle = const TextStyle(fontSize: 8, color: Colors.white70),
|
||||
Vector2? size,
|
||||
Vector2? position,
|
||||
Vector2? iconSize,
|
||||
});
|
||||
```
|
||||
- Displays a title, optional subtitle, icon, and trailing component (like a button).
|
||||
- Fully styleable with text styles, padding, spacing, and icon sizing.
|
||||
- Tapable row with `onPressed` callback support.
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 🧪 Example
|
||||
|
||||
```dart
|
||||
@@ -183,18 +115,20 @@ final button = RectButtonComponent(
|
||||
|
||||
## 📌 Notes
|
||||
|
||||
* All components are Flame `PositionComponent`s and integrate seamlessly with Flame's coordinate system.
|
||||
* Many components use `NineTileBox` or `Sprite` backgrounds and require assets to be loaded.
|
||||
* `TextFieldComponent` needs `game.buildContext` to work (e.g. `GameWidget()` inside a `MaterialApp`).
|
||||
- All components are Flame `PositionComponent`s and integrate seamlessly with Flame's coordinate
|
||||
system.
|
||||
- Many components use `NineTileBox` or `Sprite` backgrounds and require assets to be loaded.
|
||||
- `TextFieldComponent` needs `game.buildContext` to work (e.g. `GameWidget()` inside a
|
||||
`MaterialApp`).
|
||||
|
||||
---
|
||||
|
||||
## 🛠 Roadmap
|
||||
|
||||
* [ ] Cursor + selection support in `TextFieldComponent`
|
||||
* [ ] Prebuilt themes/styles
|
||||
* [ ] Dropdowns, toggles, and tabs
|
||||
* [ ] RTL / accessibility support
|
||||
- [ ] Cursor + selection support in `TextFieldComponent`
|
||||
- [ ] Prebuilt themes/styles
|
||||
- [ ] Dropdowns, toggles, and tabs
|
||||
- [ ] RTL / accessibility support
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user