From 09daf20b81cdae78772f07c0af22a571d7cc73eb Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Thu, 29 Nov 2001 19:24:00 +0000 Subject: Documentation updates galore (up to chapter 7, still need to do chapter 8 and 9, tweek the appendices, and recapture the screenshots...) git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1786 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/editor.html | 673 +++++++++++++++++++++++++--------------------- 1 file changed, 361 insertions(+), 312 deletions(-) (limited to 'documentation/editor.html') diff --git a/documentation/editor.html b/documentation/editor.html index 236bc8162..565ba5ee0 100644 --- a/documentation/editor.html +++ b/documentation/editor.html @@ -1,25 +1,35 @@ - -

4 - Designing a Simple Text Editor

-This chapter takes you through the design of a simple FLTK-based text -editor. + + + +

4 - Designing a Simple Text Editor

+ +

This chapter takes you through the design of a simple +FLTK-based text editor. +

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: + +

Since this will be the first big project you'll be doing with FLTK, +lets define what we want our text editor to do: +

Menubar/menus for all functions.
Edit a single text file.
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.
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.

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: -

+
+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 EditorWindow:
+
+
 class EditorWindow : public Fl_Double_Window {
   public:
     EditorWindow(int w, int h, const char* t);
@@ -35,29 +45,31 @@ class EditorWindow : public Fl_Double_Window {
     Fl_Text_Editor     *editor;
     char               search[256];
 };
-
-
+

Variables

-Our text editor will need some global variables to keep track of -things: -

-int                changed = 0;
-char               filename[1024] = "";
-char               search[256] = "";
-Fl_Text_Buffer     *textbuf;
-

-The textbuf variable is the text editor buffer for our -window described previously. We'll cover the other variables as -we build the application. + +

Our text editor will need some global variables to keep track of +things: + +

+int            changed = 0;
+char           filename[256] = "";
+Fl_Text_Buffer *textbuf;
+

+ +

The textbuf variable is the text editor buffer for +our window class described previously. We'll cover the other +variables as we build the application.

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: -

+
+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:
+
+ Fl_Menu_Item menuitems[] = {
   { "&File",              0, 0, 0, FL_SUBMENU },
     { "&New File",        0, (Fl_Callback *)new_cb },
@@ -87,237 +99,262 @@ Fl_Menu_Item menuitems[] = {
 
   { 0 }
 };
-
-
-Once we have the menus defined we can create the Fl_Menu_Bar
-widget and assign the menus to it with: 
-
-+
+
+Once we have the menus defined we can create the
+Fl_Menu_Bar widget and assign the menus to it with:
+
+ Fl_Menu_Bar *m = new Fl_Menu_Bar(0, 0, 512, 30);
 m->copy(menuitems);
-
-
-We'll define the callback functions later. 
+

+ +

We'll define the callback functions later. +

Editing the Text

-To keep things simple our text editor will use the -Fl_Text_Editor -widget to edit the text: -

+
+To keep things simple our text editor will use the
+Fl_Text_Editor
+widget to edit the text:
+
+
 w->editor = new Fl_Text_Editor(0, 30, 512, 354);
 w->editor->buffer(textbuf);
-
-
-So that we can keep track of changes to the file, we also want to add 
-a "modify" callback: 
-
-+
+
+So that we can keep track of changes to the file, we also want to add
+a "modify" callback:
+
+ textbuf->add_modify_callback(changed_cb, w);
 textbuf->call_modify_callbacks();
-
-
-Finally, we want to use a mono-spaced font like FL_COURIER: 
-
-+
+
+Finally, we want to use a mono-spaced font like FL_COURIER:
+
+
 w->editor->textfont(FL_COURIER);
-
-
+

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: -

The search and 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:
+
+

+Figure 4-1: The search and replace dialog.
+
+ 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");
-
-
+

Callbacks

-Now that we've defined the GUI components of our editor, we need to -define our callback functions. + +

Now that we've defined the GUI components of our editor, we +need to define our callback functions.

changed_cb()

- This function will be called whenever the user changes any text in the -input widget: -

-void changed_cb(void) {
-  set_changed(1);
+
+This function will be called whenever the user changes any text in the
+editor widget:
+
+
+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();
 }
-
-
- The set_changed() function is one that we will write to set 
-the changed status on the current file.  We're doing it this way 
-because some of the other callbacks will set the changed status to 0, 
-and also because we want to show the changed status in the window's 
-title bar. 
+

+ +

The 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. +

copy_cb()

- This callback function will call -input->copy() to copy the currently selected text to the -clipboard: -

-void copy_cb(void) {
-  input->copy();
+
+This callback function will call kf_copy()
+to copy the currently selected text to the clipboard:
+
++void copy_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  Fl_Text_Editor::kf_copy(0, e->editor);
 }
-
-
+

cut_cb()

- This callback function will call -input->copy() to copy the currently selected text to the -clipboard and then input->cut() - to delete it: -

-void cut_cb(void) {
-  input->copy();
-  input->cut();
+
+This callback function will call kf_cut()
+to cut the currently selected text to the clipboard:
+
++void cut_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  Fl_Text_Editor::kf_cut(0, e->editor);
 }
-
-
+

delete_cb()

- This callback function will call -input->cut() to delete the selected text: -

-void delete_cb(void) {
-  input->cut();
+
+This callback function will call remove_selection()
+to delete the currently selected text to the clipboard:
+
++void delete_cb(Fl_Widget*, void* v) {
+  textbuf->remove_selection();
 }
-
-
+

find_cb()

- This callback function asks for a search string using the -fl_input() convenience function and then calls the -find2_cb() function to find the string: -

-void find_cb(void) {
+
+This callback function asks for a search string using the fl_input()
+convenience function and then calls the find2_cb()
+function to find the string:
+
+
+void find_cb(Fl_Widget* w, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
   const char *val;
 
-  val = fl_input("Search String:", search);
+  val = fl_input("Search String:", e->search);
   if (val != NULL) {
     // User entered a string - go find it!
-    strcpy(search, val);
-    find2_cb();
+    strcpy(e->search, val);
+    find2_cb(w, v);
   }
-}
-
-
+

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: -

-void find2_cb(void) {
-  const char *val, *found;
-  int pos;
-
-  if (search[0] == '\0') {
+
+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:
+
+
+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();
+    find_cb(w, v);
     return;
   }
 
-  val   = input->value() + input->mark();
-  found = strstr(val, search);
-
-  if (found != NULL) {
-    // Found a match; update the position and mark...
-    pos = input->mark() + found - val;
-    input->position(pos, pos + strlen(search));
+  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();
   }
-  else fl_alert("No occurrences of \'%s\' found!", search);
+  else fl_alert("No occurrences of \'%s\' found!", e->search);
 }
-
-
- If the search string cannot be found we use the 
-fl_alert() convenience function to display a message to that 
-effect. 
+

+ +

If the search string cannot be found we use the fl_alert() +convenience function to display a message to that effect. +

new_cb()

- This callback function will clear the input widget and current -filename. It also calls the check_save() function to give the -user the opportunity to save the current file first as needed: -

-void new_cb(void) {
-  if (changed)
-    if (!check_save()) return;
+This callback function will clear the editor widget and current
+filename. It also calls the check_save() function to give the
+user the opportunity to save the current file first as needed:
+
+
+void new_cb(Fl_Widget*, void*) {
+  if (!check_save()) return;
 
   filename[0] = '\0';
-  input->value("");
-  set_changed(0);
+  textbuf->select(0, textbuf->length());
+  textbuf->remove_selection();
+  changed = 0;
+  textbuf->call_modify_callbacks();
 }
-
-
+

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 check_save() function to give the user the -opportunity to save the current file first as needed: -

-void open_cb(void) {
-  char *newfile;
 
-  if (changed)
-    if (!check_save()) return;
+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 check_save() function to give the user the
+opportunity to save the current file first as needed:
+
+
+void open_cb(Fl_Widget*, void*) {
+  if (!check_save()) return;
 
-  newfile = fl_file_chooser("Open File?", "*", filename);
-  if (newfile != NULL) load_file(newfile);
+  char *newfile = fl_file_chooser("Open File?", "*", filename);
+  if (newfile != NULL) load_file(newfile, -1);
 }
-
-
- We call the load_file() function to actually load the file. 
+

+ +

We call the load_file() function to actually load the file. +

paste_cb()

- This callback function will send a FL_PASTE message to the input - widget using the Fl::paste() - method: -

-void paste_cb(void) {
-  Fl::paste(*input);
+
+This callback function will call kf_paste()
+to paste the clipboard at the current position:
+
++void paste_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  Fl_Text_Editor::kf_paste(0, e->editor);
 }
-
-
+

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 hides -the main window: -

-void quit_cb(void) {
-  if (changed)
-    if (!check_save())
-      return;
-
-  window->hide();
+
+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:
+
+
+void quit_cb(Fl_Widget*, void*) {
+  if (changed && !check_save())
+    return;
+
+  exit(0);
 }
-
-
+

replace_cb()

- The replace callback just shows the replace dialog: -

+
+The replace callback just shows the replace dialog:
+
+
 void replace_cb(Fl_Widget*, void* v) {
   EditorWindow* e = (EditorWindow*)v;
   e->replace_dlg->show();
 }
-
-
+

replace2_cb()

-This callback will replace the next occurence of the replacement -string. If nothing has been entered for the replacement string, then -the replace dialog is displayed instead: -

+
+This callback will replace the next occurence of the replacement
+string. If nothing has been entered for the replacement string, then
+the replace dialog is displayed instead:
+
+
 void replace2_cb(Fl_Widget*, void* v) {
   EditorWindow* e = (EditorWindow*)v;
   const char *find = e->replace_find->value();
@@ -345,13 +382,14 @@ void replace2_cb(Fl_Widget*, void* v) {
   }
   else fl_alert("No occurrences of \'%s\' found!", find);
 }
-
-
+

replall_cb()

-This callback will replace all occurences of the search string in the -file: -

+
+This callback will replace all occurences of the search
+string in the file:
+
+
 void replall_cb(Fl_Widget*, void* v) {
   EditorWindow* e = (EditorWindow*)v;
   const char *find = e->replace_find->value();
@@ -388,23 +426,25 @@ void replall_cb(Fl_Widget*, void* v) {
   if (times) fl_message("Replaced %d occurrences.", times);
   else fl_alert("No occurrences of \'%s\' found!", find);
 }
-
-
+

replcan_cb()

-This callback just hides the replace dialog: -

+
+This callback just hides the replace dialog:
+
+
 void replcan_cb(Fl_Widget*, void* v) {
   EditorWindow* e = (EditorWindow*)v;
   e->replace_dlg->hide();
 }
-
-
+

save_cb()

-This callback saves the current file. If the current filename is -blank it calls the "save as" callback: -

+
+This callback saves the current file.  If the current filename is
+blank it calls the "save as" callback:
+
+
 void save_cb(void) {
   if (filename[0] == '\0') {
     // No filename - get one!
@@ -413,42 +453,38 @@ void save_cb(void) {
   }
   else save_file(filename);
 }
-
-
- The save_file() function saves the current file to the 
-specified filename. 
+

+ +

The save_file() function saves the current file to the +specified filename. +

saveas_cb()

- This callback asks the user for a filename and saves the current file: -

+
+This callback asks the user for a filename and saves the current file:
+
+
 void saveas_cb(void) {
   char *newfile;
 
   newfile = fl_file_chooser("Save File As?", "*", filename);
   if (newfile != NULL) save_file(newfile);
 }
-
-
- The save_file() function saves the current file to the 
-specified filename. 
-undo_cb()
- The undo callback just calls the 
-undo() method: 
-
--void undo_cb(void) {
-  input->undo();
-}
-
-
+

+ +

The save_file() function saves the current file to the +specified filename. +

Other Functions

- Now that we've defined the callback functions, we need our support -functions to make it all work: + +

Now that we've defined the callback functions, we need our support +functions to make it all work: +

check_save()

- 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: -

+
+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:
+
+
 int check_save(void) {
   if (!changed) return 1;
 
@@ -463,12 +499,13 @@ int check_save(void) {
 
   return (r == 2) ? 1 : 0;
 }
-
-
+

load_file()

- This function loads the specified file into the input widget: -

+
+This function loads the specified file into the textbuf class:
+
+
 int loading = 0;
 void load_file(char *newfile, int ipos) {
   loading = 1;
@@ -485,15 +522,19 @@ void load_file(char *newfile, int ipos) {
   loading = 0;
   textbuf->call_modify_callbacks();
 }
-
-
-When loading the file we use the
-loadfile()
-method to "replace" the text in the buffer.
+

+ +

When loading the file we use the loadfile() +method to "replace" the text in the buffer, or the insertfile() +method to insert text in the buffer from the named file. +

save_file()

-This function saves the current buffer to the specified file: -

+
+This function saves the current buffer to the specified file:
+
+
 void save_file(char *newfile) {
   if (textbuf->savefile(newfile))
     fl_alert("Error writing to file \'%s\':\n%s.", newfile, strerror(errno));
@@ -502,52 +543,60 @@ void save_file(char *newfile) {
   changed = 0;
   textbuf->call_modify_callbacks();
 }
-
-
-set_changed()
- This function sets the changed variable and updates the 
-window label accordingly: 
-
--void set_changed(int c) {
-  if (c != changed) {
-    char title[1024];
-    char *slash;
-
-    changed = c;
+
 
-    if (filename[0] == '\0') strcpy(title, "Untitled");
-    else {
-      slash = strrchr(filename, '/');
-      if (slash == NULL) slash = strrchr(filename, '\\');
+set_title()
 
-      if (slash != NULL) strcpy(title, slash + 1);
-      else strcpy(title, filename);
-    }
+This function checks the changed variable and updates the
+window label accordingly:
+
+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);
+  }
 
-    if (changed) strcat(title, " (modified)");
+  if (changed) strcat(title, " (modified)");
 
-    window->label(title);
-  }
+  w->label(title);
 }
-
-
+

Compiling the Editor

- The complete source for our text editor can be found in the -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: -

+ +

The complete source for our text editor can be found in the 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: + +

 CC -o editor editor.cxx -lfltk -lXext -lX11 -lm
-

- As noted in Chapter 1, you may need to -include compiler and linker options to tell them where to find the FLTK +

+ +

or by using the fltk-config script with: + +

+fltk-config --compile editor.cxx
+

+ +

As noted in Chapter 1, you may need to +include compiler and linker options to tell them where to find the FLTK library. Also, the CC command may also be called gcc - or c++ on your system. -

Congratulations, you've just built your own text editor!

+or c++ on your system. + +

Congratulations, you've just built your own text editor!

The Final Product

- The final editor window should look like the image on the next page. -

The completed editor window.

- + +The final editor window should look like the image in Figure 4-2. + +

The completed editor window.
+Figure 4-2: The completed editor window

+ + + -- cgit v1.2.3