RFC: Different approach to Editor tutorial (see #189) (#883)

Update test/editor code and tutorial (#189, #883)

Different, sequential approach to Editor tutorial
Co-authored-by: Albrecht Schlosser <albrechts.fltk@online.de>

1 files changed, 742 insertions, 424 deletions

diff --git a/documentation/src/editor.dox b/documentation/src/editor.dox
index eaafe3aec..7358417e4 100644
--- a/documentation/src/editor.dox
+++ b/documentation/src/editor.dox
@@ -1,622 +1,940 @@
 /**
 
- \page  editor Designing a Simple Text Editor
 
-This chapter takes you through the design of a simple
-FLTK-based text editor.
+\page  editor  Designing a Simple Text Editor
+
+This chapter guides you through the design of a simple FLTK-based text editor.
+The complete source code for our text editor can be found in
+the test/editor.cxx file.
+
+The tutorial comprises multiple chapters, and you can activate the relevant
+code by adjusting the TUTORIAL_CHAPTER macro at the top of the source file
+to match the chapter number.
+
+Each chapter builds on the previous one. The documentation, as well as the
+source code, can be read sequentially, maintaining a consistent program
+structure while introducing additional features step by step.
+
+\note The tutorial uses several global variables for brevity. Additionally,
+the order of code blocks is rather uncommon but helps to keep related
+features within a chapter.
+
+<!-- ----------------------------------------------------- -->
 
 \section editor_goals Determining the Goals of the Text Editor
 
-Since this will be the first big project you'll be doing with FLTK,
-lets define what we want our text editor to do:
+As our first step, we define what we want our text editor to do:
 
+-# Edit a single text document.
 -# Provide a menubar/menus for all functions.
--# Edit a single text file, possibly with multiple views.
 -# Load from a file.
 -# Save to a file.
--# Cut/copy/delete/paste functions.
--# Search and replace functions.
 -# Keep track of when the file has been changed.
+-# Cut/copy/delete/paste menus.
+-# Search and replace functionality.
+-# Multiple views of the same text.
+-# "C" language syntax highlighting.
 
 <!-- NEED 4in -->
 
-\section editor_main_window Designing the Main Window
 
-Now that we've outlined the goals for our editor, we can begin with
-the design of our GUI. Obviously the first thing that we need is a
-window, which we'll place inside a class called \p EditorWindow:
+<!-- ----------------------------------------------------- -->
+
+\section editor_main_window Chapter 1: A Minimal App
+
+Let's ensure that we can set up our build process to compile and verify our
+code as we add features. We begin by writing a minimal program with no
+other purpose than opening a window.
+
+The code for that is barely longer than a "Hello, world" program and is
+marked in the source code as `TUTORIAL_CHAPTER = 1`.
 
 \code
-class EditorWindow : public Fl_Double_Window {
-  public:
-    EditorWindow(int w, int h, const char* t);
-    ~EditorWindow();
+#include <FL/Fl_Double_Window.H>
+#include <FL/Fl.H>
 
-    Fl_Window          *replace_dlg;
-    Fl_Input           *replace_find;
-    Fl_Input           *replace_with;
-    Fl_Button          *replace_all;
-    Fl_Return_Button   *replace_next;
-    Fl_Button          *replace_cancel;
+Fl_Double_Window *app_window = NULL;
 
-    Fl_Text_Editor     *editor;
-    char               search[256];
-};
+void tut1_build_app_window() {
+  app_window = new Fl_Double_Window(640, 480, "FLTK Editor");
+}
+
+int main (int argc, char **argv) {
+  tut1_build_app_window();
+  app_window->show(argc, argv);
+  return Fl::run();
+}
 \endcode
 
-\section editor_variables Variables
+Passing `argc` and `argv` to `Fl_Double_Window::show()` allows FLTK to parse
+command line options, providing the user with the ability to change the
+color or graphical scheme of the editor at launch time.
+
+`Fl::run()` will return when no more windows in the app are visible.
+In other words, if all windows in an app are closed, hidden, or deleted.
+Pressing "Escape" or clicking the "Close" button in the window frame will
+close our only window, prompting `Fl::run()` to return, effectively
+ending the app.
+
+When building FLTK from source, the `CMake` environment includes the
+necessary rules to build the editor. You can find more information on
+how to write your own `CMake` files in the `README.CMake.txt` text in the
+top FLTK directory.
 
-Our text editor will need some global variables to keep track of things:
+For Linux and macOS, FLTK comes with the `fltk-config` script that generates
+the compiler commands for you:
 
 \code
-int            changed = 0;
-char           filename[FL_PATH_MAX] = "";
-char           title[FL_PATH_MAX];
-Fl_Text_Buffer *textbuf = 0;
+fltk-config --compile editor.cxx
 \endcode
 
-The \p textbuf variable is the text editor buffer for
-our window class described previously. We'll cover the other
-variables as we build the application.
+If the code compiles and links correctly, running the app will pop up an
+empty application window on the desktop screen. You can close the window
+and quit the app by pressing the 'Escape' key or by clicking the "Close"
+button in the window frame.
+
+Congratulations, you've just built a minimal FLTK app.
+
 
-\section editor_menubars Menubars and Menus
+<!-- ----------------------------------------------------- -->
 
-The first goal requires us to use a menubar and menus that
-define each function the editor needs to perform. The Fl_Menu_Item
-structure is used to define the menus and items in a menubar:
+\section editor_main_menu Chapter 2: Adding a Menu Bar
+
+In this chapter, we will add the main menu bar with a File menu and a
+Quit button. This is a good time to define a flag that will track
+changes in the text later.
 
 \code
-Fl_Menu_Item menuitems[] = {
-  { "&File",              0, 0, 0, FL_SUBMENU },
-    { "&New File",        0, (Fl_Callback *)new_cb },
-    { "&Open File...",    FL_COMMAND + 'o', (Fl_Callback *)open_cb },
-    { "&Insert File...",  FL_COMMAND + 'i', (Fl_Callback *)insert_cb, 0, FL_MENU_DIVIDER },
-    { "&Save File",       FL_COMMAND + 's', (Fl_Callback *)save_cb },
-    { "Save File &As...", FL_COMMAND + FL_SHIFT + 's', (Fl_Callback *)saveas_cb, 0, FL_MENU_DIVIDER },
-    { "New &View", FL_ALT + 'v', (Fl_Callback *)view_cb, 0 },
-    { "&Close View", FL_COMMAND + 'w', (Fl_Callback *)close_cb, 0, FL_MENU_DIVIDER },
-    { "E&xit", FL_COMMAND + 'q', (Fl_Callback *)quit_cb, 0 },
-    { 0 },
+// remove `main()` from chapter 1, but keep the rest of the code, then add...
 
-  { "&Edit", 0, 0, 0, FL_SUBMENU },
-    { "&Undo",       FL_COMMAND + 'z', (Fl_Callback *)undo_cb, 0, FL_MENU_DIVIDER },
-    { "Cu&t",        FL_COMMAND + 'x', (Fl_Callback *)cut_cb },
-    { "&Copy",       FL_COMMAND + 'c', (Fl_Callback *)copy_cb },
-    { "&Paste",      FL_COMMAND + 'v', (Fl_Callback *)paste_cb },
-    { "&Delete",     0, (Fl_Callback *)delete_cb },
-    { 0 },
+#include <FL/Fl_Menu_Bar.H>
+#include <FL/fl_ask.H>
 
-  { "&Search", 0, 0, 0, FL_SUBMENU },
-    { "&Find...",       FL_COMMAND + 'f', (Fl_Callback *)find_cb },
-    { "F&ind Again",    FL_COMMAND + 'g', find2_cb },
-    { "&Replace...",    FL_COMMAND + 'r', replace_cb },
-    { "Re&place Again", FL_COMMAND + 't', replace2_cb },
-    { 0 },
+Fl_Menu_Bar *app_menu_bar = NULL;
+bool text_changed = false;
 
-  { 0 }
-};
-\endcode
+void menu_quit_callback(Fl_Widget *, void *) { /* TODO */ }
 
-Once we have the menus defined we can create the
-Fl_Menu_Bar widget and assign the menus to it with:
+void tut2_build_app_menu_bar() {
+  app_window->begin();
+  app_menu_bar = new Fl_Menu_Bar(0, 0, app_window->w(), 25);
+  app_menu_bar->add("File/Quit Editor", FL_COMMAND+'q', menu_quit_callback);
+  app_window->callback(menu_quit_callback);
+  app_window->end();
+}
 
-\code
-Fl_Menu_Bar *m = new Fl_Menu_Bar(0, 0, 640, 30);
-m->copy(menuitems);
+int main (int argc, char **argv) {
+  tut1_build_app_window();
+  tut2_build_app_menu_bar();
+  app_window->show(argc, argv);
+  return Fl::run();
+}
 \endcode
 
-We'll define the callback functions later.
+`begin()` tells FLTK to add all widgets created hereafter to our
+`app_window`. In this particular case, it is redundant because creating
+the window in the previous chapter already called `begin()` for us.
 
-\section editor_editing Editing the Text
+In the next line, we create the menu bar and add our first menu item
+to it. Menus can be constructed like file paths, with forward slashes
+'/' separating submenus from menu items.
 
-To keep things simple our text editor will use the
-Fl_Text_Editor widget to edit the text:
+Our basic callback is simple:
 
 \code
-w->editor = new Fl_Text_Editor(0, 30, 640, 370);
-w->editor->buffer(textbuf);
+void menu_quit_callback(Fl_Widget *, void *) {
+  Fl::hide_all_windows();
+}
 \endcode
 
-So that we can keep track of changes to the file, we also want to add
-a "modify" callback:
+`Fl::hide_all_windows()` will make all windows invisible, causing `Fl::run()`
+to return and `main` to exit.
 
-\code
-textbuf->add_modify_callback(changed_cb, w);
-textbuf->call_modify_callbacks();
-\endcode
+The next line, `app_window->callback(menu_quit_callback)` links the same
+`menu_quit_callback` to the `app_window` as well. Assigning the window
+callback removes the default "Escape" key handling and allows the
+`menu_quit_callback` to handle that keypress with a friendly dialog box
+instead of just quitting the app.
 
-Finally, we want to use a mono-spaced font like \p FL_COURIER:
+The `Fl_Widget*` parameter in the callback will either be `app_window` if
+called through the window callback, or `app_menu_bar` if called by one of
+the menu items.
+
+One of our goals was to keep track of text changes. If we know the
+text changed and is unsaved, we should notify the user that she is
+about to lose her work. We achieve this by adding a dialog box in
+the Quit callback that queries if the user really wants to quit,
+even if text was changed:
 
 \code
-w->editor->textfont(FL_COURIER);
+void menu_quit_callback(Fl_Widget *, void *) {
+  if (text_changed) {
+    int c = fl_choice("Changes in your text have not been saved.\n"
+                      "Do you want to quit the editor anyway?",
+                      "Quit", "Cancel", NULL);
+    if (c == 1) return;
+  }
+  Fl::hide_all_windows();
+}
 \endcode
 
-\section editor_replace_dialog The Replace Dialog
 
-We can use the FLTK convenience functions for many of the
-editor's dialogs, however the replace dialog needs its own
-custom window.  To keep things simple we will have a
-"find" string, a "replace" string, and
-"replace all", "replace next", and
-"cancel" buttons.  The strings are just
-Fl_Input widgets, the "replace all" and
-"cancel" buttons are Fl_Button widgets, and
-the "replace next " button is a
-Fl_Return_Button widget:
+<!-- ----------------------------------------------------- -->
+
+\section editor_text_widget Chapter 3: Adding a Text Editor widget
+
+FLTK comes with a pretty capable builtin text editing widget. We will use
+this `Fl_Text_Editor` widget here to allow users to edit their documents.
 
-\image html editor-replace.png "The search and replace dialog"
-\image latex editor-replace.png "The search and replace dialog" width=10cm
+`Fl_Text_Editor` needs an `Fl_Text_Buffer` to do anything useful. What
+might seem like an unnecessary extra step is a great feature: we can
+assign one text buffer to multiple text editors. In a later chapter,
+we will use this feature to implement a split editor window.
 
 \code
-Fl_Window *replace_dlg = new Fl_Window(300, 105, "Replace");
-Fl_Input *replace_find = new Fl_Input(70, 10, 200, 25, "Find:");
-Fl_Input *replace_with = new Fl_Input(70, 40, 200, 25, "Replace:");
-Fl_Button *replace_all = new Fl_Button(10, 70, 90, 25, "Replace All");
-Fl_Button *replace_next = new Fl_Button(105, 70, 120, 25, "Replace Next");
-Fl_Button *replace_cancel = new Fl_Button(230, 70, 60, 25, "Cancel");
+#include <FL/Fl_Text_Buffer.H>
+#include <FL/Fl_Text_Editor.H>
+#include <FL/filename.H>
+
+Fl_Text_Editor *app_editor = NULL;
+Fl_Text_Editor *app_split_editor = NULL; // for later
+Fl_Text_Buffer *app_text_buffer = NULL;
+char app_filename[FL_PATH_MAX] = "";
+
+// ... callbacks go here
+
+void tut3_build_main_editor() {
+  app_window->begin();
+  app_text_buffer = new Fl_Text_Buffer();
+  app_text_buffer->add_modify_callback(text_changed_callback, NULL);
+  app_editor = new Fl_Text_Editor(0, app_menu_bar->h(),
+    app_window->w(), app_window->h() - app_menu_bar->h());
+  app_editor->buffer(app_text_buffer);
+  app_editor->textfont(FL_COURIER);
+  app_window->resizable(app_editor);
+  app_window->end();
+}
 \endcode
 
-\section editor_callbacks Callbacks
+By setting the `app_editor` to be the `resizable()` property of
+`app_window`, we make our application window resizable on the desktop,
+and we ensure that resizing the window will only resize the text editor
+vertically, but not our menu bar.
 
-Now that we've defined the GUI components of our editor, we
-need to define our callback functions.
+To keep track of changes to the document, we add a callback to the text
+editor that will be called whenever text is added or deleted. The text modify
+callback sets our `text_changed` flag if text was changed:
 
-\subsection editor_changed_cb changed_cb()
+\code
+// insert before tut3_build_main_editor()
+void text_changed_callback(int, int n_inserted, int n_deleted, int, const char*, void*) {
+  if (n_inserted || n_deleted)
+    text_changed = true;
+}
+\endcode
 
-This function will be called whenever the user changes any text in the
-\p editor widget:
+To wrap this chapter up, we add a "File/New" menu and link it to a callback
+that clears the text buffer, clears the current filename, and marks the buffer
+as unchanged.
 
 \code
-void changed_cb(int, int nInserted, int nDeleted,int, const char*, void* v) {
-  if ((nInserted || nDeleted) && !loading) changed = 1;
-  EditorWindow *w = (EditorWindow *)v;
-  set_title(w);
-  if (loading) w->editor->show_insert_position();
+// insert before tut3_build_main_editor()
+void menu_new_callback(Fl_Widget*, void*) {
+  app_text_buffer->text("");
+  text_changed = false;
 }
+
+// insert at the end of tut3_build_main_editor()
+  ...
+  // find the Quit menu and insert the New menu there
+  int ix = app_menu_bar->find_index(menu_quit_callback);
+  app_menu_bar->insert(ix, "New", FL_COMMAND+'n', menu_new_callback);
+  ...
 \endcode
 
-The \p set_title() function is one that we will write to set
-the changed status on the current file.  We're doing it this way
-because we want to show the changed status in the window's
-title bar.
 
-\subsection editor_copy_cb copy_cb()
+<!-- ----------------------------------------------------- -->
+
+\section editor_file_support Chapter 4: Reading and Writing Files
 
-This callback function will call Fl_Text_Editor::kf_copy()
-to copy the currently selected text to the clipboard:
+In this chapter, we will add support for loading and saving text files,
+so we need three more menu items in the File menu: Open, Save, and Save As.
 
 \code
-void copy_cb(Fl_Widget*, void* v) {
-  EditorWindow* e = (EditorWindow*)v;
-  Fl_Text_Editor::kf_copy(0, e->editor);
+#include <FL/Fl_Native_File_Chooser.H>
+#include <FL/platform.H>
+#include <errno.h>
+
+// ... add callbacks here
+
+void tut4_add_file_support() {
+  int ix = app_menu_bar->find_index(menu_quit_callback);
+  app_menu_bar->insert(ix, "Open", FL_COMMAND+'o', menu_open_callback, NULL, FL_MENU_DIVIDER);
+  app_menu_bar->insert(ix+1, "Save", FL_COMMAND+'s', menu_save_callback);
+  app_menu_bar->insert(ix+2, "Save as...", FL_COMMAND+'S', menu_save_as_callback, NULL, FL_MENU_DIVIDER);
 }
 \endcode
 
-\subsection editor_cut_cb cut_cb()
+\note The menu shortcuts <TT>FL_COMMAND+'s'</TT> and <TT>FL_COMMAND+'S'</TT>
+look the same at a first glance, but the second shortcut is actually
+<TT>Ctrl-Shift-S</TT> due to the capital letter 'S'. Also, we use
+<TT>FL_COMMAND</TT> as our menu shortcut modifier key. <TT>FL_COMMAND</TT>
+translates to `FL_CTRL` on Windows and Linux, and to `FL_META` on macOS,
+better known as the cloverleaf, or simply "the Apple key".
 
-This callback function will call Fl_Text_Editor::kf_cut()
-to cut the currently selected text to the clipboard:
+We implement the Save As callback first, because we will want to call it from
+the Open callback later. The basic callback is only a few lines of code.
 
 \code
-void cut_cb(Fl_Widget*, void* v) {
-  EditorWindow* e = (EditorWindow*)v;
-  Fl_Text_Editor::kf_cut(0, e->editor);
+void menu_save_as_callback(Fl_Widget*, void*) {
+  Fl_Native_File_Chooser file_chooser;
+  file_chooser.title("Save File As...");
+  file_chooser.type(Fl_Native_File_Chooser::BROWSE_SAVE_FILE);
+  if (file_chooser.show() == 0) {
+    app_text_buffer->savefile(file_chooser.filename());
+    strncpy(app_filename, file_chooser.filename(), FL_PATH_MAX-1);
+    text_changed = false;
+  }
 }
 \endcode
 
-\subsection editor_delete_cb delete_cb()
+However if the user has already set a file name including path information,
+it is the polite thing to preload the file chooser with that information. This
+little chunk of code will separate the file name from the path before we call
+`file_chooser.show()`:
+
+\code
+// insert before `if (file_chooser.show()...`
+  if (app_filename[0]) {
+    char temp_filename[FL_PATH_MAX];
+    strncpy(temp_filename, app_filename, FL_PATH_MAX-1);
+    const char *name = fl_filename_name(temp_filename);
+    if (name) {
+      file_chooser.preset_file(name);
+      temp_filename[name - temp_filename] = 0;
+      file_chooser.directory(temp_filename);
+    }
+  }
+\endcode
 
-This callback function will call Fl_Text_Buffer::remove_selection()
-to delete the currently selected text to the clipboard:
+Great. Now let's add code for our File/Save menu. If no filename was set yet,
+it falls back to our Save As callback. `Fl_Text_Editor::savefile()` writes
+the contents of our text widget into a UTF-8 encoded text file.
 
 \code
-void delete_cb(Fl_Widget*, void* v) {
-  textbuf->remove_selection();
+void menu_save_callback(Fl_Widget*, void*) {
+  if (!app_filename[0]) {
+    menu_save_as_callback(NULL, NULL);
+  } else {
+    app_text_buffer->savefile(file_chooser.filename());
+    text_changed = false;
+  }
 }
 \endcode
 
-\subsection editor_find_cb find_cb()
-
-This callback function asks for a search string using the
-fl_input() convenience function and then calls the \p find2_cb()
-function to find the string:
+On to loading a new file. Let's write the function to load a file
+from a given file name:
 
 \code
-void find_cb(Fl_Widget* w, void* v) {
-  EditorWindow* e = (EditorWindow*)v;
-  const char *val;
-
-  val = fl_input("Search String:", e->search);
-  if (val != NULL) {
-    // User entered a string - go find it!
-    strcpy(e->search, val);
-    find2_cb(w, v);
+void load(const char *filename) {
+  if (app_text_buffer->loadfile(filename) == 0) {
+    strncpy(app_filename, filename, FL_PATH_MAX-1);
+    text_changed = false;
   }
+}
 \endcode
 
-\subsection editor_find2_cb find2_cb()
-
-This function will find the next occurrence of the search
-string. If the search string is blank then we want to pop up the
-search dialog:
+A friendly app should warn the user if file operations fail. This can be
+done in three lines of code, so let's add an alert dialog after every `loadfile`
+and `savefile` call. This is exemplary for `load()`, and the
+code is very similar for the two other locations.
 
 \code
-void find2_cb(Fl_Widget* w, void* v) {
-  EditorWindow* e = (EditorWindow*)v;
-  if (e->search[0] == '\0') {
-    // Search string is blank; get a new one...
-    find_cb(w, v);
-    return;
+void load(const char *filename) {
+  if (app_text_buffer->loadfile(filename) == 0) {
+    strncpy(app_filename, filename, FL_PATH_MAX-1);
+    text_changed = false;
+  } else {
+    fl_alert("Failed to load file\n%s\n%s",
+             filename,
+             strerror(errno));
   }
+}
+\endcode
 
-  int pos = e->editor->insert_position();
-  int found = textbuf->search_forward(pos, e->search, &pos);
-  if (found) {
-    // Found a match; select and update the position...
-    textbuf->select(pos, pos+strlen(e->search));
-    e->editor->insert_position(pos+strlen(e->search));
-    e->editor->show_insert_position();
+If the user selects our pulldown "Load" menu, we first check if the current
+text was modified and provide a dialog box that offers to save the changes
+before loading a new text file:
+
+\code
+void menu_open_callback(Fl_Widget*, void*) {
+  if (text_changed) {
+    int r = fl_choice("The current file has not been saved.\n"
+                      "Would you like to save it now?",
+                      "Cancel", "Save", "Don't Save");
+    if (r == 2)
+      return;
+    if (r == 1)
+      menu_save_callback();
   }
-  else fl_alert("No occurrences of \'%s\' found!", e->search);
-}
+  ...
 \endcode
 
-If the search string cannot be found we use the fl_alert()
-convenience function to display a message to that effect.
+If the user did not cancel the operation, we pop up a file chooser for
+loading the file, using similar code as in Save As.
 
-\subsection editor_new_cb new_cb()
+\code
+...
+  Fl_Native_File_Chooser file_chooser;
+  file_chooser.title("Open File...");
+  file_chooser.type(Fl_Native_File_Chooser::BROWSE_FILE);
+...
+\endcode
 
-This callback function will clear the editor widget and current
-filename. It also calls the \p check_save() function to give the
-user the opportunity to save the current file first as needed:
+Again, we preload the file chooser with the last used path and file
+name:
 
 \code
-void new_cb(Fl_Widget*, void*) {
-  if (!check_save()) return;
+...
+  if (app_filename[0]) {
+    char temp_filename[FL_PATH_MAX];
+    strncpy(temp_filename, app_filename, FL_PATH_MAX-1);
+    const char *name = fl_filename_name(temp_filename);
+    if (name) {
+      file_chooser.preset_file(name);
+      temp_filename[name - temp_filename] = 0;
+      file_chooser.directory(temp_filename);
+    }
+  }
+...
+\endcode
+
+And finally, we pop up the file chooser. If the user cancels the file
+dialog, we do nothing and keep the current file. Otherwise, we call
+the `load()` function that we already wrote:
 
-  filename[0] = '\0';
-  textbuf->select(0, textbuf->length());
-  textbuf->remove_selection();
-  changed = 0;
-  textbuf->call_modify_callbacks();
+\code
+  if (file_chooser.show() == 0)
+    load(file_chooser.filename());
 }
 \endcode
 
-\subsection editor_open_cb open_cb()
-
-This callback function will ask the user for a filename and then load
-the specified file into the input widget and current filename. It also
-calls the \p check_save() function to give the user the
-opportunity to save the current file first as needed:
+We really should support two more ways to load documents from a file.
+Let's modify the "show and run" part of `main()` to handle command
+line parameters and desktop drag'n'drop operations. For that, we refactor
+the last two lines of `main()` into a new function:
 
 \code
-void open_cb(Fl_Widget*, void*) {
-  if (!check_save()) return;
-
-  char *newfile = fl_file_chooser("Open File?", "*", filename);
-  if (newfile != NULL) load_file(newfile, -1);
+// ... new function here
+
+int main (int argc, char **argv) {
+  tut1_build_app_window();
+  tut2_build_app_menu_bar();
+  tut3_build_main_editor();
+  tut4_add_file_support();
+  // ... refactor those into the new function
+  // app_window->show(argc, argv);
+  // return Fl::run();
+  return tut4_handle_commandline_and_run(argc, argv);
 }
 \endcode
 
-We call the \p load_file() function to actually load the file.
-
-\subsection editor_paste_cb paste_cb()
+Our function to show the window and run the app has a few lines of boilerplate
+code. `Fl::args_to_utf8()` converts the command line argument from whatever
+the host system provides into Unicode. `Fl::args()` goes through the
+list of arguments and gives `args_handler()` a chance to handle each argument.
+It also makes sure that FLTK specific args are still forwarded to FLTK,
+so `"-scheme plastic"` and `"-background #aaccff"` will draw beautiful blue
+buttons in a plastic look.
 
-This callback function will call Fl_Text_Editor::kf_paste()
-to paste the clipboard at the current position:
+`fl_open_callback()` lets FLTK know what to do if a user drops a text
+file onto our editor icon (Apple macOS). Here, we ask it to call the `load()`
+function that we wrote earlier.
 
 \code
-void paste_cb(Fl_Widget*, void* v) {
-  EditorWindow* e = (EditorWindow*)v;
-  Fl_Text_Editor::kf_paste(0, e->editor);
+// ... args_handler here
+
+int tut4_handle_commandline_and_run(int &argc, char **argv) {
+  int i = 0;
+  Fl::args_to_utf8(argc, argv);
+  Fl::args(argc, argv, i, args_handler);
+  fl_open_callback(load);
+  app_window->show(argc, argv);
+  return Fl::run();
 }
 \endcode
 
-\subsection editor_quit_cb quit_cb()
-
-The quit callback will first see if the current file has been
-modified, and if so give the user a chance to save it. It then exits
-from the program:
+Last work item for this long chapter: what should our `args_handler`
+do? We could handle additional command line options here, but for now,
+all we want to handle is file names and paths. Let's make this easy: if the
+current arg does not start with a '-', we assume it is a file name, and
+we call `load()`:
 
 \code
-void quit_cb(Fl_Widget*, void*) {
-  if (changed && !check_save())
-    return;
-
-  exit(0);
+int args_handler(int argc, char **argv, int &i) {
+  if (argv && argv[i] && argv[i][0]!='-') {
+    load(argv[i]);
+    i++;
+    return 1;
+  }
+  return 0;
 }
 \endcode
 
-\subsection editor_replace_cb replace_cb()
+So this is our basic but quite functional text editor app in about
+100 lines of code. The following chapters add some user convenience
+functions and show off some FLTK features including split editors and
+syntax highlighting.
+
+
+<!-- ----------------------------------------------------- -->
 
-The replace callback just shows the replace dialog:
+\section editor_cut_copy_paste Chapter 5: Cut, Copy, and Paste
+
+The FLTK Text Editor widget comes with builtin cut, copy, and
+paste functionality, but as a courtesy, we should also offer these
+as menu items in the main menu.
+
+In our feature list, we noted that we want to implement a split
+text editor. This requires that the callbacks know which text editor
+has the keyboard focus. Calling `Fl::focus()` may return `NULL` or
+other unknown widgets, so we add a little test in our callbacks:
 
 \code
-void replace_cb(Fl_Widget*, void* v) {
-  EditorWindow* e = (EditorWindow*)v;
-  e->replace_dlg->show();
+void menu_cut_callback(Fl_Widget*, void* v) {
+  Fl_Widget *e = Fl::focus();
+  if (e && (e == app_editor || e == app_split_editor))
+    Fl_Text_Editor::kf_cut(0, (Fl_Text_Editor*)e);
 }
 \endcode
 
-\subsection editor_replace2_cb replace2_cb()
-
-This callback will replace the next occurrence of the replacement
-string. If nothing has been entered for the replacement string, then
-the replace dialog is displayed instead:
+We can write very similar callbacks for undo, redo, copy, paste, and delete.
+Adding a new menu and the six menu items follows the same pattern as
+before. Using the Menu/Item notation will create an Edit menu for us:
 
 \code
-void replace2_cb(Fl_Widget*, void* v) {
-  EditorWindow* e = (EditorWindow*)v;
-  const char *find = e->replace_find->value();
-  const char *replace = e->replace_with->value();
+void tut5_cut_copy_paste() {
+  app_menu_bar->add("Edit/Undo",   FL_COMMAND+'z', menu_undo_callback);
+  app_menu_bar->add("Edit/Redo",   FL_COMMAND+'Z', menu_redo_callback, NULL, FL_MENU_DIVIDER);
+  app_menu_bar->add("Edit/Cut",    FL_COMMAND+'x', menu_cut_callback);
+  app_menu_bar->add("Edit/Copy",   FL_COMMAND+'c', menu_copy_callback);
+  app_menu_bar->add("Edit/Paste",  FL_COMMAND+'v', menu_paste_callback);
+  app_menu_bar->add("Edit/Delete", 0,              menu_delete_callback);
+}
+\endcode
 
-  if (find[0] == '\0') {
-    // Search string is blank; get a new one...
-    e->replace_dlg->show();
-    return;
-  }
 
-  e->replace_dlg->hide();
+<!-- ----------------------------------------------------- -->
+
+\section editor_find Chapter 6: Find and Find Next
 
-  int pos = e->editor->insert_position();
-  int found = textbuf->search_forward(pos, find, &pos);
+Corporate called. They want a dialog box for their users that can search
+for some word in the text file. We can add this functionality using
+a callback and a standard FLTK dialog box.
 
+Here is some code to find a string in a text editor. The first four lines
+make sure that we start our search at the cursor position of the current
+editor window. The rest of the code searches the string and marks it
+if found.
+
+\code
+void find_next(const char *needle) {
+  Fl_Text_Editor *editor = app_editor;
+  Fl_Widget *e = Fl::focus();
+  if (e && e == app_split_editor)
+    editor = app_split_editor;
+  int pos = editor->insert_position();
+  int found = app_text_buffer->search_forward(pos, needle, &pos);
   if (found) {
-    // Found a match; update the position and replace text...
-    textbuf->select(pos, pos+strlen(find));
-    textbuf->remove_selection();
-    textbuf->insert(pos, replace);
-    textbuf->select(pos, pos+strlen(replace));
-    e->editor->insert_position(pos+strlen(replace));
-    e->editor->show_insert_position();
+    app_text_buffer->select(pos, pos + (int)strlen(needle));
+    editor->insert_position(pos + (int)strlen(needle));
+    editor->show_insert_position();
+  } else {
+    fl_alert("No further occurrences of '%s' found!", needle);
   }
-  else fl_alert("No occurrences of \'%s\' found!", find);
 }
 \endcode
 
-\subsection editor_replall_cb replall_cb()
-
-This callback will replace all occurrences of the search
-string in the file:
+The callbacks are short, using the FLTK text field dialog box and the
+`find_next` function that we already implemented. The last searched text
+is saved in `last_find_text` to be reused by `menu_find_next_callback`.
+If no search text was set yet, or it was set to an empty text, "Find Next"
+will forward to `menu_find_callback` and pop up our "Find Text" dialog.
 
 \code
-void replall_cb(Fl_Widget*, void* v) {
-  EditorWindow* e = (EditorWindow*)v;
-  const char *find = e->replace_find->value();
-  const char *replace = e->replace_with->value();
+char last_find_text[1024] = "";
 
-  find = e->replace_find->value();
-  if (find[0] == '\0') {
-    // Search string is blank; get a new one...
-    e->replace_dlg->show();
-    return;
+void menu_find_callback(Fl_Widget*, void* v) {
+  const char *find_text = fl_input("Find in text:", last_find_text);
+  if (find_text) {
+    strncpy(last_find_text, find_text, sizeof(last_find_text)-1);
+    find_next(find_text);
   }
+}
 
-  e->replace_dlg->hide();
-
-  e->editor->insert_position(0);
-  int times = 0;
-
-  // Loop through the whole string
-  for (int found = 1; found;) {
-    int pos = e->editor->insert_position();
-    found = textbuf->search_forward(pos, find, &pos);
-
-    if (found) {
-      // Found a match; update the position and replace text...
-      textbuf->select(pos, pos+strlen(find));
-      textbuf->remove_selection();
-      textbuf->insert(pos, replace);
-      e->editor->insert_position(pos+strlen(replace));
-      e->editor->show_insert_position();
-      times++;
-    }
+void menu_find_next_callback(Fl_Widget*, void* v) {
+  if (last_find_text[0]) {
+    find_next(last_find_text);
+  } else {
+    menu_find_callback(NULL, NULL);
   }
-
-  if (times) fl_message("Replaced %d occurrences.", times);
-  else fl_alert("No occurrences of \'%s\' found!", find);
 }
 \endcode
 
-\subsection editor_replcan_cb replcan_cb()
-
-This callback just hides the replace dialog:
+And of course we need to add two menu items to our main application menu.
 
 \code
-void replcan_cb(Fl_Widget*, void* v) {
-  EditorWindow* e = (EditorWindow*)v;
-  e->replace_dlg->hide();
-}
+  ...
+  app_menu_bar->add("Find/Find...",   FL_COMMAND+'f', menu_find_callback);
+  app_menu_bar->add("Find/Find Next", FL_COMMAND+'g', menu_find_next_callback, NULL, FL_MENU_DIVIDER);
+  ...
 \endcode
 
-\subsection editor_save_cb save_cb()
 
-This callback saves the current file.  If the current filename is
-blank it calls the "save as" callback:
+<!-- ----------------------------------------------------- -->
+
+\section editor_replace Chapter 7: Replace and Replace Next
+
+To implement the next feature, we will need to implement our own "Find
+and Replace" dialog box. To make this dialog box useful, it needs the
+following elements:
+
+- a text input field for the text that we want to find
+- a text input field for the replacement text
+- a button to find the next occurrence
+- a button to replace the current text and find the next occurrence
+- a button to close the dialog
+
+This is rather complex functionality, so instead of adding more global
+variables, we will pack this dialog into a class, derived from `Fl_Window`.
+
+\note The tutorial uses `Fl_Double_Window` instead of `Fl_Window` throughout.
+Historically, on some platforms, `Fl_Window` renders faster, but has a
+tendency to flicker. In today's world, this has very little relevance and
+FLTK optimizes both window types. `Fl_Double_Window` is recommended unless
+there is a specific reason to use `Fl_Window`.
+
+Let's implement the text replacement code first:
 
 \code
-void save_cb(void) {
-  if (filename[0] == '\0') {
-    // No filename - get one!
-    saveas_cb();
-    return;
+char last_replace_text[1024] = "";
+
+void replace_selection(const char *new_text) {
+  Fl_Text_Editor *editor = app_editor;
+  Fl_Widget *e = Fl::focus();
+  if (e && e == app_split_editor)
+    editor = app_split_editor;
+  int start, end;
+  if (app_text_buffer->selection_position(&start, &end)) {
+    app_text_buffer->remove_selection();
+    app_text_buffer->insert(start, new_text);
+    app_text_buffer->select(start, start + (int)strlen(new_text));
+    editor->insert_position(start + (int)strlen(new_text));
+    editor->show_insert_position();
   }
-  else save_file(filename);
 }
 \endcode
 
-The \p save_file() function saves the current file to the
-specified filename.
+As before, the first four lines anticipate a split editor and find the
+editor that has focus. The code then deletes the currently selected
+text, replaces it with the new text, selects the new text, and finally
+sets the text cursor to the end of the new text.
 
-\subsection editor_saveas_cb saveas_cb()
+<H3>The Replace_Dialog class</H3>
 
-This callback asks the user for a filename and saves the current file:
+The Replace_Dialog class holds pointers to our active UI elements as
+well as all the callbacks for the dialog buttons.
 
 \code
-void saveas_cb(void) {
-  char *newfile;
+class Replace_Dialog : public Fl_Double_Window {
+  Fl_Input *find_text_input;
+  Fl_Input *replace_text_input;
+  Fl_Button *find_next_button;
+  Fl_Button *replace_and_find_button;
+  Fl_Button *close_button;
+public:
+  Replace_Dialog(const char *label);
+  void show() FL_OVERRIDE;
+private:
+  static void find_next_callback(Fl_Widget*, void*);
+  static void replace_and_find_callback(Fl_Widget*, void*);
+  static void close_callback(Fl_Widget*, void*);
+};
 
-  newfile = fl_file_chooser("Save File As?", "*", filename);
-  if (newfile != NULL) save_file(newfile);
-}
+Replace_Dialog *replace_dialog = NULL;
 \endcode
 
-The \p save_file() function saves the current file to the
-specified filename.
+The constructor creates the dialog and marks it as "non modal". This will
+make the dialog hover over the application window like a toolbox window until
+the user closes it, allowing multiple "find and replace" operations. So here
+is our constructor:
 
-\section editor_other_functions Other Functions
+\code
+Replace_Dialog::Replace_Dialog(const char *label)
+: Fl_Double_Window(430, 110, label)
+{
+  find_text_input = new Fl_Input(100, 10, 320, 25, "Find:");
+  replace_text_input = new Fl_Input(100, 40, 320, 25, "Replace:");
+  Fl_Flex* button_field = new Fl_Flex(100, 70, w()-100, 40);
+  button_field->type(Fl_Flex::HORIZONTAL);
+  button_field->margin(0, 5, 10, 10);
+  button_field->gap(10);
+  find_next_button = new Fl_Button(0, 0, 0, 0, "Next");
+  find_next_button->callback(find_next_callback, this);
+  replace_and_find_button = new Fl_Button(0, 0, 0, 0, "Replace");
+  replace_and_find_button->callback(replace_and_find_callback, this);
+  close_button = new Fl_Button(0, 0, 0, 0, "Close");
+  close_button->callback(close_callback, this);
+  button_field->end();
+  set_non_modal();
+}
+\endcode
 
-Now that we've defined the callback functions, we need our support
-functions to make it all work:
+All buttons are created inside an `Fl_Flex` group. They will be arranged
+automatically by `Fl_Flex`, so there is no need to set x and y coordinates
+or a width or height. `button_field` will lay out the buttons for us.
 
-\subsection editor_check_save check_save()
+\note There is no need to write a destructor or delete individual widgets.
+When we delete an instance of `Replace_Dialog`, all children are deleted
+for us.
 
-This function checks to see if the current file needs to be saved.  If
-so, it asks the user if they want to save it:
+The `show()` method overrides the window's show method. It adds some code to
+preload the values of the text fields for added convenience. It then pops up
+the dialog box by calling the original `Fl_Double_Window::show()`.
 
 \code
-int check_save(void) {
-  if (!changed) return 1;
+void Replace_Dialog::show() {
+  find_text_input->value(last_find_text);
+  replace_text_input->value(last_replace_text);
+  Fl_Double_Window::show();
+}
+\endcode
 
-  int r = fl_choice("The current file has not been saved.\n"
-                    "Would you like to save it now?",
-                    "Cancel", "Save", "Discard");
+The buttons in the dialog need callbacks to be useful. If callbacks are
+defined within a class, they must be defined `static`, but a pointer to the
+class can be provided through the `user_data` field. We have done that in
+the constructor by adding `this` as the last argument when setting the
+callback, for example in `close_button->callback(close_callback, this);`.
 
-  if (r == 1) {
-    save_cb(); // Save the file...
-    return !changed;
-  }
+The callback itself can then extract the `this` pointer with a static cast:
 
-  return (r == 2) ? 1 : 0;
+\code
+void Replace_Dialog::close_callback(Fl_Widget*, void* my_dialog) {
+  Replace_Dialog *dlg = static_cast<Replace_Dialog*>(my_dialog);
+  dlg->hide();
 }
 \endcode
 
-\subsection editor_load_file load_file()
-
-This function loads the specified file into the \p textbuf variable:
+The callback for the Find button uses our already implemented `find_next`
+function:
 
 \code
-int loading = 0;
-void load_file(char *newfile, int ipos) {
-  loading = 1;
-  int insert = (ipos != -1);
-  changed = insert;
-  if (!insert) strcpy(filename, "");
-  int r;
-  if (!insert) r = textbuf->loadfile(newfile);
-  else r = textbuf->insertfile(newfile, ipos);
-  if (r)
-    fl_alert("Error reading from file \'%s\':\n%s.", newfile, strerror(errno));
-  else
-    if (!insert) strcpy(filename, newfile);
-  loading = 0;
-  textbuf->call_modify_callbacks();
+void Replace_Dialog::find_next_callback(Fl_Widget*, void* my_dialog) {
+  Replace_Dialog *dlg = static_cast<Replace_Dialog*>(my_dialog);
+  strncpy(last_find_text, dlg->find_text_input->value(), sizeof(last_find_text)-1);
+  strncpy(last_replace_text, dlg->replace_text_input->value(), sizeof(last_replace_text)-1);
+  if (last_find_text[0])
+    find_next(last_find_text);
 }
 \endcode
 
-When loading the file we use the Fl_Text_Buffer::loadfile()
-method to "replace" the text in the buffer, or the
-Fl_Text_Buffer::insertfile()
-method to insert text in the buffer from the named file.
+The Replace button callback calls our newly implemented `replace_selection`
+function and then continues on to the `find_next_callback`:
 
-\subsection editor_save_file save_file()
+\code
+void Replace_Dialog::replace_and_find_callback(Fl_Widget*, void* my_dialog) {
+  Replace_Dialog *dlg = static_cast<Replace_Dialog*>(my_dialog);
+  replace_selection(dlg->replace_text_input->value());
+  find_next_callback(NULL, my_dialog);
+}
+\endcode
 
-This function saves the current buffer to the specified file:
+This long chapter comes close to its end. We are missing menu items that pop
+up our dialog and that allow a quick "Replace and Find Next" functionality
+without popping up the dialog. The code is quite similar to the "Find" and
+"Find Next" code in the previous chapter:
 
 \code
-void save_file(char *newfile) {
-  if (textbuf->savefile(newfile))
-    fl_alert("Error writing to file \'%s\':\n%s.", newfile, strerror(errno));
-  else
-    strcpy(filename, newfile);
-  changed = 0;
-  textbuf->call_modify_callbacks();
+void menu_replace_callback(Fl_Widget*, void*) {
+  if (!replace_dialog)
+    replace_dialog = new Replace_Dialog("Find and Replace");
+  replace_dialog->show();
+}
+
+void menu_replace_next_callback(Fl_Widget*, void*) {
+  if (!last_find_text[0]) {
+    menu_replace_callback(NULL, NULL);
+  } else {
+    replace_selection(last_replace_text);
+    find_next(last_find_text);
+  }
+}
+
+void tut7_implement_replace() {
+  app_menu_bar->add("Find/Replace...",   FL_COMMAND+'r', menu_replace_callback);
+  app_menu_bar->add("Find/Replace Next", FL_COMMAND+'t', menu_replace_next_callback);
 }
 \endcode
 
-\subsection editor_set_title set_title()
 
-This function checks the \p changed variable and updates the
-window label accordingly:
+
+<!-- ----------------------------------------------------- -->
+
+\section editor_editor_features Chapter 8: Editor Features
+
+Chapter 7 was long an intense. Let's relax and implement something simple here.
+We want menus with check boxes that can toggle some text editor features on
+and off:
+
 \code
-void set_title(Fl_Window* w) {
-  if (filename[0] == '\0') strcpy(title, "Untitled");
-  else {
-    char *slash;
-    slash = strrchr(filename, '/');
-#ifdef _WIN32
-    if (slash == NULL) slash = strrchr(filename, '\\');
-#endif
-    if (slash != NULL) strcpy(title, slash + 1);
-    else strcpy(title, filename);
-  }
+void tut8_editor_features() {
+  app_menu_bar->add("Window/Line Numbers", FL_COMMAND+'l', menu_linenumbers_callback, NULL, FL_MENU_TOGGLE);
+  app_menu_bar->add("Window/Word Wrap", 0, menu_wordwrap_callback, NULL, FL_MENU_TOGGLE);
+}
+\endcode
 
-  if (changed) strcat(title, " (modified)");
+The `Fl_Widget` parameter in callbacks always points to the widget that causes
+the callback. Menu items are not derived from widgets, so to find out which
+menu item caused a callback, we can do this:
 
-  w->label(title);
+\code
+void menu_linenumbers_callback(Fl_Widget* w, void*) {
+  Fl_Menu_Bar* menu = static_cast<Fl_Menu_Bar*>(w);
+  const Fl_Menu_Item* linenumber_item = menu->mvalue();
+  if (linenumber_item->value()) {
+    app_editor->linenumber_width(40);
+  } else {
+    app_editor->linenumber_width(0);
+  }
+  app_editor->redraw();
 }
 \endcode
 
-\section editor_main_function The main() Function
+Setting the width enables the line numbers, setting it to 0 disables the
+line number display. When changing the value of a widget, FLTK will make sure
+that the widget is redrawn to reflect the new value. When changing other
+attributes such as colors or fonts, FLTK assumes that many attributes are
+changed at the same time and leaves it to the user to call
+`Fl_Widget::redraw()` when done. Here we call `app_editor->redraw()` to make
+sure that the change in the line number setting is also drawn on screen.
 
-Once we've created all of the support functions, the only thing left
-is to tie them all together with the \p main() function.
-The \p main() function creates a new text buffer, creates a
-new view (window) for the text, shows the window, loads the file on
-the command-line (if any), and then enters the FLTK event loop:
+Let's not forget to update the line number display
+for a potential split editor widget es well:
 
 \code
-int main(int argc, char **argv) {
-  textbuf = new Fl_Text_Buffer;
+  // add before the end of menu_linenumbers_callback
+  if (app_split_editor) {
+    if (linenumber_item->value()) {
+      app_split_editor->linenumber_width(40);
+    } else {
+      app_split_editor->linenumber_width(0);
+    }
+    app_split_editor->redraw();
+  }
+\endcode
 
-  Fl_Window* window = new_view();
+The word wrap feature is activated by calling `Fl_Text_Editor::wrap_mode()`
+with the parameters `Fl_Text_Display::WRAP_AT_BOUNDS` and `0`. It's
+deactivated with `Fl_Text_Display::WRAP_NONE`. The implementation of
+the callback is the same as `menu_linenumbers_callback`.
 
-  window->show(1, argv);
 
-  if (argc > 1) load_file(argv[1], -1);
+<!-- ----------------------------------------------------- -->
 
-  return Fl::run();
-}
-\endcode
+\section editor_split_editor Chapter 9: Split Editor
 
-\section editor_compiling Compiling the Editor
+When editing long source code files, it can be really helpful to split
+the editor to view statements at the top of the text while
+adding features at the bottom of the text in a split text view.
 
-The complete source for our text editor can be found in the
-\p test/editor.cxx source file.  Both the Makefile and Visual C++
-workspace include the necessary rules to build the editor.  You can
-also compile it using a standard compiler with:
+FLTK can link multiple text editors to a single text buffer. Let's implement
+this now. This chapter will show you how to rearrange widgets in an existing
+widget tree.
+
+Our initializer removes the main text editor from the widget tree and
+replaces it with an `Fl_Tile`. A tile can hold multiple widgets that can
+then be resized interactively by the user by clicking and dragging the divider
+between those widgets.
+
+We start by replacing the editor widget with a tile group of the same size.
 
 \code
-CC -o editor editor.cxx -lfltk -lXext -lX11 -lm
+#include <FL/Fl_Tile.H>
+
+Fl_Tile *app_tile = NULL;
+
+void tut9_split_editor() {
+  app_window->begin();
+  app_tile = new Fl_Tile(app_editor->x(), app_editor->y(),
+                         app_editor->w(), app_editor->h());
+  app_window->remove(app_editor);
 \endcode
 
-or by using the \p fltk-config script with:
+Next we add our existing editor as the first child of the tile and create
+another text editor `app_split_editor` as the second child of the tile, but
+it's hidden for now with a height of zero pixels.
+
+\note Creating the new `Fl_Tile` also calls `Fl_Tile::begin()`.
+<BR><BR>Adding `app_editor` to the tile would have also removed it from
+`app_window`, so `app_window->remove(app_editor)` in the code above is not
+really needed, but illustrates what we are doing.
 
 \code
-fltk-config --compile editor.cxx
+  app_tile->add(app_editor);
+  app_split_editor = new Fl_Text_Editor(app_tile->x(), app_tile->y()+app_tile->h(),
+                                        app_tile->w(), 0);
+  app_split_editor->buffer(app_text_buffer);
+  app_split_editor->textfont(FL_COURIER);
+  app_split_editor->hide();
 \endcode
 
-As noted in \ref basics_standard_compiler, you may need to
-include compiler and linker options to tell them where to find the FLTK
-library. Also, the \p CC command may also be called \p gcc
-or \p c++ on your system.
+Now we clean up after ourselves and make sure that the resizables are all
+set correctly. Lastly, we add a menu item with a callback.
 
-Congratulations, you've just built your own text editor!
+\code
+  app_tile->end();
+  app_tile->size_range(0, 25, 25);
+  app_tile->size_range(1, 25, 25);
+  app_window->end();
+  app_window->resizable(app_tile);
+  app_tile->resizable(app_editor);
+  app_menu_bar->add("Window/Split", FL_COMMAND+'-', menu_split_callback, NULL, FL_MENU_TOGGLE);
+}
+\endcode
 
-\section editor_final_product The Final Product
+Now with all widgets in place, the callback's job is to show and resize, or
+hide and resize the split editor. We can implement that like here:
 
-The final editor window should look like this:
+\code
+void menu_split_callback(Fl_Widget* w, void*) {
+  Fl_Menu_Bar* menu = static_cast<Fl_Menu_Bar*>(w);
+  const Fl_Menu_Item* splitview_item = menu->mvalue();
+  if (splitview_item->value()) {
+    int h_split = app_tile->h()/2;
+    app_editor->size(app_tile->w(), h_split);
+    app_split_editor->resize(app_tile->x(), app_tile->y() + h_split,
+                             app_tile->w(), app_tile->h() - h_split);
+    app_split_editor->show();
+  } else {
+    app_editor->size(app_tile->w(), app_tile->h());
+    app_split_editor->resize(app_tile->x(), app_tile->y()+app_tile->h(),
+                             app_tile->w(), 0);
+    app_split_editor->hide();
+  }
+  app_tile->resizable(app_editor);
+  app_tile->init_sizes();
+  app_tile->redraw();
+}
+\endcode
 
-\image html editor.png "The completed editor window"
-\image latex editor.png "The completed editor window" width=12cm
 
-\section editor_advanced_features Advanced Features
+<!-- ----------------------------------------------------- -->
 
-Now that we've implemented the basic functionality, it is
-time to show off some of the advanced features of the
-Fl_Text_Editor widget.
+\section editor_syntax_highlighting Chapter 10: Syntax Highlighting
 
-\subsection editor_syntax Syntax Highlighting
+Chapter 10 adds a lot of code to implement "C" language syntax highlighting.
+Not all code is duplicated here in the documentation. Please check out
+`test/editor.cxx` for all the details.
 
 The Fl_Text_Editor widget supports highlighting
 of text with different fonts, colors, and sizes. The
@@ -667,18 +985,18 @@ You call the \p highlight_data() method to associate the
 style data and buffer with the text editor widget:
 
 \code
-Fl_Text_Buffer *stylebuf;
+Fl_Text_Buffer *app_style_buffer;
 
-w->editor->highlight_data(stylebuf, styletable,
-                          sizeof(styletable) / sizeof(styletable[0]),
-                          'A', style_unfinished_cb, 0);
+app_editor->highlight_data(app_style_buffer, styletable,
+                           sizeof(styletable) / sizeof(styletable[0]),
+                           'A', style_unfinished_cb, 0);
 \endcode
 
 Finally, you need to add a callback to the main text buffer so
 that changes to the text buffer are mirrored in the style buffer:
 
 \code
-textbuf->add_modify_callback(style_update, w->editor);
+app_text_buffer->add_modify_callback(style_update, app_editor);
 \endcode
 
 The \p style_update() function, like the \p change_cb()
@@ -707,7 +1025,7 @@ style_update(int        pos,          // I - Position of update
 
   // If this is just a selection change, just unselect the style buffer...
   if (nInserted == 0 && nDeleted == 0) {
-    stylebuf->unselect();
+    app_style_buffer->unselect();
     return;
   }
 
@@ -718,31 +1036,31 @@ style_update(int        pos,          // I - Position of update
     memset(style, 'A', nInserted);
     style[nInserted] = '\0';
 
-    stylebuf->replace(pos, pos + nDeleted, style);
+    app_style_buffer->replace(pos, pos + nDeleted, style);
     delete[] style;
   } else {
     // Just delete characters in the style buffer...
-    stylebuf->remove(pos, pos + nDeleted);
+    app_style_buffer->remove(pos, pos + nDeleted);
   }
 
   // Select the area that was just updated to avoid unnecessary
   // callbacks...
-  stylebuf->select(pos, pos + nInserted - nDeleted);
+  app_style_buffer->select(pos, pos + nInserted - nDeleted);
 
   // Re-parse the changed region; we do this by parsing from the
   // beginning of the line of the changed region to the end of
   // the line of the changed region...  Then we check the last
   // style character and keep updating if we have a multi-line
   // comment character...
-  start = textbuf->line_start(pos);
-  end   = textbuf->line_end(pos + nInserted - nDeleted);
-  text  = textbuf->text_range(start, end);
-  style = stylebuf->text_range(start, end);
+  start = app_text_buffer->line_start(pos);
+  end   = app_text_buffer->line_end(pos + nInserted - nDeleted);
+  text  = app_text_buffer->text_range(start, end);
+  style = app_style_buffer->text_range(start, end);
   last  = style[end - start - 1];
 
   style_parse(text, style, end - start);
 
-  stylebuf->replace(start, end, style);
+  app_style_buffer->replace(start, end, style);
   ((Fl_Text_Editor *)cbArg)->redisplay_range(start, end);
 
   if (last != style[end - start - 1]) {
@@ -751,13 +1069,13 @@ style_update(int        pos,          // I - Position of update
     free(text);
     free(style);
 
-    end   = textbuf->length();
-    text  = textbuf->text_range(start, end);
-    style = stylebuf->text_range(start, end);
+    end   = app_text_buffer->length();
+    text  = app_text_buffer->text_range(start, end);
+    style = app_style_buffer->text_range(start, end);
 
     style_parse(text, style, end - start);
 
-    stylebuf->replace(start, end, style);
+    app_style_buffer->replace(start, end, style);
     ((Fl_Text_Editor *)cbArg)->redisplay_range(start, end);
   }
 
@@ -779,10 +1097,10 @@ void
 style_parse(const char *text,
             char       *style,
             int        length) {
-  char             current;
-  int             col;
-  int             last;
-  char             buf[255],
+  char       current;
+  int        col;
+  int        last;
+  char       buf[255],
              *bufptr;
   const char *temp;