Flutter, explained for beginners

# Verify your setup
flutter doctor

# See available devices / emulators
flutter devices

# Create a new project
flutter create my_app
cd my_app

# Run it (with hot reload active)
flutter run

# While running: press r = hot reload, R = hot restart, q = quit

// Type inference
var name = 'Flutter';        // String
final version = 3.24;        // set once, at runtime
const pi = 3.14159;          // compile-time constant (must be known at compile time)

// Explicit types
int count = 3;
double ratio = 0.5;
String greeting = 'Hello';
bool isReady = true;

// Collections
List<String> fruits = ['apple', 'banana'];
Map<String, int> scores = {'Ada': 10, 'Linus': 9};
Set<int> ids = {1, 2, 3};

// String interpolation
print('$greeting, $name! Version $version');   // simple
print('Total: ${count + 1}');                  // expression

String a = 'always non-null';   // cannot be null
String? b;                      // MAY be null — the ? makes it nullable

// b.length;                    // ❌ compile error: b might be null
if (b != null) {
  print(b.length);              // ✅ promoted to non-null inside the check
}

// Null-aware operators
print(b?.length);               // null if b is null, otherwise b.length
print(b ?? 'fallback');         // 'fallback' if b is null
b ??= 'default';                // assign only if currently null

// Classic
int add(int a, int b) {
  return a + b;
}

// Arrow syntax for single expressions
int add2(int a, int b) => a + b;

// Optional named parameters (the Flutter style)
void greet({required String name, String greeting = 'Hello'}) {
  print('$greeting, $name');
}
greet(name: 'Ada');                       // Hello, Ada
greet(name: 'Ada', greeting: 'Hi');       // Hi, Ada

// Optional positional
void log(String msg, [int? level]) { /* ... */ }

// Functions are values
final doubleFn = (int x) => x * 2;

class Point {
  final double x;
  final double y;

  // Constructor with initializer shorthand
  const Point(this.x, this.y);

  // Named constructor
  Point.origin() : x = 0, y = 0;

  double distanceTo(Point other) {
    final dx = x - other.x;
    final dy = y - other.y;
    return math.sqrt(dx * dx + dy * dy);
  }

  @override
  String toString() => 'Point($x, $y)';
}

final p = Point(1, 2);
final o = const Point.origin();

final numbers = [1, 2, 3, 4, 5];

// Functional helpers
final doubled = numbers.map((n) => n * 2).toList();      // [2,4,6,8,10]
final evens   = numbers.where((n) => n.isEven).toList();  // [2,4]
final sum     = numbers.reduce((a, b) => a + b);          // 15
final hasBig  = numbers.any((n) => n > 4);                // true

// Spread & collection-if (great for building widget lists)
final more = [0, ...numbers, if (hasBig) 6];

// for-in
for (final n in numbers) { print(n); }

// switch expression (Dart 3)
final label = switch (numbers.length) {
  0 => 'empty',
  1 => 'one',
  _ => 'many',
};

// Future = a value that arrives later (one value)
Future<String> fetchName() async {
  await Future.delayed(const Duration(seconds: 1));
  return 'Ada';
}

// Stream = a sequence of values arriving over time
Stream<int> countdown(int from) async* {
  for (var i = from; i > 0; i--) {
    yield i;
    await Future.delayed(const Duration(seconds: 1));
  }
}

await for (final n in countdown(3)) {
  print(n); // 3, 2, 1
}

// ---- Stateless ----
class Greeting extends StatelessWidget {
  final String name;
  const Greeting({super.key, required this.name});

  @override
  Widget build(BuildContext context) {
    return Text('Hello, $name');
  }
}

// ---- Stateful ----
class Toggle extends StatefulWidget {
  const Toggle({super.key});

  @override
  State<Toggle> createState() => _ToggleState();
}

class _ToggleState extends State<Toggle> {
  bool _on = false;

  @override
  Widget build(BuildContext context) {
    return Switch(
      value: _on,
      onChanged: (v) => setState(() => _on = v),
    );
  }
}

import 'package:flutter/material.dart';

// 1. Every Dart program starts at main().
void main() => runApp(const MyApp());

// 2. The root widget of the app.
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // 3. MaterialApp wires up theming, routing and localization.
    return MaterialApp(
      title: 'Demo',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        colorSchemeSeed: Colors.indigo,
        useMaterial3: true,
      ),
      home: const HomePage(),
    );
  }
}

// 4. A page. Scaffold gives us the standard page structure.
class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: const Center(
        child: Text('Hello, Flutter!'),
      ),
    );
  }
}

class CounterPage extends StatefulWidget {
  const CounterPage({super.key});

  @override
  State<CounterPage> createState() => _CounterPageState();
}

class _CounterPageState extends State<CounterPage> {
  int _count = 0;

  void _increment() {
    setState(() {
      _count++;          // mutate state inside setState
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Counter')),
      body: Center(
        child: Text(
          '$_count',
          style: Theme.of(context).textTheme.displayMedium,
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _increment,
        child: const Icon(Icons.add),
      ),
    );
  }
}

class Parent extends StatefulWidget {
  const Parent({super.key});
  @override
  State<Parent> createState() => _ParentState();
}

class _ParentState extends State<Parent> {
  String _name = 'World';

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Hello, $_name'),
        NameField(
          onNameChanged: (value) => setState(() => _name = value),
        ),
      ],
    );
  }
}

class NameField extends StatelessWidget {
  final ValueChanged<String> onNameChanged;
  const NameField({super.key, required this.onNameChanged});

  @override
  Widget build(BuildContext context) {
    return TextField(onChanged: onNameChanged);
  }
}

Column(
  // Column's main axis is vertical, cross axis is horizontal.
  mainAxisAlignment: MainAxisAlignment.center,      // along the column
  crossAxisAlignment: CrossAxisAlignment.start,     // across the column
  children: [
    const Text('Title'),
    const SizedBox(height: 8),
    Row(
      children: [
        const CircleAvatar(child: Icon(Icons.person)),
        const SizedBox(width: 12),
        // Expanded fills the leftover horizontal space.
        Expanded(
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: const [
              Text('Ada Lovelace'),
              Text('Mathematician', style: TextStyle(color: Colors.grey)),
            ],
          ),
        ),
      ],
    ),
  ],
)

Container(
  width: 200,
  height: 100,
  margin: const EdgeInsets.all(16),          // outside
  padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
  decoration: BoxDecoration(
    color: Colors.white,
    borderRadius: BorderRadius.circular(12),
    border: Border.all(color: Colors.black12),
    boxShadow: const [
      BoxShadow(blurRadius: 8, color: Colors.black12, offset: Offset(0, 2)),
    ],
  ),
  child: const Text('Card-like box'),
)

class Todo {
  final String title;
  final String subtitle;
  const Todo(this.title, this.subtitle);
}

class TodoList extends StatelessWidget {
  final List<Todo> todos;
  const TodoList({super.key, required this.todos});

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: todos.length,
      // Optional: separate the rows
      separatorBuilder: (_, __) => const Divider(height: 1),
      itemBuilder: (context, index) {
        final todo = todos[index];
        return ListTile(
          leading: const Icon(Icons.check_circle_outline),
          title: Text(todo.title),
          subtitle: Text(todo.subtitle),
          trailing: const Icon(Icons.chevron_right),
          onTap: () => print('Tapped ${todo.title}'),
        );
      },
    );
  }
}

Widget build(BuildContext context) {
  if (isLoading) {
    return const Center(child: CircularProgressIndicator());
  }
  if (error != null) {
    return Center(child: Text('Something went wrong: $error'));
  }
  if (todos.isEmpty) {
    return const Center(child: Text('Nothing here yet.'));
  }
  return ListView.builder(/* ... */);
}

SingleChildScrollView(
  padding: const EdgeInsets.all(16),
  child: Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: const [
      Text('Heading'),
      SizedBox(height: 12),
      Text('A long body of text that will scroll...'),
      // ...
    ],
  ),
)

ElevatedButton(
  onPressed: () => print('tapped'),
  child: const Text('Primary'),
)

OutlinedButton.icon(
  onPressed: _submit,
  icon: const Icon(Icons.send),
  label: const Text('Send'),
)

TextButton(
  onPressed: () => Navigator.pop(context),
  child: const Text('Cancel'),
)

// Disable any button by passing null
ElevatedButton(onPressed: null, child: const Text('Disabled'))

class SignupForm extends StatefulWidget {
  const SignupForm({super.key});
  @override
  State<SignupForm> createState() => _SignupFormState();
}

class _SignupFormState extends State<SignupForm> {
  final _formKey = GlobalKey<FormState>();
  final _emailController = TextEditingController();

  @override
  void dispose() {
    _emailController.dispose();   // always dispose controllers
    super.dispose();
  }

  void _submit() {
    // validate() runs every validator and returns true if all pass
    if (_formKey.currentState!.validate()) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Welcome, ${_emailController.text}')),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      child: Column(
        children: [
          TextFormField(
            controller: _emailController,
            keyboardType: TextInputType.emailAddress,
            decoration: const InputDecoration(
              labelText: 'Email',
              hintText: 'you@example.com',
            ),
            validator: (value) {
              if (value == null || value.isEmpty) return 'Email is required';
              if (!value.contains('@')) return 'Enter a valid email';
              return null;   // null means "valid"
            },
          ),
          const SizedBox(height: 16),
          ElevatedButton(onPressed: _submit, child: const Text('Sign up')),
        ],
      ),
    );
  }
}

// No visual feedback — good for custom hit areas
GestureDetector(
  onTap: () => print('tapped'),
  onLongPress: () => print('held'),
  child: const Icon(Icons.favorite),
)

// Material ripple feedback — prefer this for tappable surfaces
InkWell(
  onTap: () => print('tapped'),
  borderRadius: BorderRadius.circular(8),
  child: const Padding(
    padding: EdgeInsets.all(12),
    child: Text('Tap me'),
  ),
)

// Go to a new screen
Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => const DetailsPage()),
);

// Go back
Navigator.pop(context);

// Go back and return a value to whoever pushed us
Navigator.pop(context, 'result');

// Receive that value
final result = await Navigator.push<String>(
  context,
  MaterialPageRoute(builder: (context) => const PickerPage()),
);
print(result);   // 'result' once PickerPage pops

MaterialApp(
  initialRoute: '/',
  routes: {
    '/': (context) => const HomePage(),
    '/details': (context) => const DetailsPage(),
    '/settings': (context) => const SettingsPage(),
  },
);

// Then anywhere:
Navigator.pushNamed(context, '/details');
Navigator.pushReplacementNamed(context, '/settings');  // replaces current

class Shell extends StatefulWidget {
  const Shell({super.key});
  @override
  State<Shell> createState() => _ShellState();
}

class _ShellState extends State<Shell> {
  int _index = 0;

  static const _pages = [
    Center(child: Text('Home')),
    Center(child: Text('Search')),
    Center(child: Text('Profile')),
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: _pages[_index],
      bottomNavigationBar: NavigationBar(
        selectedIndex: _index,
        onDestinationSelected: (i) => setState(() => _index = i),
        destinations: const [
          NavigationDestination(icon: Icon(Icons.home), label: 'Home'),
          NavigationDestination(icon: Icon(Icons.search), label: 'Search'),
          NavigationDestination(icon: Icon(Icons.person), label: 'Profile'),
        ],
      ),
    );
  }
}

Future<String> fetchGreeting() async {
  await Future.delayed(const Duration(seconds: 1));
  return 'Hello from the server';
}

Future<void> main() async {
  print('start');
  final greeting = await fetchGreeting();   // pauses here, doesn't block the UI
  print(greeting);
  print('end');
}
// Output: start → (1s pause) → Hello from the server → end

// pubspec.yaml:
//   dependencies:
//     http: ^1.2.0

import 'dart:convert';
import 'package:http/http.dart' as http;

class Todo {
  final int id;
  final String title;
  final bool completed;

  const Todo({required this.id, required this.title, required this.completed});

  // Named constructor: build from a decoded JSON map
  factory Todo.fromJson(Map<String, dynamic> json) => Todo(
        id: json['id'] as int,
        title: json['title'] as String,
        completed: json['completed'] as bool? ?? false,
      );
}

Future<List<Todo>> fetchTodos() async {
  final uri = Uri.parse('https://jsonplaceholder.typicode.com/todos');
  final response = await http.get(uri);

  if (response.statusCode != 200) {
    throw Exception('Request failed with status ${response.statusCode}');
  }

  final List<dynamic> data = jsonDecode(response.body) as List<dynamic>;
  return data
      .map((item) => Todo.fromJson(item as Map<String, dynamic>))
      .toList();
}

class TodoScreen extends StatefulWidget {
  const TodoScreen({super.key});
  @override
  State<TodoScreen> createState() => _TodoScreenState();
}

class _TodoScreenState extends State<TodoScreen> {
  late Future<List<Todo>> _future;

  @override
  void initState() {
    super.initState();
    // Create the future ONCE, not inside build().
    _future = fetchTodos();
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<List<Todo>>(
      future: _future,
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return const Center(child: CircularProgressIndicator());
        }
        if (snapshot.hasError) {
          return Center(child: Text('Error: ${snapshot.error}'));
        }
        final todos = snapshot.data ?? const [];
        if (todos.isEmpty) {
          return const Center(child: Text('No todos.'));
        }
        return ListView.builder(
          itemCount: todos.length,
          itemBuilder: (context, i) => ListTile(title: Text(todos[i].title)),
        );
      },
    );
  }
}

Future<void> _save() async {
  await api.save();

  // The user may have navigated away while we waited.
  if (!mounted) return;      // in a State object

  ScaffoldMessenger.of(context).showSnackBar(
    const SnackBar(content: Text('Saved!')),
  );
}

my_app/
├── lib/                    # ← all your Dart code lives here
│   ├── main.dart           # entry point
│   ├── models/             # plain data classes
│   ├── screens/            # one file per page
│   ├── widgets/            # reusable UI pieces
│   └── services/           # API clients, storage
├── test/                   # unit & widget tests
├── android/  ios/  web/    # platform-specific shells
├── assets/                 # images, fonts, JSON you ship
├── pubspec.yaml            # dependencies + assets + metadata
└── analysis_options.yaml   # linter rules

name: my_app
description: A sample Flutter app.
publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: '^3.5.0'

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0
  provider: ^6.1.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^4.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/images/
  # fonts:
  #   - family: MyFont
  #     fonts:
  #       - asset: assets/fonts/MyFont-Regular.ttf

// ❌ Works, but the whole thing rebuilds together and you lose const.
Widget _buildHeader() {
  return const Text('Header');
}

// ✅ Separate widget: Flutter can skip rebuilding it when nothing changed.
class _Header extends StatelessWidget {
  const _Header();
  @override
  Widget build(BuildContext context) => const Text('Header');
}