From 8416a4012ecb985d150fad566659cf59ee1dc3aa Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sat, 13 Sep 2008 15:55:32 +0000 Subject: Doxygen documentation - WP12 and WP13 - first step. Converted the descriptive chapters of the html docs to doxygen format and modified index.dox accordingly. This checkin includes only trivial reformatting, no major rewriting. Added a chapter "Migrating Code from FLTK 1.1 to 1.3". All links on the main page are working now. Todo: - Check doxygen error messages, rewrite pages (html tags, contents). - Fill the new "Migrating..." chapter. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6224 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/editor.dox | 905 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 905 insertions(+) create mode 100644 documentation/editor.dox (limited to 'documentation/editor.dox') diff --git a/documentation/editor.dox b/documentation/editor.dox new file mode 100644 index 000000000..260c7a887 --- /dev/null +++ b/documentation/editor.dox @@ -0,0 +1,905 @@ +/** + + \page 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: + +

    + +
  1. Provide a menubar/menus for all functions.
    2. +
  2. Edit a single text file, possibly with multiple views.
    3. +
  3. Load from a file.
    4. +
  4. Save to a file.
    5. +
  5. Cut/copy/delete/paste functions.
    6. +
  6. Search and replace functions.
    7. +
  7. Keep track of when the file has been changed.
    8. + +
+ + + +

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

+ +

Variables

+ +

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

+ +

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:

+ + + +

Once we have the menus defined we can create the +Fl_Menu_Bar widget and assign the menus to it with:

+ + + +

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

+ +

So that we can keep track of changes to the file, we also want to add +a "modify" callback:

+ + + +

Finally, we want to use a mono-spaced font like 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.
+Figure 4-1: The search and replace dialog.

+ + + +

Callbacks

+ +

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

+ +

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 kf_copy() +to copy the currently selected text to the clipboard:

+ + + +

cut_cb()

+ +

This callback function will call kf_cut() +to cut the currently selected text to the clipboard:

+ + + +

delete_cb()

+ +

This callback function will call remove_selection() +to delete the currently selected text to the clipboard:

+ + + +

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

+ +

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

+ +

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

+ +

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

+ +

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

paste_cb()

+ +

This callback function will call kf_paste() +to paste the clipboard at the current position:

+ + + +

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

+ +

replace_cb()

+ +

The replace callback just shows the replace dialog: + +

+ +

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

+ +

replall_cb()

+ +

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

+ +

replcan_cb()

+ +

This callback just hides the replace dialog: + +

+ +

save_cb()

+ +

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

+ +

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

+ +

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

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

+ +

load_file()

+ +

This function loads the specified file into the textbuf class: + +

+ +

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

+ +

set_title()

+ +

This function checks the changed variable and updates the +window label accordingly: +

+ +

The main() Function

+ +

Once we've created all of the support functions, the only thing left +is to tie them all together with the main() function. +The 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: + +

+ +

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

+ +

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

+ +

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!

+ +

The Final Product

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

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

+ +

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

Syntax Highlighting

+ +

The Fl_Text_Editor widget supports highlighting +of text with different fonts, colors, and sizes. The +implementation is based on the excellent NEdit text editor core, which +uses a parallel "style" buffer which tracks the font, color, and +size of the text that is drawn. + +

Styles are defined using the +Fl_Text_Display::Style_Table_Entry structure +defined in <FL/Fl_Text_Display.H>: + +

+ +

The color member sets the color for the text, +the font member sets the FLTK font index to use, +and the size member sets the pixel size of the +text. The attr member is currently not used. + +

For our text editor we'll define 7 styles for plain code, +comments, keywords, and preprocessor directives: + +

+ +

You'll notice that the comments show a letter next to each +style - each style in the style buffer is referenced using a +character starting with the letter 'A'. + +

You call the highlight_data() method to associate the +style data and buffer with the text editor widget: + +

+ +

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

+ +

The style_update() function, like the change_cb() +function described earlier, is called whenever text is added or removed from +the text buffer. It mirrors the changes in the style buffer and then updates +the style data as necessary: + +

+ +

The style_parse() function scans a copy of the +text in the buffer and generates the necessary style characters +for display. It assumes that parsing begins at the start of a line: + +

+ +*/ -- cgit v1.2.3