diff options
| author | Michael R Sweet <michael.r.sweet@gmail.com> | 1998-12-29 14:21:17 +0000 |
|---|---|---|
| committer | Michael R Sweet <michael.r.sweet@gmail.com> | 1998-12-29 14:21:17 +0000 |
| commit | 87dd7f0d23eba5c09e71ec6efeb34c6844f5e95f (patch) | |
| tree | ecd25b3fbecdd2d1c6abf106d0c94ac2b1e9926e /documentation/editor.html | |
| parent | 20adb6834b22523e9d1fecdb7bb8a117f7b6179a (diff) | |
Revised documentation files.
git-svn-id: file:///fltk/svn/fltk/trunk@177 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
Diffstat (limited to 'documentation/editor.html')
| -rw-r--r-- | documentation/editor.html | 603 |
1 files changed, 603 insertions, 0 deletions
diff --git a/documentation/editor.html b/documentation/editor.html new file mode 100644 index 000000000..60dca040c --- /dev/null +++ b/documentation/editor.html @@ -0,0 +1,603 @@ +<HTML> +<BODY> + +<H1 ALIGN=RIGHT>4 - Designing a Simple Text Editor</H1> + +This chapter takes you through the design of a simple FLTK-based text editor. + +<H2>Determining the Goals of the Text Editor</H2> + +Since this will be the first big project you'll be doing with FLTK, lets define +what we want our text editor to do: + +<ol> + <li>Menu_Bar/menus for all functions. + <li>Edit a single text file. + <li>Load from a file. + <li>Save to a file. + <li>Cut/copy/delete/paste functions. + <li>Search and replace functions. + <li>Keep track of when the file has been changed. +</ol> + +<H2>Designing the Main Window</H2> + +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: + +<ul><pre> +Fl_Window *window; + +window = new Fl_Window(640, 480, "Text Editor"); +</pre></ul> + +<H2>Variables</H2> + +Our text editor will need some global variables to keep track of things: + +<ul><pre> +Fl_Window *window; +Fl_Menu_Bar *menubar; +Fl_Multiline_Input *input; +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; + +int changed = 0; +char filename[1024] = ""; +char search[256] = ""; +</pre></ul> + +The <tt>window</tt> variable is our top-level window described previously. +We'll cover the other variables as we build the application. + +<H2>Menu_Bars and Menus</H2> + +The first goal requires us to use a menubar and menus that define +each function the editor needs to perform. The +<a href="#Fl_Menu_Item"><tt>Fl_Menu_Item</tt></a> structure is used to +define the menus and items in a menubar: + +<ul><pre> +Fl_Menu_Item menuitems[] = { + { "&File", 0, 0, 0, FL_SUBMENU }, + { "&New", FL_ALT + 'n', new_cb }, + { "&Open...", FL_ALT + 'o', open_cb, 0, FL_MENU_DIVIDER }, + { "&Save", FL_ALT + 's', save_cb }, + { "Save &As...", FL_ALT + FL_SHIFT + 's', saveas_cb, 0, FL_MENU_DIVIDER }, + { "&Quit", FL_ALT + 'q', quit_cb }, + { 0 }, + + { "&Edit", 0, 0, 0, FL_SUBMENU }, + { "&Undo", FL_ALT + 'z', undo_cb, 0, FL_MENU_DIVIDER }, + { "Cu&t", FL_ALT + 'x', cut_cb }, + { "&Copy", FL_ALT + 'c', copy_cb }, + { "&Paste", FL_ALT + 'v', paste_cb }, + { "&Delete", 0, delete_cb }, + { 0 }, + + { "&Search", 0, 0, 0, FL_SUBMENU }, + { "&Find...", FL_ALT + 'f', find_cb }, + { "F&ind Again", FL_ALT + 'g', find2_cb }, + { "&Replace...", FL_ALT + 'r', replace_cb }, + { "Re&place Again", FL_ALT + 't', replace2_cb }, + { 0 }, + + { 0 } +}; +</pre></ul> + +Once we have the menus defined we can create the <tt>Fl_Menu_Bar</tt> widget +and assign the menus to it with: + +<ul><pre> +Fl_Menu_Bar *menubar = new Fl_Menu_Bar(0, 0, 640, 30); +menubar->menu(menuitems); +</pre></ul> + +We'll define the callback functions later. + +<H2>Editing the Text</H2> + +To keep things simple our text editor will use the +<a href="#Fl_Multiline_Input"><tt>Fl_Multiline_Input</tt></a> widget to +edit the text: + +<ul><pre> +Fl_Multiline_Input *input = new Fl_Multiline_Input(0, 30, 640, 450); +</pre></ul> + +So that we can keep track of changes to the file, we also want to add a +"changed" callback: + +<ul><pre> +input->callback(changed_cb); +input->when(FL_WHEN_CHANGED); +</pre></ul> + +Finally, we want to use a mono-spaced font like <tt>FL_COURIER</tt>: + +<ul><pre> +input->textfont(FL_COURIER); +</pre></ul> + +<H2>The Replace Dialog</H2> + +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 <tt>Fl_Input</tt> widgets, the "replace all" and "cancel" +buttons are <tt>Fl_Button</tt> widgets, and the "replace next " button +is a <tt>Fl_Return_Button</tt> widget: + +<center><img src=editor-replace.gif></center> + +<ul><pre> +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"); +</pre></ul> + +<H2>Callbacks</H2> + +Now that we've defined the GUI components of our editor, we need to define +our callback functions. + +<H3>changed_cb()</H3> + +This function will be called whenever the user changes any text in the +<tt>input</tt> widget: + +<ul><pre> +void changed_cb(void) { + set_changed(1); +} +</pre></ul> + +The <tt>set_changed()</tt> 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. + +<H3>copy_cb()</H3> + +This callback function will call <a href="#Fl_Input.copy"> +<tt>input->copy()</tt></a> to copy the currently selected text to the +clipboard: + +<ul><pre> +void copy_cb(void) { + input->copy(); +} +</pre></ul> + +<H3>cut_cb()</H3> + +This callback function will call <a href="#Fl_Input_.copy"> +<tt>input->copy()</tt></a> to copy the currently selected text to the +clipboard and then <a href="#Fl_Input_.cut"><tt>input->cut()</tt></a> +to delete it: + +<ul><pre> +void cut_cb(void) { + input->copy(); + input->cut(); +} +</pre></ul> + +<H3>delete_cb()</H3> + +This callback function will call <a href="#Fl_Input_.cut"> +<tt>input->cut()</tt></a> to delete the selected text: + +<ul><pre> +void delete_cb(void) { + input->cut(); +} +</pre></ul> + +<H3>find_cb()</H3> + +This callback function asks for a search string using the +<a href="#fl_input"><tt>fl_input()</tt></a> convenience function and +then calls the <tt>find2_cb()</tt> function to find the string: + +<ul><pre> +void find_cb(void) { + const char *val; + + val = fl_input("Search String:", search); + if (val != NULL) { + // User entered a string - go find it! + strcpy(search, val); + find2_cb(); + } +} +</pre></ul> + +<H3>find2_cb()</H3> + +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: + +<ul><pre> +void find2_cb(void) { + const char *val, *found; + int pos; + + if (search[0] == '\0') { + // Search string is blank; get a new one... + find_cb(); + 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)); + } + else fl_alert("No occurrences of \'%s\' found!", search); +} +</pre></ul> + +If the search string cannot be found we use the <a href="#fl_alert"> +<tt>fl_alert()</tt></a> convenience function to display a message to +that effect. + +<H3>new_cb()</H3> + +This callback function will clear the input widget and current filename. +It also calls the <tt>check_save()</tt> function to give the user the +opportunity to save the current file first as needed: + +<ul><pre> +void new_cb(void) { + if (changed) + if (!check_save()) return; + + filename[0] = '\0'; + input->value(""); + set_changed(0); +} +</pre></ul> + +<H3>open_cb()</H3> + +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 <tt>check_save()</tt> function to give the user the +opportunity to save the current file first as needed: + +<ul><pre> +void open_cb(void) { + char *newfile; + + if (changed) + if (!check_save()) return; + + newfile = fl_file_chooser("Open File?", "*", filename); + if (newfile != NULL) load_file(newfile); +} +</pre></ul> + +We call the <tt>load_file()</tt> function to actually load the file. + +<H3>paste_cb()</H3> + +This callback function will send a FL_PASTE message to the <tt>input</tt> +widget using the <a href="#paste"><tt>Fl::paste()</tt> method: + +<ul><pre> +void paste_cb(void) { + Fl::paste(*input); +} +</pre></ul> + +<H3>quit_cb()</H3> + +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: + +<ul><pre> +void quit_cb(void) { + if (changed) + if (!check_save()) + return; + + window->hide(); +} +</pre></ul> + +<H3>replace_cb()</H3> + +The replace callback just shows the replace dialog: + +<ul><pre> +void replace_cb(void) { + replace_dlg->show(); +} +</pre></ul> + +<H3>replace2_cb()</H3> + +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: + +<ul><pre> +void replace2_cb() { + const char *find, *val, *found; + int pos; + + find = replace_find->value(); + if (find[0] == '\0') { + // Search string is blank; get a new one... + replace_dlg->show(); + return; + } + + val = input->value() + input->position(); + found = strstr(val, find); + + if (found != NULL) { + // Found a match; update the position and replace text... + pos = input->position() + found - val; + input->replace(pos, pos + strlen(find), replace_with->value()); + input->position(pos + strlen(replace_with->value())); + } + else fl_alert("No occurrences of \'%s\' found!", find); +} +</pre></ul> + +<H3>replall_cb()</H3> + +This callback will replace all occurences of the search string in the file: + +<ul><pre> +void replall_cb() { + const char *find, *val, *found; + int pos; + int times; + + find = replace_find->value(); + if (find[0] == '\0') { + // Search string is blank; get a new one... + replace_dlg->show(); + return; + } + + input->position(0); + times = 0; + + // Loop through the whole string + do { + val = input->value() + input->position(); + found = strstr(val, find); + + if (found != NULL) { + // Found a match; update the position and replace text... + times ++ + pos = input->position() + found - val; + input->replace(pos, pos + strlen(find), replace_with->value()); + input->position(pos + strlen(replace_with->value())); + } + } while (found != NULL); + + if (times > 0) fl_message("Replaced %d occurrences.", times); + else fl_alert("No occurrences of \'%s\' found!", find); +} +</pre></ul> + +<H3>replcan_cb()</H3> + +This callback just hides the replace dialog: + +<ul><pre> +void replcan_cb() { + replace_dlg->hide(); +} +</pre></ul> + +<H3>save_cb()</H3> + +This callback saves the current file. If the current filename is blank it +calls the "save as" callback: + +<ul><pre> +void save_cb(void) { + if (filename[0] == '\0') { + // No filename - get one! + saveas_cb(); + return; + } + else save_file(filename); +} +</pre></ul> + +The <tt>save_file()</tt> function saves the current file to the specified +filename. + +<H3>saveas_cb()</H3> + +This callback asks the user for a filename and saves the current file: + +<ul><pre> +void saveas_cb(void) { + char *newfile; + + newfile = fl_file_chooser("Save File As?", "*", filename); + if (newfile != NULL) save_file(newfile); +} +</pre></ul> + +The <tt>save_file()</tt> function saves the current file to the specified +filename. + +<H3>undo_cb()</H3> + +The undo callback just calls the <a href="#Fl_Input_.undo"> +<tt>undo()</tt></a> method: + +<ul><pre> +void undo_cb(void) { + input->undo(); +} +</pre></ul> + +<H2>Other Functions</H2> + +Now that we've defined the callback functions, we need our support functions +to make it all work: + +<H3>check_save()</H3> + +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: + +<ul><pre> +int check_save(void) { + if (!changed) return 1; + + if (fl_ask("The current file has not been saved.\n" + "Would you like to save it now?")) { + // Save the file... + save_cb(); + + return !changed; + } + else return (1); +} +</pre></ul> + +<H3>load_file()</H3> + +This function loads the specified file into the <tt>input</tt> widget: + +<ul><pre> +void load_file(char *newfile) { + FILE *fp; + char buffer[8192]; + int nbytes; + int pos; + + input->value(""); + + fp = fopen(newfile, "r"); + if (fp != NULL) { + // Was able to open file; let's read from it... + strcpy(filename, newfile); + pos = 0; + + while ((nbytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) { + input->replace(pos, pos, buffer, nbytes); + pos += nbytes; + } + + fclose(fp); + input->position(0); + set_changed(0); + } else { + // Couldn't open file - say so... + fl_alert("Unable to open \'%s\' for reading!"); + } +} +</pre></ul> + +When loading the file we use the <a href="#Fl_Input_.replace"> +<tt>input->replace()</tt> method to "replace" the text at the end of +the buffer. The <tt>pos</tt> variable keeps track of the end of the +buffer. + +<H3>save_file()</H3> + +This function saves the current buffer to the specified file: + +<ul><pre> +void save_file(char *newfile) { + FILE *fp; + + fp = fopen(newfile, "w"); + if (fp != NULL) { + // Was able to create file; let's write to it... + strcpy(filename, newfile); + + if (fwrite(input->value(), 1, input->size(), fp) < 1) { + fl_alert("Unable to write file!"); + fclose(fp); + return; + } + + fclose(fp); + set_changed(0); + } else { + // Couldn't open file - say so... + fl_alert("Unable to create \'%s\' for writing!"); + } +} +</pre></ul> + +<H3>set_changed()</H3> + +This function sets the <tt>changed</tt> variable and updates the window label +accordingly: + +<ul><pre> +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, '\\'); + + if (slash != NULL) strcpy(title, slash + 1); + else strcpy(title, filename); + } + + if (changed) strcat(title, " (modified)"); + + window->label(title); + } +} +</pre></ul> + +<H2>Compiling the Editor</H2> + +The complete source for our text editor can be found in the +<tt>test/editor.cxx</tt> 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: + +<ul><pre> +CC -o editor editor.cxx -lfltk -lXext -lX11 -lm +</pre></ul> + +As noted in <a href="#basics">Chapter 1</a>, you may need to include +compiler and linker options to tell them where to find the FLTK library. +Also, the <tt>CC</tt> command may also be called <tt>gcc</tt> or +<tt>c++</tt> on your system. + +<p>Congratulations, you've just built your own text editor! + +<H2>The Final Product</H2> + +The final editor window should look like the image below: + +<center><img src=editor.gif></center> + +</BODY> +</HTML> |