Flutter-Widgets.md

+[[_TOC_]]
+
 # Brief Overview
 
 Everything in Flutter is a widget. Every component of the UI is made from a widget. Widgets are used to display Ui elements, such as text, buttons, image and more complex elements like lists and forms.
@@ -87,3 +89,83 @@ Perhaps the most common widget, the `Scaffold` widget provides a basic structure
 ### Others
 
 For more build-in widgets, you can visit the [widget catalog](https://docs.flutter.dev/development/ui/widgets) on the official Flutter docs page for a full list
+
+# Example of How These Widgets Are Used
+
+Below is a snippet from the change password page with comments explaining the various parts of the widget:
+```dart
+Widget buildInputScreen(AllPlayersResponse playersResponse) => Padding(
+      // Add 24 pixels of padding around the widget
+      padding: const EdgeInsets.all(24.0),
+      child: Center(
+          // Column is used to display the children vertically
+          child: Column(children: [
+        // Dropdown containing all player names
+        DropdownButtonFormField(
+          // Adds an icon and color to the dropdown
+          decoration: const InputDecoration(
+              prefixIcon: Icon(Icons.person, color: Colors.black)),
+          // Hint is the text that's displayed when no item is selected
+          hint: const Text("Players"),
+          // Initial value of the dropdown
+          value: username,
+          // Method for what to do when the selected item has changed
+          onChanged: (String? value) {
+            setState(() {
+              username = value!;
+            });
+          },
+          // Retrieve the data from the response, map it to a
+          // List, then assign to the dropdown as the dropdown items
+          items: playersResponse.players
+              .map<DropdownMenuItem<String>>((Player player) {
+            return DropdownMenuItem<String>(
+              // value of the dropdown item
+              value: player.playerName,
+              // The text to show for the dropdown item
+              child: Text(player.playerName),
+            );
+          }).toList(),
+        ),
+        // Special TextField to enter new password
+        // PasswordField is a custom widget we created. This defines the
+        // constructor of that widget
+        PasswordField(
+          controller: passwordFirst,
+          validator: validator,
+          notifyParent: refresh,
+        ),
+        // TextField to confirm password
+        TextField(
+          controller: passwordConfirm,
+          // obscureText takes a boolean and defines whether to show the text or
+          // show asterisks instead
+          obscureText: !validator.passwordVisible,
+          decoration: InputDecoration(
+            // Row is used to show elements side by side
+            label: Row(
+              children: [
+                Icon(Icons.key),
+                SizedBox(
+                  width: 10,
+                ),
+                Text('Confirm Password'),
+              ],
+            ),
+            errorText: isMatching ? null : "The two passwords do not match.",
+            fillColor: Colors.grey,
+          ),
+        ),
+        // SizedBox is used as a spacer. This creates an invisible box that's 60 pixels high
+        const SizedBox(
+          height: 60,
+        ),
+        // This is calling the constructor for SubmitButtonBuilder
+        // SubmitButtonBuilder is a class defined on the page with a constructor and
+        // a build method for creating the submit button widget
+        SubmitButtonBuilder(
+            username: username ?? "",
+            password: passwordConfirm,
+            isValid: (isMatching && validator.isSecure && username != null))
+      ])));
+```
\ No newline at end of file