Flutter

┌─────────────────────────────────────┐
│         YOUR DART CODE              │  // Your widgets, business logic
├─────────────────────────────────────┤
│         FLUTTER FRAMEWORK           │  // Widgets, animations, gestures (Dart)
├─────────────────────────────────────┤
│         FLUTTER ENGINE              │  // Skia/Impeller rendering, Dart VM (C++)
├─────────────────────────────────────┤
│         PLATFORM EMBEDDER           │  // iOS, Android, Web, Desktop (native)
└─────────────────────────────────────┘

Build → Layout → Paint → Composite
  ↑         ↑        ↑        ↑
Widget   RenderObject  Layer  GPU
 Tree      Tree      Tree   Frame

// Non-nullable (default) — cannot be null, compiler enforces this
String name = "Flutter";
int age = 5;

// Nullable — CAN be null (add ? to opt in)
String? nickname;       // null by default
int? optionalAge;

// late — tells Dart "I'll initialize this before use"
late String lazyValue;  // crashes at runtime if you read it before setting it

String? user;

// ?? — provide a default value when null
String display = user ?? "Guest";         // "Guest" because user is null

// ?. — safe navigation (no crash on null)
int? length = user?.length;              // null (no crash)

// ! — force unwrap (use sparingly — you'd better be right)
String forced = user!;                   // throws if null

// ??= — lazy default assignment
user ??= "Anonymous";                    // sets user only if it was null

// Arrow functions — single-expression shorthand
int double(int x) => x * 2;

// Named parameters — callers must use the parameter name
void greet({required String name, String greeting = "Hello"}) {
  print("$greeting, $name!");
}
greet(name: "Kamran");               // Hello, Kamran!
greet(name: "Dev", greeting: "Hi"); // Hi, Dev!

// Positional optional parameters — caller can skip them
int add(int a, [int b = 0]) => a + b;

// Cascade notation — chain multiple calls on the SAME object
var paint = Paint()
  ..color = Colors.blue       // same as paint.color = Colors.blue
  ..strokeWidth = 5.0
  ..style = PaintingStyle.stroke;

// Spread operator — unpack a list into another list
var list1 = [1, 2, 3];
var list2 = [...list1, 4, 5];  // [1, 2, 3, 4, 5]

// Collection if and for — build lists with logic inline
var items = [
  'Home',
  if (isLoggedIn) 'Profile',      // conditionally add an item
  for (var tag in tags) tag,       // spread items from a loop
];

// Future — a single value that arrives eventually (like ordering a package)
Future<String> fetchUser() async {
  await Future.delayed(Duration(seconds: 2)); // simulate network delay
  return "Kamran";
}

// await pauses THIS function, not the whole UI — the app stays responsive
void loadData() async {
  String user = await fetchUser();
  print(user); // "Kamran" after 2 seconds
}

// then() — callback style (less readable, less preferred)
fetchUser().then((user) => print(user)).catchError((e) => print(e));

// Stream — a sequence of async events (like a live radio broadcast)
Stream<int> counter() async* {
  for (int i = 0; i < 5; i++) {
    await Future.delayed(Duration(seconds: 1));
    yield i; // emit one value at a time, then pause
  }
}

// StatelessWidget — build() is called when parent rebuilds with new data
class WelcomeCard extends StatelessWidget {
  final String name;
  const WelcomeCard({required this.name, super.key});

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(16), // 16px padding on all sides
        child: Text('Hello, $name!'),
      ),
    );
  }
}

// StatefulWidget — split into a widget class + a separate State class
class Counter extends StatefulWidget {
  const Counter({super.key});
  @override
  State<Counter> createState() => _CounterState(); // creates the State object once
}

class _CounterState extends State<Counter> {
  int _count = 0;  // mutable state lives HERE in State, not in the widget

  void _increment() {
    setState(() {      // tell Flutter "something changed, please rebuild"
      _count++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Count: $_count'),        // reads from state
        ElevatedButton(
          onPressed: _increment,       // triggers setState on tap
          child: const Text('Add'),
        ),
      ],
    );
  }
}

// StatefulWidget lifecycle — what happens and when:
createState()           // State object created once when widget enters the tree
initState()             // Called once after creation — perfect for async setup
didChangeDependencies() // Called when an InheritedWidget ancestor changes
build()                 // Called every time setState() fires or parent rebuilds
didUpdateWidget()       // Called when parent gives the widget new configuration
dispose()               // Called before state is removed — CLEAN UP HERE

class _MyState extends State<MyWidget> {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    // Good place to: initialize controllers, fetch data, set up listeners
    _controller = AnimationController(vsync: this, duration: Duration(seconds: 1));
  }

  @override
  void dispose() {
    _controller.dispose(); // ALWAYS dispose to prevent memory leaks
    super.dispose();
  }

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

// Column — stacks children vertically (like a menu list)
Column(
  mainAxisAlignment: MainAxisAlignment.center,    // alignment along vertical axis
  crossAxisAlignment: CrossAxisAlignment.start,   // alignment along horizontal axis
  children: [Text('A'), Text('B'), Text('C')],
)

// Row — places children side by side horizontally
Row(
  mainAxisAlignment: MainAxisAlignment.spaceBetween, // spread items apart
  children: [Icon(Icons.star), Text('4.5')],
)

// Stack — layers children on top of each other (like CSS z-index)
Stack(
  children: [
    Image.asset('background.png'),           // bottom layer
    Positioned(
      bottom: 16,
      right: 16,
      child: FloatingActionButton(onPressed: () {}, child: Icon(Icons.add)),
    ),
  ],
)

// Container — the "div" of Flutter (combines decoration, padding, margin, sizing)
Container(
  width: 200,
  height: 100,
  margin: EdgeInsets.all(8),                      // space outside the container
  padding: EdgeInsets.symmetric(horizontal: 16, vertical: 8), // space inside
  decoration: BoxDecoration(
    color: Colors.blue,
    borderRadius: BorderRadius.circular(12),      // rounded corners
    boxShadow: [BoxShadow(color: Colors.black26, blurRadius: 8)],
  ),
  child: Text('Card'),
)

// Expanded — greedily takes all remaining space in a Row/Column
Row(
  children: [
    Icon(Icons.star),
    Expanded(child: Text('This fills remaining width')), // takes ALL leftover space
    Text('end'),
  ],
)

// Flexible — like Expanded but the child can be SMALLER than its allocation
Flexible(flex: 2, child: Container(color: Colors.red))   // gets 2/3 of space
Flexible(flex: 1, child: Container(color: Colors.blue))  // gets 1/3 of space

// SizedBox — fixed-size box, also used as a spacing gap
SizedBox(height: 16)   // a simple 16px vertical spacer
SizedBox(width: double.infinity, height: 50, child: ElevatedButton(...))

// Padding — just adds padding, nothing else
Padding(
  padding: EdgeInsets.only(left: 16, right: 16),
  child: Text('Padded Text'),
)

// Suitable for: toggle buttons, form fields, counters, tab selection
setState(() {
  _isLoading = true; // Flutter will call build() again with the new value
});

// Low-level — usually wrapped by Provider or Riverpod in real apps
class AppTheme extends InheritedWidget {
  final ThemeData theme;
  const AppTheme({required this.theme, required super.child, super.key});

  // Any descendant can call AppTheme.of(context) to access the theme
  static AppTheme of(BuildContext context) =>
    context.dependOnInheritedWidgetOfExactType<AppTheme>()!;

  @override
  bool updateShouldNotify(AppTheme old) => theme != old.theme; // rebuild only on change
}

// Step 1: Define your state class — extend ChangeNotifier
class CartModel extends ChangeNotifier {
  final List<String> _items = [];
  List<String> get items => List.unmodifiable(_items); // read-only view

  void add(String item) {
    _items.add(item);
    notifyListeners(); // broadcast "state changed" to all listeners
  }

  void remove(String item) {
    _items.remove(item);
    notifyListeners();
  }
}

// Step 2: Wrap your app (or a subtree) with ChangeNotifierProvider
void main() {
  runApp(
    ChangeNotifierProvider(
      create: (_) => CartModel(), // creates ONE instance shared by the whole tree
      child: const MyApp(),
    ),
  );
}

// Step 3: Read the state in any descendant widget
class CartBadge extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final cart = context.watch<CartModel>(); // subscribes — rebuilds on change
    return Text('${cart.items.length} items');
  }
}

class AddToCartButton extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () => context.read<CartModel>().add('Apple'), // read once, no subscription
      child: const Text('Add to Cart'),
    );
  }
}

// Define a provider at the top level (not inside any widget)
final counterProvider = StateNotifierProvider<CounterNotifier, int>(
  (ref) => CounterNotifier(), // Riverpod manages the lifecycle
);

class CounterNotifier extends StateNotifier<int> {
  CounterNotifier() : super(0); // initial state = 0

  void increment() => state++; // changing state triggers rebuilds in watchers
  void decrement() => state--;
}

// Extend ConsumerWidget instead of StatelessWidget to get access to ref
class CounterDisplay extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider); // subscribe to state changes

    return Column(children: [
      Text('$count'),
      ElevatedButton(
        onPressed: () => ref.read(counterProvider.notifier).increment(),
        child: Text('Increment'),
      ),
    ]);
  }
}

// Push a new screen onto the stack — user can go back
Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => const DetailScreen()),
);

// Push with a named route (routes registered in MaterialApp)
Navigator.pushNamed(context, '/details');

// Pop (go back) — optionally pass a return value to the previous screen
Navigator.pop(context, 'result');

// Replace current screen — user cannot go back to previous screen
Navigator.pushReplacement(context, MaterialPageRoute(builder: (_) => HomeScreen()));

// Clear the entire stack and push a new screen (e.g., after login)
Navigator.pushAndRemoveUntil(
  context,
  MaterialPageRoute(builder: (_) => HomeScreen()),
  (route) => false,  // returning false removes ALL previous routes
);

// Passing data to a new screen via constructor
Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => UserScreen(userId: '123', name: 'Kamran'),
  ),
);

// Receiving a result from a screen that was pushed
final result = await Navigator.push<String>(
  context,
  MaterialPageRoute(builder: (_) => PickerScreen()),
);
print(result); // whatever the picker screen passed to Navigator.pop()

// GoRouter setup — declare all routes in one place
final router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(), // / maps to HomeScreen
    ),
    GoRoute(
      path: '/user/:id',
      builder: (context, state) {
        final id = state.pathParameters['id']!; // extract :id from the URL
        return UserScreen(userId: id);
      },
    ),
    GoRoute(
      path: '/settings',
      builder: (context, state) => const SettingsScreen(),
    ),
  ],
);

// Navigate with GoRouter
context.go('/user/123');           // replaces history — no back button
context.push('/settings');         // adds to history — back button works
context.pop();                     // go back
context.goNamed('profile', pathParameters: {'id': '42'}); // navigate by route name

// FutureBuilder — builds different UI based on a Future's current state
FutureBuilder<User>(
  future: fetchUser(),  // the async operation to watch
  builder: (context, snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const CircularProgressIndicator();  // still loading
    }
    if (snapshot.hasError) {
      return Text('Error: ${snapshot.error}');   // something went wrong
    }
    if (!snapshot.hasData) {
      return const Text('No data found');        // done but empty
    }
    // success — render the actual data
    final user = snapshot.data!;
    return Text('Welcome, ${user.name}');
  },
)

// StreamBuilder — rebuilds UI every time a Stream emits a new value
StreamBuilder<int>(
  stream: timerStream(),
  builder: (context, snapshot) {
    if (!snapshot.hasData) return const CircularProgressIndicator();
    return Text('Tick: ${snapshot.data}'); // updates in real time
  },
)

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

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

// Model class — typed representation of the API response
class Post {
  final int id;
  final String title;
  final String body;

  Post({required this.id, required this.title, required this.body});

  // fromJson factory — converts raw Map into a typed Post object
  factory Post.fromJson(Map<String, dynamic> json) {
    return Post(
      id: json['id'] as int,
      title: json['title'] as String,
      body: json['body'] as String,
    );
  }

  // toJson — converts Post back to Map for POST/PUT request bodies
  Map<String, dynamic> toJson() => {'id': id, 'title': title, 'body': body};
}

// GET request — fetch a list of posts
Future<List<Post>> fetchPosts() async {
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/posts'),
  );

  if (response.statusCode == 200) {
    final List<dynamic> data = jsonDecode(response.body); // parse JSON string → List
    return data.map((json) => Post.fromJson(json)).toList(); // convert each item
  } else {
    throw Exception('Failed to load posts: ${response.statusCode}');
  }
}

// POST request — send new data to the server
Future<Post> createPost(String title, String body) async {
  final response = await http.post(
    Uri.parse('https://jsonplaceholder.typicode.com/posts'),
    headers: {'Content-Type': 'application/json'}, // tell server we're sending JSON
    body: jsonEncode({'title': title, 'body': body, 'userId': 1}),
  );

  if (response.statusCode == 201) {
    return Post.fromJson(jsonDecode(response.body)); // server returns the created post
  } else {
    throw Exception('Failed to create post');
  }
}

// AnimatedContainer — animate ANY Container property change automatically
AnimatedContainer(
  duration: Duration(milliseconds: 300), // how long the animation takes
  curve: Curves.easeInOut,               // the speed curve
  width: _isExpanded ? 200 : 100,        // Flutter animates between these values
  height: _isExpanded ? 200 : 100,
  color: _isExpanded ? Colors.blue : Colors.red,
  child: Text('Tap Me'),
)

// AnimatedOpacity — fade in and out
AnimatedOpacity(
  opacity: _isVisible ? 1.0 : 0.0, // 1.0 = fully visible, 0.0 = invisible
  duration: Duration(milliseconds: 500),
  child: Text('I fade in and out'),
)

// AnimatedSwitcher — smoothly transition between two different widgets
AnimatedSwitcher(
  duration: Duration(milliseconds: 300),
  child: Text('$_count', key: ValueKey(_count)), // key change is what triggers the animation
)

class SpinningLogo extends StatefulWidget {
  @override
  State<SpinningLogo> createState() => _SpinningLogoState();
}

class _SpinningLogoState extends State<SpinningLogo>
    with SingleTickerProviderStateMixin { // mixin provides vsync for the controller
  late AnimationController _controller;
  late Animation<double> _rotation;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      vsync: this,                              // syncs animation with screen refresh
      duration: const Duration(seconds: 2),
    )..repeat(); // start immediately and loop forever

    _rotation = Tween<double>(begin: 0, end: 2 * 3.14159).animate(
      CurvedAnimation(parent: _controller, curve: Curves.linear), // defines the value range
    );
  }

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

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: _rotation,
      builder: (context, child) {
        return Transform.rotate(angle: _rotation.value, child: child); // apply rotation each frame
      },
      child: FlutterLogo(size: 100), // child is cached — not rebuilt each frame, only rotated
    );
  }
}

import 'package:shared_preferences/shared_preferences.dart';

// Save values — async because it writes to disk
final prefs = await SharedPreferences.getInstance();
await prefs.setString('username', 'Kamran');
await prefs.setInt('age', 25);
await prefs.setBool('isDarkMode', true);

// Read values — returns null if not set, so always provide a default
final username = prefs.getString('username') ?? 'Guest';
final isDark = prefs.getBool('isDarkMode') ?? false;

// Remove a value — useful for logout flows
await prefs.remove('username');

// Dart side — define the channel and call the native method
static const platform = MethodChannel('com.myapp/battery'); // must match native side

Future<int> getBatteryLevel() async {
  try {
    final level = await platform.invokeMethod<int>('getBatteryLevel'); // send the call
    return level ?? -1;
  } on PlatformException catch (e) {
    throw Exception('Failed: ${e.message}'); // native side threw an error
  }
}

// Android side (Kotlin) — receive and respond to the Dart call
class MainActivity : FlutterActivity() {
  override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)
    MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "com.myapp/battery")
      .setMethodCallHandler { call, result ->
        if (call.method == "getBatteryLevel") {
          val level = getBatteryLevel()    // call the actual Android API
          result.success(level)            // send result back to Dart
        } else {
          result.notImplemented()          // tell Dart this method doesn't exist
        }
      }
  }
}

// Unit test — test pure Dart logic, no UI involved
test('CartModel adds items correctly', () {
  final cart = CartModel();
  cart.add('Apple');
  expect(cart.items.length, 1);         // verify the item was added
  expect(cart.items.first, 'Apple');    // verify the correct item
});

// Widget test — test UI in isolation using a simulated environment
testWidgets('Counter increments smoke test', (WidgetTester tester) async {
  await tester.pumpWidget(const MyApp()); // render the widget

  expect(find.text('0'), findsOneWidget);       // initial state shows 0
  await tester.tap(find.byIcon(Icons.add));     // simulate a tap
  await tester.pump();                          // trigger a rebuild

  expect(find.text('1'), findsOneWidget);       // state changed to 1
});

// Integration test — test the full app flow end-to-end
// Uses flutter_test and integration_test packages
// Runs on a real device or emulator