flutter-study-notebook/posts/03_dicee.md

---
title: "Flutter Dicee Project Study Guide"
tags:
  - project-03
---

# Flutter Dicee Project Study Guide

## Project Overview
This project creates a dice rolling app using Flutter. It demonstrates key concepts in Flutter development, including stateful widgets, random number generation, and interactive UI elements.

## Key Components

### 1. Main Dart File (main.dart)

#### Entry Point
```dart
void main() {
  return runApp(
    MaterialApp(
      // ...
    ),
  );
}
```
- The `main()` function is the entry point of the Flutter app.
- `runApp()` takes the root widget of the app as an argument.

#### App Structure
```dart
MaterialApp(
  home: Scaffold(
    backgroundColor: Colors.red,
    appBar: AppBar(
      // ...
    ),
    body: DicePage(),
  ),
)
```
- `MaterialApp` provides the base structure for the app.
- `Scaffold` implements the basic material design layout.
- `AppBar` creates a custom app bar with a title and bottom border.
- `DicePage` is the main content of the app.

### 2. Widget Tree

To include the widget tree diagram in your markdown notes, use the following code block:

```mermaid
graph TD
    A[MaterialApp] --> B[Scaffold]
    B --> C[AppBar]
    B --> D[DicePage Stateful Widget]
    D --> E[Center]
    E --> F[Row]
    F --> G[Expanded Left]
    F --> H[Expanded Right]
    G --> I[TextButton Left]
    H --> J[TextButton Right]
    I --> K[Image.asset Left]
    J --> L[Image.asset Right]
```

### 3. Key Widgets and Their Purposes

1. **MaterialApp**: Provides default theme and navigation structure.
2. **Scaffold**: Implements the basic material design layout.
3. **AppBar**: Creates a custom app bar for the app.
4. **DicePage (StatefulWidget)**: The main content widget that can update its state.
5. **Center**: Centers its child within itself.
6. **Row**: Arranges its children horizontally.
7. **Expanded**: Expands a child of a Row, Column, or Flex.
8. **TextButton**: A Material Design text button.
9. **Image.asset**: Displays an image from the app's assets.

### 4. Stateful Widget Implementation

```dart
class DicePage extends StatefulWidget {
  @override
  State<DicePage> createState() => _DicePageState();
}

class _DicePageState extends State<DicePage> {
  int leftDiceNumber = 1;
  int rightDiceNumber = 1;

  void rollDice() {
    setState(() {
      leftDiceNumber = Random().nextInt(6) + 1;
      rightDiceNumber = Random().nextInt(6) + 1;
    });
  }

  @override
  Widget build(BuildContext context) {
    // ... widget tree
  }
}
```
- `DicePage` is a `StatefulWidget` that creates and manages a `_DicePageState`.
- `_DicePageState` contains the mutable state and the `build` method.
- `rollDice()` method updates the state using `setState()`.

### 5. Interactivity and State Management

- `TextButton` widgets are used to make the dice images tappable.
- `onPressed` property of `TextButton` is set to call `rollDice()`.
- `setState()` is used to update the UI when dice values change.

### 6. Asset Management

In `pubspec.yaml`:
```yaml
flutter:
  assets:
    - images/
```
This allows the use of `Image.asset('images/dice$diceNumber.png')` in the code.

## Learning Outcomes

1. Creating and using Stateful Widgets
2. Implementing interactivity with `TextButton`
3. Managing app state with `setState()`
4. Using `Random()` for generating random numbers
5. Structuring a Flutter app with `MaterialApp` and `Scaffold`
6. Using `Row` and `Expanded` for layout
7. Loading and displaying images from assets
8. String interpolation in Dart (`'images/dice$diceNumber.png'`)

## Exercises to Reinforce Learning

1. Add a "Roll Both" button that changes both dice at once.
2. Implement a score counter that increments based on the dice values.
3. Add animations to the dice when they change.
4. Create a custom app theme and apply it to the entire app.
5. Implement a "lock" feature for each die, allowing the user to keep one die's value while rolling the other.

## Finished App

![Finished App](../images/dicee-demo.gif)

## Additional Resources

- [Flutter Documentation](https://flutter.dev/docs)
- [Dart Language Tour](https://dart.dev/guides/language/language-tour)
- [Flutter State Management](https://flutter.dev/docs/development/data-and-backend/state-mgmt/intro)

Remember to refer to the README.md file for the project goals and additional learning points!