The Starting Point: Notes.dart

Ah, it’s the beginning of a widget! Most importantly, note that it’s a stateless widget. Remember: using scoped_model means you’re dealing with state, but that doesn’t imply you have to have stateful widgets. Stateful widgets are effectively another approach to state, an approach we’re not using in this app (in this source file or any other).

Finally, the widget is returned from the build() method, which you of course know must be present given that this entire source file is defining a widget. You can see the ScopedModel at the top, with a ScopedModelDescendent underneath it, as discussed earlier. An IndexedStack is used to contain the two screens, which are defined in separate source files that we’ll look at soon. Notice that the index value of the IndexedStack is a reference to the stackIndex field in the NotesModel instance. That’s how we can display one screen vs. the other: set the value of stackIndex to 0, and NotesList is shown; set it to 1 to display NotesEntry (assuming, of course, that notifyListeners() is called after that change, which it is, as you saw in BaseModel).

The Model: NotesModel.dart

The model class for this entity is found in NotesModel.dart. The model for this entity type isn’t just the model class though; it’s also a class representing a note.

As you know, this class will extend BaseModel, which itself extends Model from scoped_model, so it must be imported.

Instances of this class represent notes. Each note has four pieces of information: a unique id, a title, content (which is the note text itself), and a color for the background of the Card on the list screen for a note, so each of those is represented by a member variable here. While not required, I also added a toString() method, which overrides the default implementation provided by the Object class , which is the parent of all classes in Dart. That default implementation isn’t beneficial: it just says what type the object it’s called on is. This version instead shows the details of the note, which is very handy when debugging when you want to print() a note object to the console.

Yep, that’s it! Most of what this class needs are provided by BaseModel, so it’s just that color that is an issue. At the risk of jumping the gun a bit: this is needed because when the user selects a color block on the entry screen, just changing the values in a Note instance wouldn’t reflect in the model and the screen wouldn’t know to change. We instead need a direct member of the model class for this to occur. Don’t worry; I don’t expect that you’ll totally understand this part just yet! Once we get to the edit screen, it should start to make sense quickly.

We have a class definition before this, but we don’t have an instance of NotesModel yet. That’s what we get from this line. The file is only ever parsed once, no matter how many times it’s imported, or where it’s imported, so this ensures we only ever have a single instance of NotesModel, which it happens is exactly all we need!

The Database Layer: NotesDBWorker.dart

There’s probably not too much surprising there. The path.dart module contains functions for working with paths on a file system in an ostensibly cross-platform manner. Things like getting the platform separator character, normalizing paths, getting file extensions from a path, and so on. Most of the typical path operations you’d expect are here, but we’ll just need one, which will turn up shortly.

The first step is ensuring there is only ever a single instance of this class, so we’re going to implement a singleton pattern. That begins with creating a private constructor, as seen on the first line. On the second line, the constructor is called, and the instance of the class stored statically in db.

When the database getter is called, we see if there is already an instance in _db. If so, it’s returned, but if not, then the init() method is called. Doing this ensures that the single instance of NotesDBWorker only ever has one Database object in it, which is exactly what we want to ensure no data integrity issues.

The key task here is to make sure the notes database exists in SQLite. The database will be stored as a file in the app’s documents directory, so we need a path to that. Here, the one function from the path module we need is used: the join() method , which concatenates the documents directory path to the name of the file, notes.db (we’re free to call it whatever we want, but I dare say that name is logical).

Once that’s done, we need to create a Database object from that path, which is where the openDatabase() function comes in. We feed it the path, plus a version (which allows you to do schema updates if need be) plus a callback function to call when the database is opened (which here is empty since there’s nothing to do in this situation). We also give it a function to call when the database is created, which is where we create the table we need for notes, assuming it doesn’t already exist. The execute() method of the created Database object is how we do that, and it simply takes the SQL to execute. Once that’s done, the Database instance is returned, which you’ll recall gets stored in _db in the database getter. After that, we’re ready to perform database operations!

Yep, quite simple, and I’d bet entirely apparent to you by now, so let’s get to more exciting stuff: creating a note in the database!

Creating a note is a three-step process. First, we need to get a reference to the Database object, so we await that (remember: the getter function will be called to satisfy this). Second, we need to come up with a unique ID for the note. To do this, we query the existing notes and just increment whatever the highest ID we find is. If this is the first note though, we’ll get null back, so we explicitly deal with that situation (in practice, null for an ID actually does work, but it strikes me as bad form if nothing else, so this check ensures we always have a valid numeric ID).

Once that’s done, the third step is to call the rawInsert() method of the Database object referenced by db is called and a simple SQL query executed to insert the values, which are naturally taken from the Note object passed in as inNote. As you can see, we return the Future that rawInsert() returns, so the caller of create() can await this result, but that’s the only information we need this method to return, so we’re done!

The caller passes in the ID they want to retrieve, and the query() method of the Database instance is called. This takes the name of the table to query, and a where clause (there are multiple forms this method can take, this is just one) plus the values for that where clause. Here, we just need to query the id field. The result of this call will be a map, so we need that noteFromMap() function now to return a Note object.

Here, the query() method just needs the name of the table, and it will dutifully retrieve all the records in it. If we got no records back then an empty list is returned, but if we did get records then we map() the returned list and for each, call noteFromMap(), and finally convert the resultant map to a list to return to the caller.

Well, that’s not too tough, is it? The update() method takes the name of the table, the map that contains the values to update (which we get by calling noteToMap() to convert the inNote Note object to a map) and the where clause to identify the record by ID to be updated. This method knows how to take the elements of the map and convert them to column names – well, there’s no real conversion necessary as it assumes the columns are named after the items in the map, but you knew what I mean!

Yep, that’s all there is to it! By this point, I would bet (and hope!) that an explanation isn’t necessary. So, let’s get to some screen code, starting with the list screen.

The List Screen: NotesList.dart

This Scaffold has a floatingActionButton, which is how the user will add a new note. This floats in the lower right, over the content of the screen. When tapped, the onPressed function fires, and we kick off entry. To do this, we begin by creating a new Note instance and storing it in the model as the entityBeingEdited. This is the object that will ultimately be saved to the database, once all the data the user enters is put into it (which you’ll see in the next section about the entry screen).

One of the things the user can do on the entry screen is select a color for the note. Recall earlier when we talked about how the screen will re-paint itself when the model changes. Well, that’s going to be necessary whenever the user selects a color. But, just having the color stored in that new Note object won’t be enough since scoped_model won’t see it change (because it’s not a top-level property of the model – scoped_model can’t see down into the properties of objects), so as you saw earlier, the NoteModel has a color property. Initially, we want there to be no color selected, hence the call to setColor(), passing it null, which sets the color property of the model and calls notifyListeners() so the screen updates (which doesn’t really matter just yet since the entry screen isn’t shown at this point, but it’s still what happens).

Finally, we move the user to the entry screen by calling setStackIndex() and passing it a value of one, because the entry screen is the second thing on the IndexedStack (IndexedStack is zero-based obviously, and the list screen is at index zero).

We’re using a ListView widget here because we want a scrolling list of items. This requires us to use the builder() constructor, which takes the number of items in the list via itemCount, and that’s just the length of the entityList in the model, and then a function to actually build the widget for each item in the list. For each, we get the Note object from the list, and the first thing we need to do is deal with the color. By default, we’ll assume no color has been specified, which means the note will be white. For all the others, we set the correct color from the Colors collection (note that the value of these constants are objects, not simple strings or numbers, which is why I didn’t store those values directly, which necessitates this branching).

It all starts with a Container, and we give it a little bit of padding around on the left, top, and right. This keeps the notes away from the edges of the screen, which is just aesthetically a little more pleasing, and ensures we have some space between notes.

Next, we come to that Slidable that we saw imported earlier. This widget is just a type of container that introduces some slide functionality. In many mobile apps, when there is a list of items, you can slide them left and/or right to reveal buttons for various functions. That’s what this widget does for us. In simplest terms, you have to provide it a delegate that controls how the slide is animated (which here is just an instance of the SlidableDrawerDelegate() , also provided by this plugin). You also have to tell it how far the item can be slid, and here .25 means 25% of the way across the screen. Then, you have to specify the actions and/or secondaryActions properties. The actions property specifies what functions will be exposed with then item is slid to the right while secondaryActions are what functions will be exposed when the item is slid to the left. Here, we only have a delete action to implement, and most typically you see delete actions on the right (though there’s no rule that says it has to be that way), so secondaryActions is all I used for sliding to the left.

Inside the Container and Slidable, each note is represented by a Card, which you will recall provides a box with a drop shadow on it as per Google’s Material design guidelines. These look a little bit like sticky notes to my eyes, so I felt this was a good choice here. I bump up the elevation a little bit to give them more pronounced drop shadows, and the color, of course, uses the color we determined earlier. Then, the child of the card is just a ListTile. This widget gives us a common way to lay out content with a title, which is the note title, and subtitle, which here I use to display the note’s content. The note will expand vertically as much as necessary to show all the content. The ListTile is a very common widget that is typically used as the child of a ListView, but as you can see, it doesn’t have to be a direct child of one (it doesn’t even have to be an indirect child of one technically). You’ll see more of this widget in the next chapter as well and see some other capabilities it has.

Now, when a note is tapped, we want the user to be able to edit it. This looks almost the same as creating a new note with one critical exception: the note is retrieved from the database. This is actually unnecessary since we already effectively have it in the entityList property in the model. However, for demonstration purposes, I thought it was better to show it coming from the database (there’s also something to be said for having the database be the Single Source Of Truth™ for the app, which wouldn’t be the case if we took it from entityList).

As with most delete operations, confirming the user’s intent is a nice thing to do, so we’ll launch a dialog to do that with showDialog(). In order to do that, we need the BuildContext in effect where the dialog is shown from, which is passed in, along with the Note instance so that we can use some of its data (the title) in the dialog. Then, inside the builder() function that showDialog() requires, we construct an AlertDialog, the content of which asks for confirmation and shows the note’s title. Then, for the actions, we build two: a cancel FlatButton, which simply pop()’s the dialog away, and the delete FlatButton. When the latter is tapped, we call the delete() method of the NotesDBWorker (it’s db property technically, which actually is the NotesDBWorker singleton instance), passing it the id of the note. Then, we pop() the dialog away, and use the showSnackBar() method of the Scaffold to show a message indicating the note was deleted. This will show for two seconds as per the Duration. Finally, the loadData() method of notesModel needs to be called so that the list will be refreshed. Recall that loadData() will re-load all the notes from the database and then call notifyListeners(), which triggers re-painting of the screen. This has to happen after removing a note; otherwise, it would be deleted from the database but not reflect that on the screen.

The Entry Screen: NotesEntry.dart

Now we come to the final part of the notes puzzle, the entry screen. It’s a simple screen, as you can see in Figure 5-4.

The title (which I’ve entered here) and the content (which I haven’t entered) are required (and you can see the error message for content where I’ve tried to save without entering anything). The color boxes are optional, but here I’ve selected red (which you can’t see on a black-and-white printed page, so just trust me, m’kay?!), indicated by it being a bit bigger. There’s a Cancel and a Save button, the former returns the user to the list screen, and the latter, of course, saves the new note (and, as I’m hoping you’ve realized by now, triggers re-painting of the list screen to show the new note).

Nothing new here as far as the imports go, and the widget class start is also what you’ve seen before. Keep in mind that this is still a stateless widget, despite having to deal with some state.

A TextFormField, which is what the title and content will be entered with, needs to have a TextEditingController associated with it to deal with things like its default value and the various events that can occur as the user is typing. But, we’re going to need access to these from our code too, so we create two, and they will be hooked up to the TextFormFields when we define them later but as properties of our class, are available to our application code too (as opposed to defining them inline with the TextFormFields, in which case we wouldn’t have any way to reference them, not without hackery anyway!)

We don’t so much care what the key is, only that we have one, so a simple GlobalKey is created.

See! We really did need access to those two controllers! The trick here is that any time the value of the TextFormField the controller is attached to changes, the corresponding value in entityBeingEdited needs to be updated. Calling addListener() and giving it a function to be called that does that accomplishes that goal. Without doing this, whatever the user enters on the screen wouldn’t be reflected in the model, so we’d have nothing to save later.

Since this screen can effectively be used in two modes, adding and maintaining a note, we’ll want to make sure the previous values for title and content are on the screen when editing one. That’s what these statements do. When the screen is in add mode, it will just be setting null values, since that’s the default for a String, which is what the title and content properties of the Note class are. The TextFormField handles that nicely and just makes them blank as we want; otherwise, whatever the current value is when editing a Note will be shown.

The bottomNavigationBar of the Scaffold widget lets us put some static content at the bottom, content that won’t scroll away even if what’s above it requires scrolling. That’s perfect for buttons, which is exactly what we have here. The first one is Cancel, which navigates the user back the list screen via a call to setStackIndex(). Just before that though, we need to hide the soft keyboard if it’s open. Otherwise, it’ll still be there obscuring the ListView on the notes list screen. The FocusScope class establishes a scope in which widgets can receive focus. Flutter keeps track via a focus tree of which widget is the user’s current focus. When you get the FocusScope of a given context via the static of() method, you can then call the requestFocus() method to send focus to a specific place, but passing a new FocusNode() instance effectively results in focus not going anywhere, which causes the OS to collapse the keyboard and mission accomplished!

In the previous two chapters, you saw how you can optionally have a Form widget so that you can have, among other things, validation events for your entry fields. That’s precisely what we want here, and of course, that _formKey that was created earlier is used here. The children are ListTile widgets, and here you can see one of the other things that widget provides: leading. This can be some content on the left side of the main content, and an Icon as shown here is typical. This widget also supports a trailing property to do the same on the right side, but that’s not needed here.

The title of the ListTile is the first TextFormField. It might seem weird that a property named title isn’t just a text string, but that’s the beauty of everything being a widget in Flutter: it doesn’t (usually) matter! You can put anything you want there, so long as it’s a widget (whether it’ll look good or work as you expect is another matter of course, but it will ostensibly work virtually all the time, that’s the point). This TextFormField has a decoration whose value is an InputDecoration object that. This object has many properties including labelText (text that describes the field), enabled (for visually enabling or disabling the field), suffixIcon (an icon that that appears after the editable part of the text field and after the suffix or suffixText, within the decoration’s container), just to name a few. It also has a hintText property. Setting this as shown has the effect of showing the word “Title” as slightly dimmed text whenever the field is empty of user input. It serves the same function as a label in other words. As you can see, the controller property references the TextEditingController created earlier for this field, and there is a validator defined that checks to ensure something has been entered and which returns an error string if not that will be displayed in red below the field once the form is validated, which happens in that _save() method that we’ll get into soon.

It’s almost the same as that of the title field, save for one thing: the maxLines. This determines how tall the field will be. Here, there will be enough space for eight lines of text. If you know HTML, this in effect makes this TextFormField work like a <textarea>.

We start with another ListTile, with a leading that shows a color palette icon (Flutter calls it a color “lens,” but whatever, looks like a palette to me!). The title this time is a Row so that all the blocks can be laid out next to each other.

Each block beings with a GestureDetector , which is a widget that gives us an element that responds to various touch events. We only care about tap events here though, hence the onTap() function provided. That’s jumping ahead though! Inside the GestureDetector is a Container, and this widget has a decoration that defines a box with a Border around all sides. The box is given a border eighteen pixels wide, which effectively results in a filled box since there is no content, so the borders in a sense “collapse” into a solid box. Then, another Border is added to that, again using the all() constructor, to put a six-pixel wide border around that box. If the color property in the model has a value of red, then the border’s color is made red. Otherwise, it’s made the same color as the background, which we can get by interrogating the Theme associated with this BuildContext. The canvasColor is the background that everything is drawn on, so that’s the element of Theme that we want. The idea here is that the box will be made thicker by virtue of that outer border only when it’s selected.

When the block is tapped, then the color is set in entityBeingEdited, and also it’s set as the color attribute of the model via the call to setColor(). That call also results in notifyListeners() being called, which causes this screen to be re-painted, which finally results in the border now being shown in the box’s color, and that’s how the box appearing bigger effect is achieved.

This, obviously, is what persists the note to the database. First, the form is validated, and if it’s not valid, then the event is terminated via the early return. If it’s valid, then the first thing to determine is whether we’re creating a new note or updating one. Since there’s no flag specifically for this purpose, we must interrogate the data to tell, and that’s easy: a new note won’t yet have an id, but one being updated will. So, we branch on inModel.entityBeingUpdated.id being null or not. If it is, then a call to the create() method of the NotesDBWorker is the right thing to do. Otherwise, we’re updating, so it’s the update() method that needs to be called. In either case, the entityBeingEdited is what gets passed to it. As you saw earlier, that will be converted to a map and saved to the database.

With the note saved, we just have some final tasks to accomplish to complete the process. First, a call to loadData() needs to be made so that the list screen will be updated to reflect the new note or the changes to an existing one. Then, we navigate the user back to the entry screen with the call to setStackIndex(). Finally, we snow a SnackBar message for two seconds to indicate that the note was saved.

And that, as they say, is a wrap on notes!